From c919bb5bc493d773be4b91dc2336f765039b4e23 Mon Sep 17 00:00:00 2001
From: Nuno Maduro <enunomaduro@gmail.com>
Date: Tue, 14 May 2024 01:58:44 +0100
Subject: [PATCH] feat: adds `pest` function

---
 composer.json                      |  1 +
 resources/base-phpunit.xml         | 31 ++++++++++
 src/Configuration.php              | 71 ++++++++++++++++++++++
 src/Configuration/Theme.php        | 23 +++++++
 src/Functions.php                  | 11 ++++
 src/PendingCalls/UsesCall.php      | 29 ++++++++-
 src/Plugins/Configuration.php      | 96 ++++++++++++++++++++++++++++++
 tests/.snapshots/success.txt       |  8 ++-
 tests/Pest.php                     | 19 +++---
 tests/Unit/Configuration/In.php    |  9 +++
 tests/Unit/Configuration/Theme.php |  7 +++
 tests/Visual/Parallel.php          |  2 +-
 12 files changed, 293 insertions(+), 14 deletions(-)
 create mode 100644 resources/base-phpunit.xml
 create mode 100644 src/Configuration.php
 create mode 100644 src/Configuration/Theme.php
 create mode 100644 src/Plugins/Configuration.php
 create mode 100644 tests/Unit/Configuration/In.php
 create mode 100644 tests/Unit/Configuration/Theme.php

diff --git a/composer.json b/composer.json
index b5f6eeee..c3d7bf79 100644
--- a/composer.json
+++ b/composer.json
@@ -91,6 +91,7 @@
     "extra": {
         "pest": {
             "plugins": [
+                "Pest\\Plugins\\Configuration",
                 "Pest\\Plugins\\Bail",
                 "Pest\\Plugins\\Cache",
                 "Pest\\Plugins\\Coverage",
diff --git a/resources/base-phpunit.xml b/resources/base-phpunit.xml
new file mode 100644
index 00000000..79d106e6
--- /dev/null
+++ b/resources/base-phpunit.xml
@@ -0,0 +1,31 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:noNamespaceSchemaLocation="vendor/phpunit/phpunit/phpunit.xsd"
+         bootstrap="vendor/autoload.php"
+         colors="true"
+>
+    <testsuites>
+        <testsuite name="Default">
+            <directory>tests/</directory>
+        </testsuite>
+    </testsuites>
+    <source>
+        <include>
+            <directory>app</directory>
+            <directory>src</directory>
+        </include>
+    </source>
+    <php>
+        <env name="APP_ENV" value="testing"/>
+        <env name="APP_MAINTENANCE_DRIVER" value="file"/>
+        <env name="BCRYPT_ROUNDS" value="4"/>
+        <env name="CACHE_STORE" value="array"/>
+        <!-- <env name="DB_CONNECTION" value="sqlite"/> -->
+        <!-- <env name="DB_DATABASE" value=":memory:"/> -->
+        <env name="MAIL_MAILER" value="array"/>
+        <env name="PULSE_ENABLED" value="false"/>
+        <env name="QUEUE_CONNECTION" value="sync"/>
+        <env name="SESSION_DRIVER" value="array"/>
+        <env name="TELESCOPE_ENABLED" value="false"/>
+    </php>
+</phpunit>
diff --git a/src/Configuration.php b/src/Configuration.php
new file mode 100644
index 00000000..16d321a4
--- /dev/null
+++ b/src/Configuration.php
@@ -0,0 +1,71 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Pest;
+
+use Pest\PendingCalls\UsesCall;
+use Pest\Support\Backtrace;
+
+/**
+ * @internal
+ */
+final class Configuration
+{
+    /**
+     * The instance of the configuration.
+     */
+    private static ?Configuration $instance = null;
+
+    /**
+     * Gets the instance of the configuration.
+     */
+    public static function getInstance(): Configuration
+    {
+        return self::$instance ??= new Configuration(
+            Backtrace::file(),
+        );
+    }
+
+    /**
+     * Creates a new configuration instance.
+     */
+    private function __construct(
+        private readonly string $filename,
+    ) {
+    }
+
+    /**
+     * Gets the configuration of a certain folder.
+     */
+    public function in(string ...$targets): UsesCall
+    {
+        return (new UsesCall($this->filename, []))->in(...$targets);
+    }
+
+    /**
+     * Depending on where is called, it will extend the given classes and traits globally or locally.
+     */
+    public function extend(string ...$classAndTraits): UsesCall
+    {
+        return (new UsesCall($this->filename, array_values($classAndTraits)))
+            ->in($this->filename)
+            ->extend(...$classAndTraits);
+    }
+
+    /**
+     * Depending on where is called, it will extend the given classes and traits globally or locally.
+     */
+    public function use(string ...$classAndTraits): UsesCall
+    {
+        return $this->extend(...$classAndTraits);
+    }
+
+    /**
+     * Gets the theme configuration.
+     */
+    public function theme(): Configuration\Theme
+    {
+        return new Configuration\Theme();
+    }
+}
diff --git a/src/Configuration/Theme.php b/src/Configuration/Theme.php
new file mode 100644
index 00000000..6e7321b3
--- /dev/null
+++ b/src/Configuration/Theme.php
@@ -0,0 +1,23 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Pest\Configuration;
+
+use NunoMaduro\Collision\Adapters\Phpunit\Printers\DefaultPrinter;
+
+/**
+ * @internal
+ */
+final readonly class Theme
+{
+    /**
+     * Sets the theme to compact.
+     */
+    public function compact(): self
+    {
+        DefaultPrinter::compact(true);
+
+        return $this;
+    }
+}
diff --git a/src/Functions.php b/src/Functions.php
index 34595794..353b08c6 100644
--- a/src/Functions.php
+++ b/src/Functions.php
@@ -3,6 +3,7 @@
 declare(strict_types=1);
 
 use Pest\Concerns\Expectable;
+use Pest\Configuration;
 use Pest\Exceptions\AfterAllWithinDescribe;
 use Pest\Exceptions\BeforeAllWithinDescribe;
 use Pest\Expectation;
@@ -108,6 +109,16 @@ if (! function_exists('uses')) {
     }
 }
 
+if (! function_exists('pest')) {
+    /**
+     * Creates a new Pest configuration instance.
+     */
+    function pest(): Configuration
+    {
+        return Configuration::getInstance();
+    }
+}
+
 if (! function_exists('test')) {
     /**
      * Adds the given closure as a test. The first argument
diff --git a/src/PendingCalls/UsesCall.php b/src/PendingCalls/UsesCall.php
index 2cd33efb..dc48ac64 100644
--- a/src/PendingCalls/UsesCall.php
+++ b/src/PendingCalls/UsesCall.php
@@ -48,11 +48,14 @@ final class UsesCall
      */
     public function __construct(
         private readonly string $filename,
-        private readonly array $classAndTraits
+        private array $classAndTraits
     ) {
         $this->targets = [$filename];
     }
 
+    /**
+     * @deprecated Use `pest()->theme()->compact()` instead.
+     */
     public function compact(): self
     {
         DefaultPrinter::compact(true);
@@ -60,11 +63,31 @@ final class UsesCall
         return $this;
     }
 
+    /**
+     * Specifies the class or traits to use.
+     *
+     * @alias extend
+     */
+    public function use(string ...$classAndTraits): self
+    {
+        return $this->extend(...$classAndTraits);
+    }
+
+    /**
+     * Specifies the class or traits to use.
+     */
+    public function extend(string ...$classAndTraits): self
+    {
+        $this->classAndTraits = array_values($classAndTraits);
+
+        return $this;
+    }
+
     /**
      * The directories or file where the
      * class or traits should be used.
      */
-    public function in(string ...$targets): void
+    public function in(string ...$targets): self
     {
         $targets = array_map(function (string $path): string {
             $startChar = DIRECTORY_SEPARATOR;
@@ -92,6 +115,8 @@ final class UsesCall
 
             return $accumulator;
         }, []);
+
+        return $this;
     }
 
     /**
diff --git a/src/Plugins/Configuration.php b/src/Plugins/Configuration.php
new file mode 100644
index 00000000..646d200a
--- /dev/null
+++ b/src/Plugins/Configuration.php
@@ -0,0 +1,96 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Pest\Plugins;
+
+use DOMDocument;
+use Pest\Contracts\Plugins\HandlesArguments;
+use Pest\Contracts\Plugins\Terminable;
+use Pest\Plugins\Concerns\HandleArguments;
+use PHPUnit\TextUI\CliArguments\Builder as CliConfigurationBuilder;
+use PHPUnit\TextUI\CliArguments\XmlConfigurationFileFinder;
+
+/**
+ * @internal
+ */
+final class Configuration implements HandlesArguments, Terminable
+{
+    use HandleArguments;
+
+    /**
+     * The base PHPUnit file.
+     */
+    public const BASE_PHPUNIT_FILE = __DIR__
+        .DIRECTORY_SEPARATOR
+        .'..'
+        .DIRECTORY_SEPARATOR
+        .'..'
+        .DIRECTORY_SEPARATOR
+        .'resources/base-phpunit.xml';
+
+    /**
+     * Handles the arguments, adding the cache directory and the cache result arguments.
+     */
+    public function handleArguments(array $arguments): array
+    {
+        if ($this->hasArgument('--configuration', $arguments) || $this->hasCustomConfigurationFile()) {
+            return $arguments;
+        }
+
+        $arguments = $this->pushArgument('--configuration', $arguments);
+
+        return $this->pushArgument((string) realpath($this->fromGeneratedConfigurationFile()), $arguments);
+    }
+
+    /**
+     * Get the configuration file from the generated configuration file.
+     */
+    private function fromGeneratedConfigurationFile(): string
+    {
+        $path = $this->getTempPhpunitXmlPath();
+        if (file_exists($path)) {
+            unlink($path);
+        }
+
+        $doc = new DOMDocument();
+        $doc->load(self::BASE_PHPUNIT_FILE);
+
+        $contents = $doc->saveXML();
+
+        assert(is_int(file_put_contents($path, $contents)));
+
+        return $path;
+    }
+
+    /**
+     * Check if the configuration file is custom.
+     */
+    private function hasCustomConfigurationFile(): bool
+    {
+        $cliConfiguration = (new CliConfigurationBuilder)->fromParameters([]);
+        $configurationFile = (new XmlConfigurationFileFinder)->find($cliConfiguration);
+
+        return is_string($configurationFile);
+    }
+
+    /**
+     * Get the temporary phpunit.xml path.
+     */
+    private function getTempPhpunitXmlPath(): string
+    {
+        return getcwd().'/.pest.xml';
+    }
+
+    /**
+     * Terminates the plugin.
+     */
+    public function terminate(): void
+    {
+        $path = $this->getTempPhpunitXmlPath();
+
+        if (file_exists($path)) {
+            unlink($path);
+        }
+    }
+}
diff --git a/tests/.snapshots/success.txt b/tests/.snapshots/success.txt
index 1f5012b6..6a99b1d9 100644
--- a/tests/.snapshots/success.txt
+++ b/tests/.snapshots/success.txt
@@ -1272,6 +1272,12 @@
   ✓ it allows global uses
   ✓ it allows multiple global uses registered in the same path
 
+   PASS  Tests\Unit\Configuration\In
+  ✓ it proxies to uses call
+
+   PASS  Tests\Unit\Configuration\Theme
+  ✓ it creates a theme instance
+
    PASS  Tests\Unit\Console\Help
   ✓ it outputs the help information when --help is used
 
@@ -1455,4 +1461,4 @@
    WARN  Tests\Visual\Version
   - visual snapshot of help command output
 
-  Tests:    2 deprecated, 4 warnings, 5 incomplete, 2 notices, 13 todos, 24 skipped, 1040 passed (2561 assertions)
\ No newline at end of file
+  Tests:    2 deprecated, 4 warnings, 5 incomplete, 2 notices, 13 todos, 24 skipped, 1042 passed (2563 assertions)
\ No newline at end of file
diff --git a/tests/Pest.php b/tests/Pest.php
index 2236c650..f7cf1c9b 100644
--- a/tests/Pest.php
+++ b/tests/Pest.php
@@ -7,20 +7,21 @@ error_reporting(E_ALL);
 
 $GLOBALS['__PEST_INTERNAL_TEST_SUITE'] = true;
 
-uses(CustomTestCaseInSubFolder::class)->in('PHPUnit/CustomTestCaseInSubFolders/SubFolder/SubFolder');
+pest()->in('PHPUnit/CustomTestCaseInSubFolders/SubFolder/SubFolder')->use(CustomTestCaseInSubFolder::class);
 
 // test case for all the directories inside PHPUnit/GlobPatternTests/SubFolder/
-uses(CustomTestCase::class)->in('PHPUnit/GlobPatternTests/SubFolder/*/');
+pest()->in('PHPUnit/GlobPatternTests/SubFolder/*')->extend(CustomTestCase::class);
 
 // test case for all the files that end with AsPattern.php inside PHPUnit/GlobPatternTests/SubFolder2/
-uses(CustomTestCase::class)->in('PHPUnit/GlobPatternTests/SubFolder2/*AsPattern.php');
+pest()->in('PHPUnit/GlobPatternTests/SubFolder2/*AsPattern.php')->use(CustomTestCase::class);
 
-uses()->group('integration')->in('Visual');
+pest()->in('Visual')->group('integration');
 
 // NOTE: global test value container to be mutated and checked across files, as needed
 $_SERVER['globalHook'] = (object) ['calls' => (object) ['beforeAll' => 0, 'afterAll' => 0]];
 
-uses()
+pest()
+    ->in('Hooks')
     ->beforeEach(function () {
         $this->baz = 0;
     })
@@ -34,10 +35,9 @@ uses()
     ->afterAll(function () {
         $_SERVER['globalHook']->afterAll = 0;
         $_SERVER['globalHook']->calls->afterAll++;
-    })
-    ->in('Hooks');
+    });
 
-uses()
+pest()->in('Hooks')
     ->beforeEach(function () {
         expect($this)
             ->toHaveProperty('baz')
@@ -69,8 +69,7 @@ uses()
             ->toBe(0);
 
         $_SERVER['globalHook']->afterAll = 1;
-    })
-    ->in('Hooks');
+    });
 
 function helper_returns_string()
 {
diff --git a/tests/Unit/Configuration/In.php b/tests/Unit/Configuration/In.php
new file mode 100644
index 00000000..5dd26100
--- /dev/null
+++ b/tests/Unit/Configuration/In.php
@@ -0,0 +1,9 @@
+<?php
+
+use Pest\PendingCalls\UsesCall;
+
+it('proxies to uses call', function () {
+    $in = pest()->in();
+
+    expect($in)->toBeInstanceOf(UsesCall::class);
+});
diff --git a/tests/Unit/Configuration/Theme.php b/tests/Unit/Configuration/Theme.php
new file mode 100644
index 00000000..7cebcc16
--- /dev/null
+++ b/tests/Unit/Configuration/Theme.php
@@ -0,0 +1,7 @@
+<?php
+
+it('creates a theme instance', function () {
+    $theme = pest()->theme();
+
+    expect($theme)->toBeInstanceOf(Pest\Configuration\Theme::class);
+});
diff --git a/tests/Visual/Parallel.php b/tests/Visual/Parallel.php
index 1a701fb5..28f83d63 100644
--- a/tests/Visual/Parallel.php
+++ b/tests/Visual/Parallel.php
@@ -16,7 +16,7 @@ $run = function () {
 
 test('parallel', function () use ($run) {
     expect($run('--exclude-group=integration'))
-        ->toContain('Tests:    2 deprecated, 4 warnings, 5 incomplete, 2 notices, 13 todos, 19 skipped, 1026 passed (2529 assertions)')
+        ->toContain('Tests:    2 deprecated, 4 warnings, 5 incomplete, 2 notices, 13 todos, 19 skipped, 1028 passed (2531 assertions)')
         ->toContain('Parallel: 3 processes');
 })->skipOnWindows();