docs: update changelog

Forces higher order test callable expects to be closures

CHANGELOG.md

@@ -4,6 +4,19 @@ 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/).
 
+## [v1.9.1 (2021-07-11)](https://github.com/pestphp/pest/compare/v1.9.0...v1.9.1)
+### Fixed
+- Callable `expect` values in higher order tests failing if the value was an existing method name ([#334](https://github.com/pestphp/pest/pull/344)) 
+
+## [v1.9.0 (2021-07-09)](https://github.com/pestphp/pest/compare/v1.8.0...v1.9.0)
+### Changed
+- You may now pass just an exception message when using the `throws` method ([#339](https://github.com/pestphp/pest/pull/339)) 
+
+## [v1.8.0 (2021-07-08)](https://github.com/pestphp/pest/compare/v1.7.1...v1.8.0)
+### Added
+- A new `tap` and test case aware `expect` methods for higher order tests ([#331](https://github.com/pestphp/pest/pull/331))
+- Access to test case methods and properties when using `skip` ([#338](https://github.com/pestphp/pest/pull/338))
+
 ## [v1.7.1 (2021-06-24)](https://github.com/pestphp/pest/compare/v1.7.0...v1.7.1)
 ### Fixed
 - The `and` method not being usable in Higher Order expectations ([#330](https://github.com/pestphp/pest/pull/330))

src/PendingObjects/TestCall.php

@@ -7,14 +7,15 @@ namespace Pest\PendingObjects;
 use Closure;
 use Pest\Factories\TestCaseFactory;
 use Pest\Support\Backtrace;
+use Pest\Support\HigherOrderCallables;
 use Pest\Support\NullClosure;
 use Pest\TestSuite;
 use SebastianBergmann\Exporter\Exporter;
 
 /**
- * @method \Pest\Expectations\Expectation expect(mixed $value)
- *
  * @internal
+ *
+ * @mixin HigherOrderCallables
  */
 final class TestCall
 {
@@ -58,11 +59,15 @@ final class TestCall
     /**
      * Asserts that the test throws the given `$exceptionClass` when called.
      */
-    public function throws(string $exceptionClass, string $exceptionMessage = null): TestCall
+    public function throws(string $exception, string $exceptionMessage = null): TestCall
     {
-        $this->testCaseFactory
-            ->proxies
-            ->add(Backtrace::file(), Backtrace::line(), 'expectException', [$exceptionClass]);
+        if (class_exists($exception)) {
+            $this->testCaseFactory
+                ->proxies
+                ->add(Backtrace::file(), Backtrace::line(), 'expectException', [$exception]);
+        } else {
+            $exceptionMessage = $exception;
+        }
 
         if (is_string($exceptionMessage)) {
             $this->testCaseFactory
@@ -143,11 +148,9 @@ final class TestCall
             ? $conditionOrMessage
             : $message;
 
-        if ($condition() !== false) {
-            $this->testCaseFactory
-                ->chains
-                ->add(Backtrace::file(), Backtrace::line(), 'markTestSkipped', [$message]);
-        }
+        $this->testCaseFactory
+            ->chains
+            ->addWhen($condition, Backtrace::file(), Backtrace::line(), 'markTestSkipped', [$message]);
 
         return $this;
     }

src/Pest.php

@@ -6,7 +6,7 @@ namespace Pest;
 
 function version(): string
 {
-    return '1.7.1';
+    return '1.9.1';
 }
 
 function testDirectory(string $file = ''): string

src/Plugins/Coverage.php

@@ -81,7 +81,6 @@ final class Coverage implements AddsOutput, HandlesArguments
         }
 
         if ($input->getOption(self::MIN_OPTION) !== null) {
-            /* @phpstan-ignore-next-line */
             $this->coverageMin = (float) $input->getOption(self::MIN_OPTION);
         }
 

src/Support/HigherOrderCallables.php

@@ -0,0 +1,66 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Pest\Support;
+
+use Closure;
+use Pest\Expectation;
+use Pest\PendingObjects\TestCall;
+use PHPUnit\Framework\TestCase;
+
+/**
+ * @internal
+ */
+final class HigherOrderCallables
+{
+    /**
+     * @var object
+     */
+    private $target;
+
+    public function __construct(object $target)
+    {
+        $this->target = $target;
+    }
+
+    /**
+     * @template TValue
+     *
+     * Create a new expectation. Callable values will be executed prior to returning the new expectation.
+     *
+     * @param callable|TValue $value
+     *
+     * @return Expectation<TValue>
+     */
+    public function expect($value)
+    {
+        return new Expectation($value instanceof Closure ? Reflection::bindCallable($value) : $value);
+    }
+
+    /**
+     * @template TValue
+     *
+     * Create a new expectation. Callable values will be executed prior to returning the new expectation.
+     *
+     * @param callable|TValue $value
+     *
+     * @return Expectation<TValue>
+     */
+    public function and($value)
+    {
+        return $this->expect($value);
+    }
+
+    /**
+     * Tap into the test case to perform an action and return the test case.
+     *
+     * @return TestCall|TestCase|object
+     */
+    public function tap(callable $callable)
+    {
+        Reflection::bindCallable($callable);
+
+        return $this->target;
+    }
+}

src/Support/HigherOrderMessage.php

@@ -4,6 +4,7 @@ declare(strict_types=1);
 
 namespace Pest\Support;
 
+use Closure;
 use ReflectionClass;
 use Throwable;
 
@@ -50,6 +51,13 @@ final class HigherOrderMessage
      */
     public $arguments;
 
+    /**
+     * An optional condition that will determine if the message will be executed.
+     *
+     * @var callable(): bool|null
+     */
+    public $condition = null;
+
     /**
      * Creates a new higher order message.
      *
@@ -70,6 +78,16 @@ final class HigherOrderMessage
      */
     public function call(object $target)
     {
+        /* @phpstan-ignore-next-line */
+        if (is_callable($this->condition) && call_user_func(Closure::bind($this->condition, $target)) === false) {
+            return $target;
+        }
+
+        if ($this->hasHigherOrderCallable()) {
+            /* @phpstan-ignore-next-line */
+            return (new HigherOrderCallables($target))->{$this->methodName}(...$this->arguments);
+        }
+
         try {
             return Reflection::call($target, $this->methodName, $this->arguments);
         } catch (Throwable $throwable) {
@@ -88,6 +106,28 @@ final class HigherOrderMessage
         }
     }
 
+    /**
+     * Indicates that this message should only be called when the given condition is true.
+     *
+     * @param callable(): bool $condition
+     */
+    public function when(callable $condition): self
+    {
+        $this->condition = $condition;
+
+        return $this;
+    }
+
+    /**
+     * Determines whether or not there exists a higher order callable with the message name.
+     *
+     * @return bool
+     */
+    private function hasHigherOrderCallable()
+    {
+        return in_array($this->methodName, get_class_methods(HigherOrderCallables::class), true);
+    }
+
     private static function getUndefinedMethodMessage(object $target, string $methodName): string
     {
         if (\PHP_MAJOR_VERSION >= 8) {

src/Support/HigherOrderMessageCollection.php

@@ -24,6 +24,16 @@ final class HigherOrderMessageCollection
         $this->messages[] = new HigherOrderMessage($filename, $line, $methodName, $arguments);
     }
 
+    /**
+     * Adds a new higher order message to the collection if the callable condition is does not return false.
+     *
+     * @param array<int, mixed> $arguments
+     */
+    public function addWhen(callable $condition, string $filename, int $line, string $methodName, array $arguments): void
+    {
+        $this->messages[] = (new HigherOrderMessage($filename, $line, $methodName, $arguments))->when($condition);
+    }
+
     /**
      * Proxy all the messages starting from the target.
      */

src/Support/HigherOrderTapProxy.php

@@ -4,6 +4,7 @@ declare(strict_types=1);
 
 namespace Pest\Support;
 
+use PHPUnit\Framework\TestCase;
 use ReflectionClass;
 use Throwable;
 
@@ -17,16 +18,14 @@ final class HigherOrderTapProxy
     /**
      * The target being tapped.
      *
-     * @var mixed
+     * @var TestCase
      */
     public $target;
 
     /**
      * Create a new tap proxy instance.
-     *
-     * @param mixed $target
      */
-    public function __construct($target)
+    public function __construct(TestCase $target)
     {
         $this->target = $target;
     }

src/Support/Reflection.php

@@ -41,15 +41,25 @@ final class Reflection
             }
 
             if (is_callable($method)) {
-                return Closure::fromCallable($method)->bindTo(
-                    TestSuite::getInstance()->test
-                )(...$args);
+                return static::bindCallable($method, $args);
             }
 
             throw $exception;
         }
     }
 
+    /**
+     * Bind a callable to the TestCase and return the result.
+     *
+     * @param array<int, mixed> $args
+     *
+     * @return mixed
+     */
+    public static function bindCallable(callable $callable, array $args = [])
+    {
+        return Closure::fromCallable($callable)->bindTo(TestSuite::getInstance()->test)(...$args);
+    }
+
     /**
      * Infers the file name from the given closure.
      */

tests/.snapshots/success.txt

@@ -410,6 +410,8 @@
    PASS  Tests\Features\HigherOrderTests
   ✓ it proxies calls to object
   ✓ it is capable doing multiple assertions
+  ✓ it resolves expect callables correctly
+  ✓ it can tap into the test
 
    WARN  Tests\Features\Incompleted
   … incompleted
@@ -579,5 +581,5 @@
   ✓ it is a test
   ✓ it uses correct parent class
 
-  Tests:  4 incompleted, 7 skipped, 363 passed
+  Tests:  4 incompleted, 7 skipped, 365 passed
   

tests/Features/Exceptions.php

@@ -13,3 +13,7 @@ it('catch exceptions', function () {
 it('catch exceptions and messages', function () {
     throw new Exception('Something bad happened');
 })->throws(Exception::class, 'Something bad happened');
+
+it('can just define the message', function () {
+    throw new Exception('Something bad happened');
+})->throws('Something bad happened');

tests/Features/HigherOrderTests.php

@@ -1,5 +1,7 @@
 <?php
 
+use PHPUnit\Framework\TestCase;
+
 beforeEach()->assertTrue(true);
 
 it('proxies calls to object')->assertTrue(true);
@@ -8,4 +10,21 @@ it('is capable doing multiple assertions')
     ->assertTrue(true)
     ->assertFalse(false);
 
+it('resolves expect callables correctly')
+    ->expect(function () { return 'foo'; })
+    ->toBeString()
+    ->toBe('foo')
+    ->and('bar')
+    ->toBeString()
+    ->toBe('bar');
+
+test('does not treat method names as callables')
+    ->expect('it')->toBeString();
+
+it('can tap into the test')
+    ->expect('foo')->toBeString()
+    ->tap(function () { expect($this)->toBeInstanceOf(TestCase::class); })
+    ->toBe('foo')
+    ->and('hello world')->toBeString();
+
 afterEach()->assertTrue(true);

tests/Features/Skip.php

@@ -1,5 +1,9 @@
 <?php
 
+beforeEach(function () {
+    $this->shouldSkip = true;
+});
+
 it('do not skips')
     ->skip(false)
     ->assertTrue(true);
@@ -31,3 +35,12 @@ it('skips with condition and message')
 it('skips when skip after assertion')
     ->assertTrue(true)
     ->skip();
+
+it('can use something in the test case as a condition')
+    ->skip(function () { return $this->shouldSkip; }, 'This test was skipped')
+    ->assertTrue(false);
+
+it('can user higher order callables and skip')
+    ->skip(function () { return $this->shouldSkip; })
+    ->expect(function () { return $this->shouldSkip; })
+    ->toBeFalse();