Add ability to extend TestCall to create custom chained helpers

Author: JHWelch

src/PendingCalls/TestCall.php

@@ -5,6 +5,7 @@
 namespace Pest\PendingCalls;
 
 use Closure;
+use Pest\Concerns\Extendable;
 use Pest\Exceptions\InvalidArgumentException;
 use Pest\Exceptions\TestDescriptionMissing;
 use Pest\Factories\Attribute;
@@ -30,6 +31,9 @@
 final class TestCall
 {
     use Describable;
+    use Extendable {
+        extend as traitExtend;
+    }
 
     /**
      * The list of test case factory attributes.
@@ -642,9 +646,25 @@ public function __get(string $name): self
      */
     public function __call(string $name, array $arguments): self
     {
+        if (self::hasExtend($name)) {
+            $extend = self::$extends[$name]->bindTo($this, TestCall::class);
+
+            if ($extend != false) { // @pest-arch-ignore-line
+                return $extend(...$arguments);
+            }
+        }
+
         return $this->addChain(Backtrace::file(), Backtrace::line(), $name, $arguments);
     }
 
+    public function extend(string $name, Closure $extend): void
+    {
+        $this->traitExtend($name, $extend);
+
+        $this->description = "extend: $name";
+        $this->testCaseMethod->closure = fn (): null => null;
+    }
+
     /**
      * Add a chain to the test case factory. Omitting the arguments will treat it as a property accessor.
      *

tests/.snapshots/success.txt

@@ -1261,6 +1261,10 @@
   ✓ a test
   ✓ higher order message test
 
+   PASS  Tests\Features\TestCallExtend
+  ✓ it uses fooBar extension with ('foo')
+  ✓ it uses fooBar extension with ('bar')
+
    PASS  Tests\Features\ThrowsNoExceptions
   ✓ it allows access to the underlying expectNotToPerformAssertions method
   ✓ it allows performing no expectations without being risky
@@ -1580,4 +1584,4 @@
    WARN  Tests\Visual\Version
   - visual snapshot of help command output
 
-  Tests:    2 deprecated, 4 warnings, 5 incomplete, 2 notices, 17 todos, 28 skipped, 1093 passed (2644 assertions)
+  Tests:    2 deprecated, 4 warnings, 5 incomplete, 2 notices, 17 todos, 28 skipped, 1095 passed (2646 assertions)

tests/Features/TestCallExtend.php

@@ -0,0 +1,17 @@
+<?php
+
+use function PHPUnit\Framework\assertTrue;
+
+test()->extend('fooBar', function () {
+    return $this->with([
+        'foo',
+        'bar',
+    ]);
+});
+
+it('uses fooBar extension', function ($value) {
+    assertTrue(in_array($value, [
+        'foo',
+        'bar',
+    ]));
+})->fooBar();

tests/Visual/Parallel.php

@@ -16,7 +16,7 @@
 
 test('parallel', function () use ($run) {
     expect($run('--exclude-group=integration'))
-        ->toContain('Tests:    2 deprecated, 4 warnings, 5 incomplete, 2 notices, 17 todos, 19 skipped, 1083 passed (2620 assertions)')
+        ->toContain('Tests:    2 deprecated, 4 warnings, 5 incomplete, 2 notices, 17 todos, 19 skipped, 1085 passed (2622 assertions)')
         ->toContain('Parallel: 3 processes');
 })->skipOnWindows();