Merge pull request #331 from pestphp/higher-order-tap-and-defer

Adds a new `tap` method to Higher Order tests

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
 {

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,65 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Pest\Support;
+
+use Pest\Expectation;
+
+/**
+ * @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(is_callable($value) ? 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);
+    }
+
+    /**
+     * @template TValue
+     *
+     * @param callable(): TValue $callable
+     *
+     * @return TValue|object
+     */
+    public function tap(callable $callable)
+    {
+        Reflection::bindCallable($callable);
+
+        return $this->target;
+    }
+}

src/Support/HigherOrderMessage.php

@@ -70,6 +70,11 @@ final class HigherOrderMessage
      */
     public function call(object $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 +93,16 @@ final class HigherOrderMessage
         }
     }
 
+    /**
+     * 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/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/HigherOrderTests.php

@@ -1,5 +1,7 @@
 <?php
 
+use PHPUnit\Framework\TestCase;
+
 beforeEach()->assertTrue(true);
 
 it('proxies calls to object')->assertTrue(true);
@@ -8,4 +10,18 @@ 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');
+
+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);