docs: updates changelog

Update PHPUnit dependency version

CHANGELOG.md

@@ -4,6 +4,31 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](http://keepachangelog.com/)
 and this project adheres to [Semantic Versioning](http://semver.org/).
 
+## [v0.3.15 (2020-12-04)](https://github.com/pestphp/pest/compare/v0.3.14...v0.3.15)
+### Added
+- Support for PHPUnit 9.5.0 ([#234](https://github.com/pestphp/pest/pull/234))
+- Support for extending expectation API ([#232](https://github.com/pestphp/pest/pull/232))
+
+### Fixed
+- Static analysis while using string as key for datasets ([#233](https://github.com/pestphp/pest/pull/233))
+
+## [v0.3.14 (2020-11-28)](https://github.com/pestphp/pest/compare/v0.3.13...v0.3.14)
+### Added
+- `pest:dusk` command ([#223](https://github.com/pestphp/pest/pull/223))
+- Better feedback on errors in `toMatchArray` and `toMatchObject` ([#231](https://github.com/pestphp/pest/pull/231))
+
+## [v0.3.13 (2020-11-23)](https://github.com/pestphp/pest/compare/v0.3.12...v0.3.13)
+### Added
+- `toMatchArray` expectation ([7bea51f](https://github.com/pestphp/pest/commit/7bea51fe09dd2eca7093e4c34cf2dab2e8d39fa5), [3fd24d9](https://github.com/pestphp/pest/commit/3fd24d96d3145dcebdb0aab40aa8b76faa8b6979))
+- Add Pest options to `--help` output ([#217](https://github.com/pestphp/pest/pull/217))
+
+### Fixed
+- Resolve issue with name resolution in `depends()` ([#216](https://github.com/pestphp/pest/pull/216))
+
+## [v0.3.12 (2020-11-11)](https://github.com/pestphp/pest/compare/v0.3.11...v0.3.12)
+### Added
+- Add support for PHPUnit 9.4.3 ([#219](https://github.com/pestphp/pest/pull/219))
+
 ## [v0.3.11 (2020-11-09)](https://github.com/pestphp/pest/compare/v0.3.10...v0.3.11)
 ### Changed
 - Improved the exception output for the TeamCity printer (usage with phpstorm plugin) ([#215](https://github.com/pestphp/pest/pull/215))

RELEASE.md

@@ -0,0 +1,16 @@
+# Release process
+
+When releasing a new version of Pest there are some checks and updates that need to be done:
+
+- Clear your local repository with: `git add . && git reset --hard && git checkout master` 
+- On the GitHub repository, check the contents of [github.com/pestphp/pest/compare/{latest_version}...master](https://github.com/pestphp/pest/compare/{latest_version}...master) and update the [changelog](CHANGELOG.md) file with the main changes for this release
+- Update the version number in [src/Pest.php](src/Pest.php)
+- Run the tests locally using: `composer test`
+- Commit the CHANGELOG and Pest file with the message: `git commit -m "docs: update changelog"`
+- Push the changes to GitHub
+- Check that the CI is passing as expected: [github.com/pestphp/pest/actions](https://github.com/pestphp/pest/actions)
+- Tag and push the tag with `git tag vX.X.X && git push --tags`
+
+### Plugins
+
+Plugins should be versioned using the same major (or minor for `0.x` releases) version as Pest core.

composer.json

@@ -22,7 +22,7 @@
         "pestphp/pest-plugin": "^0.3",
         "pestphp/pest-plugin-coverage": "^0.3",
         "pestphp/pest-plugin-init": "^0.3",
-        "phpunit/phpunit": ">= 9.3.7 <= 9.4.2"
+        "phpunit/phpunit": ">= 9.3.7 <= 9.5.0"
     },
     "autoload": {
         "psr-4": {
@@ -44,6 +44,7 @@
     "require-dev": {
         "illuminate/console": "^7.16.1",
         "illuminate/support": "^7.16.1",
+        "laravel/dusk": "^6.9.0",
         "mockery/mockery": "^1.4.1",
         "pestphp/pest-dev-tools": "dev-master"
     },

src/Concerns/Extendable.php

@@ -0,0 +1,55 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Pest\Concerns;
+
+use BadMethodCallException;
+use Closure;
+
+/**
+ * @internal
+ */
+trait Extendable
+{
+    /**
+     * @var array<string, Closure>
+     */
+    private static $extends = [];
+
+    /**
+     * Register a custom extend.
+     */
+    public static function extend(string $name, Closure $extend): void
+    {
+        static::$extends[$name] = $extend;
+    }
+
+    /**
+     * Checks if extend is registered.
+     */
+    public static function hasExtend(string $name): bool
+    {
+        return array_key_exists($name, static::$extends);
+    }
+
+    /**
+     * Dynamically handle calls to the class.
+     *
+     * @param array<int, mixed> $parameters
+     *
+     * @return mixed
+     *
+     * @throws BadMethodCallException
+     */
+    public function __call(string $method, array $parameters)
+    {
+        if (!static::hasExtend($method)) {
+            throw new BadMethodCallException(sprintf('Method %s::%s does not exist.', static::class, $method));
+        }
+
+        $extend = static::$extends[$method]->bindTo($this, static::class);
+
+        return $extend(...$parameters);
+    }
+}

src/Console/Command.php

@@ -148,5 +148,7 @@ final class Command extends BaseCommand
         $version = Container::getInstance()->get(Version::class);
         $version->handleArguments(['--version']);
         parent::showHelp();
+
+        (new Help($this->output))();
     }
 }

src/Console/Help.php

@@ -0,0 +1,37 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Pest\Console;
+
+use Symfony\Component\Console\Output\OutputInterface;
+
+/**
+ * @internal
+ */
+final class Help
+{
+    /** @var array<int, string> */
+    private const HELP_MESSAGES = [
+        '<comment>Pest Options:</comment>',
+        '  <info>--init</info>                      Initialise a standard Pest configuration',
+        '  <info>--coverage</info>                  Enable coverage and output to standard output',
+        '  <info>--min=<fg=cyan><N></></info>                   Set the minimum required coverage percentage (<N>), and fail if not met',
+        '  <info>--group=<fg=cyan><name></></info>              Only runs tests from the specified group(s)',
+    ];
+
+    /** @var OutputInterface */
+    private $output;
+
+    public function __construct(OutputInterface $output)
+    {
+        $this->output = $output;
+    }
+
+    public function __invoke(): void
+    {
+        foreach (self::HELP_MESSAGES as $message) {
+            $this->output->writeln($message);
+        }
+    }
+}

src/Datasets.php

@@ -51,7 +51,7 @@ final class Datasets
     /**
      * Resolves the current dataset to an array value.
      *
-     * @param Traversable<int, mixed>|Closure|iterable<int, mixed>|string|null $data
+     * @param Traversable<int|string, mixed>|Closure|iterable<int|string, mixed>|string|null $data
      *
      * @return array<string, mixed>
      */

src/Expectation.php

@@ -4,8 +4,10 @@ declare(strict_types=1);
 
 namespace Pest;
 
+use Pest\Concerns\Extendable;
 use PHPUnit\Framework\Assert;
 use PHPUnit\Framework\Constraint\Constraint;
+use SebastianBergmann\Exporter\Exporter;
 
 /**
  * @internal
@@ -14,6 +16,8 @@ use PHPUnit\Framework\Constraint\Constraint;
  */
 final class Expectation
 {
+    use Extendable;
+
     /**
      * The expectation value.
      *
@@ -23,6 +27,15 @@ final class Expectation
      */
     public $value;
 
+    /**
+     * The exporter instance, if any.
+     *
+     * @readonly
+     *
+     * @var Exporter|null
+     */
+    private $exporter;
+
     /**
      * Creates a new expectation.
      *
@@ -408,10 +421,21 @@ final class Expectation
      * Asserts that the value array has the provided $key.
      *
      * @param string|int $key
+     * @param mixed      $value
      */
-    public function toHaveKey($key): Expectation
+    public function toHaveKey($key, $value = null): Expectation
     {
-        Assert::assertArrayHasKey($key, $this->value);
+        if (is_object($this->value) && method_exists($this->value, 'toArray')) {
+            $array = $this->value->toArray();
+        } else {
+            $array = (array) $this->value;
+        }
+
+        Assert::assertArrayHasKey($key, $array);
+
+        if (func_num_args() > 1) {
+            Assert::assertEquals($value, $array[$key]);
+        }
 
         return $this;
     }
@@ -490,6 +514,36 @@ final class Expectation
         return $this;
     }
 
+    /**
+     * Asserts that the value array matches the given array subset.
+     *
+     * @param array<int|string, mixed> $array
+     */
+    public function toMatchArray($array): Expectation
+    {
+        if (is_object($this->value) && method_exists($this->value, 'toArray')) {
+            $valueAsArray = $this->value->toArray();
+        } else {
+            $valueAsArray = (array) $this->value;
+        }
+
+        foreach ($array as $key => $value) {
+            Assert::assertArrayHasKey($key, $valueAsArray);
+
+            Assert::assertEquals(
+                $value,
+                $valueAsArray[$key],
+                sprintf(
+                    'Failed asserting that an array has a key %s with the value %s.',
+                    $this->export($key),
+                    $this->export($valueAsArray[$key]),
+                ),
+            );
+        }
+
+        return $this;
+    }
+
     /**
      * Asserts that the value object matches a subset
      * of the properties of an given object.
@@ -499,7 +553,19 @@ final class Expectation
     public function toMatchObject($object): Expectation
     {
         foreach ((array) $object as $property => $value) {
-            $this->toHaveProperty($property, $value);
+            Assert::assertTrue(property_exists($this->value, $property));
+
+            /* @phpstan-ignore-next-line */
+            $propertyValue = $this->value->{$property};
+            Assert::assertEquals(
+                $value,
+                $propertyValue,
+                sprintf(
+                    'Failed asserting that an object has a property %s with the value %s.',
+                    $this->export($property),
+                    $this->export($propertyValue),
+                ),
+            );
         }
 
         return $this;
@@ -525,6 +591,20 @@ final class Expectation
         return $this;
     }
 
+    /**
+     * Exports the given value.
+     *
+     * @param mixed $value
+     */
+    private function export($value): string
+    {
+        if ($this->exporter === null) {
+            $this->exporter = new Exporter();
+        }
+
+        return $this->exporter->export($value);
+    }
+
     /**
      * Dynamically calls methods on the class without any arguments.
      *

src/Factories/TestCaseFactory.php

@@ -59,7 +59,7 @@ final class TestCaseFactory
     /**
      * Holds the dataset, if any.
      *
-     * @var Closure|iterable<int, mixed>|string|null
+     * @var Closure|iterable<int|string, mixed>|string|null
      */
     public $dataset;
 

src/Laravel/Commands/PestDuskCommand.php

@@ -0,0 +1,41 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Pest\Laravel\Commands;
+
+use Laravel\Dusk\Console\DuskCommand;
+
+/**
+ * @internal
+ */
+final class PestDuskCommand extends DuskCommand
+{
+    /**
+     * The console command name.
+     *
+     * @var string
+     */
+    protected $signature = 'pest:dusk {--without-tty : Disable output to TTY}';
+
+    /**
+     * The console command description.
+     *
+     * @var string
+     */
+    protected $description = 'Run the Dusk tests for the application with Pest';
+
+    /**
+     * Get the PHP binary to execute.
+     *
+     * @return array<string>
+     */
+    protected function binary()
+    {
+        if ('phpdbg' === PHP_SAPI) {
+            return [PHP_BINARY, '-qrr', 'vendor/bin/pest'];
+        }
+
+        return [PHP_BINARY, 'vendor/bin/pest'];
+    }
+}

src/Laravel/PestServiceProvider.php

@@ -5,7 +5,9 @@ declare(strict_types=1);
 namespace Pest\Laravel;
 
 use Illuminate\Support\ServiceProvider;
+use Laravel\Dusk\Console\DuskCommand;
 use Pest\Laravel\Commands\PestDatasetCommand;
+use Pest\Laravel\Commands\PestDuskCommand;
 use Pest\Laravel\Commands\PestInstallCommand;
 use Pest\Laravel\Commands\PestTestCommand;
 
@@ -22,6 +24,12 @@ final class PestServiceProvider extends ServiceProvider
                 PestTestCommand::class,
                 PestDatasetCommand::class,
             ]);
+
+            if (class_exists(DuskCommand::class)) {
+                $this->commands([
+                    PestDuskCommand::class,
+                ]);
+            }
         }
     }
 }

src/PendingObjects/TestCall.php

@@ -78,7 +78,7 @@ final class TestCall
      * Runs the current test multiple times with
      * each item of the given `iterable`.
      *
-     * @param \Closure|iterable<int, mixed>|string $data
+     * @param \Closure|iterable<int|string, mixed>|string $data
      */
     public function with($data): TestCall
     {
@@ -95,7 +95,11 @@ final class TestCall
         $className = $this->testCaseFactory->getClassName();
 
         $tests = array_map(function (string $test) use ($className): ExecutionOrderDependency {
-            return ExecutionOrderDependency::createFromDependsAnnotation($className, $test);
+            if (strpos($test, '::') === false) {
+                $test = "{$className}::{$test}";
+            }
+
+            return new ExecutionOrderDependency($test, null, '');
         }, $tests);
 
         $this->testCaseFactory

src/Pest.php

@@ -6,5 +6,5 @@ namespace Pest;
 
 function version(): string
 {
-    return '0.3.11';
+    return '0.3.15';
 }

src/Support/Extendable.php

@@ -0,0 +1,33 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Pest\Support;
+
+use Closure;
+
+final class Extendable
+{
+    /**
+     * The extendable class.
+     *
+     * @var string
+     */
+    private $extendableClass;
+
+    /**
+     * Creates a new extendable instance.
+     */
+    public function __construct(string $extendableClass)
+    {
+        $this->extendableClass = $extendableClass;
+    }
+
+    /**
+     * Register a custom extend.
+     */
+    public function extend(string $name, Closure $extend): void
+    {
+        $this->extendableClass::extend($name, $extend);
+    }
+}

src/globals.php

@@ -9,6 +9,7 @@ use Pest\PendingObjects\BeforeEachCall;
 use Pest\PendingObjects\TestCall;
 use Pest\PendingObjects\UsesCall;
 use Pest\Support\Backtrace;
+use Pest\Support\Extendable;
 use Pest\Support\HigherOrderTapProxy;
 use Pest\TestSuite;
 use PHPUnit\Framework\TestCase;
@@ -111,9 +112,13 @@ function afterAll(Closure $closure = null): void
  *
  * @param mixed $value the Value
  *
- * @return Expectation
+ * @return Expectation|Extendable
  */
-function expect($value)
+function expect($value = null)
 {
+    if (func_num_args() === 0) {
+        return new Extendable(Expectation::class);
+    }
+
     return test()->expect($value);
 }

tests/.snapshots/help-command.txt

@@ -0,0 +1,5 @@
+Pest Options:
+  --init                      Initialise a standard Pest configuration
+  --coverage                  Enable coverage and output to standard output
+  --min=<N>                   Set the minimum required coverage percentage (<N>), and fail if not met
+  --group=<name>              Only runs tests from the specified group(s)

tests/.snapshots/success.txt

@@ -2,6 +2,12 @@
    PASS  Tests\CustomTestCase\ExecutedTest
   ✓ that gets executed
 
+   PASS  Tests\Expect\extend
+  ✓ it macros true is true
+  ✓ it macros false is not true
+  ✓ it macros true is true with argument
+  ✓ it macros false is not true with argument
+
    PASS  Tests\Expect\not
   ✓ not property calls
 
@@ -200,6 +206,11 @@
    PASS  Tests\Expect\toMatch
   ✓ pass
   ✓ failures
+  ✓ not failures
+
+   PASS  Tests\Expect\toMatchArray
+  ✓ pass
+  ✓ failures
   ✓ not failures
 
    PASS  Tests\Expect\toMatchConstraint
@@ -348,6 +359,9 @@
   ✓ it throws exception when `process isolation` is true
   ✓ it do not throws exception when `process isolation` is false
 
+   PASS  Tests\Unit\Console\Help
+  ✓ it outputs the help information when --help is used
+
    PASS  Tests\Unit\Datasets
   ✓ it show the names of named datasets in their description
 
@@ -374,6 +388,9 @@
    PASS  Tests\Unit\TestSuite
   ✓ it does not allow to add the same test description twice
 
+   PASS  Tests\Visual\Help
+  ✓ visual snapshot of help command output
+
    PASS  Tests\Visual\SingleTestOrDirectory
   ✓ allows to run a single test
   ✓ allows to run a directory
@@ -386,10 +403,12 @@
    PASS  Tests\Features\Depends
   ✓ first
   ✓ second
+  ✓ it asserts true is true
   ✓ depends
   ✓ depends with ...params
   ✓ depends with defined arguments
   ✓ depends run test only once
+  ✓ depends works with the correct test name
 
-  Tests:  7 skipped, 231 passed
+  Tests:  7 skipped, 242 passed
   

tests/Expect/extend.php

@@ -0,0 +1,29 @@
+<?php
+
+expect()->extend('toBeAMacroExpectation', function () {
+    $this->toBeTrue();
+
+    return $this;
+});
+
+expect()->extend('toBeAMacroExpectationWithArguments', function (bool $value) {
+    $this->toBe($value);
+
+    return $this;
+});
+
+it('macros true is true', function () {
+    expect(true)->toBeAMacroExpectation();
+});
+
+it('macros false is not true', function () {
+    expect(false)->not->toBeAMacroExpectation();
+});
+
+it('macros true is true with argument', function () {
+    expect(true)->toBeAMacroExpectationWithArguments(true);
+});
+
+it('macros false is not true with argument', function () {
+    expect(false)->not->toBeAMacroExpectationWithArguments(true);
+});

tests/Expect/toMatchArray.php

@@ -0,0 +1,31 @@
+<?php
+
+use PHPUnit\Framework\ExpectationFailedException;
+
+beforeEach(function () {
+    $this->user = [
+        'id'    => 1,
+        'name'  => 'Nuno',
+        'email' => 'enunomaduro@gmail.com',
+    ];
+});
+
+test('pass', function () {
+    expect($this->user)->toMatchArray([
+        'name'  => 'Nuno',
+        'email' => 'enunomaduro@gmail.com',
+    ]);
+});
+
+test('failures', function () {
+    expect($this->user)->toMatchArray([
+        'name'  => 'Not the same name',
+        'email' => 'enunomaduro@gmail.com',
+    ]);
+})->throws(ExpectationFailedException::class);
+
+test('not failures', function () {
+    expect($this->user)->not->toMatchArray([
+        'id' => 1,
+    ]);
+})->throws(ExpectationFailedException::class);

tests/Features/Depends.php

@@ -32,3 +32,7 @@ test('depends with defined arguments', function (string $first, string $second)
 test('depends run test only once', function () use (&$runCounter) {
     expect($runCounter)->toBe(2);
 })->depends('first', 'second');
+
+// Regression tests. See https://github.com/pestphp/pest/pull/216
+it('asserts true is true')->assertTrue(true);
+test('depends works with the correct test name')->assertTrue(true)->depends('it asserts true is true');

tests/Unit/Console/Help.php

@@ -0,0 +1,12 @@
+<?php
+
+use Pest\Console\Help;
+use Symfony\Component\Console\Output\BufferedOutput;
+
+it('outputs the help information when --help is used', function () {
+    $output = new BufferedOutput();
+    $plugin = new Help($output);
+
+    $plugin();
+    expect($output->fetch())->toContain('Pest Options:');
+});

tests/Visual/Help.php

@@ -0,0 +1,27 @@
+<?php
+
+use Pest\Console\Help;
+use Symfony\Component\Console\Output\BufferedOutput;
+
+test('visual snapshot of help command output', function () {
+    $snapshot = __DIR__ . '/../.snapshots/help-command.txt';
+
+    if (getenv('REBUILD_SNAPSHOTS')) {
+        $outputBuffer = new BufferedOutput();
+        $plugin = new Help($outputBuffer);
+
+        $plugin();
+
+        file_put_contents($snapshot, $outputBuffer->fetch());
+    }
+
+    $output = function () {
+        $process = (new Symfony\Component\Process\Process(['php', 'bin/pest', '--help']));
+
+        $process->run();
+
+        return preg_replace('#\\x1b[[][^A-Za-z]*[A-Za-z]#', '', $process->getOutput());
+    };
+
+    expect($output())->toContain(file_get_contents($snapshot));
+})->skip(PHP_OS_FAMILY === 'Windows');