Merge branch 'master' into performs_no_expectations

src/Expectation.php

@@ -56,13 +56,13 @@ final class Expectation
      */
     public function and(mixed $value): Expectation
     {
-        return new self($value);
+        return $value instanceof static ? $value : new self($value);
     }
 
     /**
      * Creates a new expectation with the decoded JSON value.
      *
-     * @return self<mixed>
+     * @return self<array<int|string, mixed>|bool>
      */
     public function json(): Expectation
     {
@@ -70,7 +70,10 @@ final class Expectation
             InvalidExpectationValue::expected('string');
         }
 
-        return $this->toBeJson()->and(json_decode($this->value, true));
+        /** @var array<int|string, mixed>|bool $value */
+        $value = json_decode($this->value, true);
+
+        return $this->toBeJson()->and($value);
     }
 
     /**
@@ -125,8 +128,8 @@ final class Expectation
         }
 
         if (is_callable($callback)) {
-            foreach ($this->value as $item) {
-                $callback(new self($item));
+            foreach ($this->value as $key => $item) {
+                $callback(new self($item), $key);
             }
         }
 
@@ -148,6 +151,7 @@ final class Expectation
             throw new BadMethodCallException('Expectation value is not iterable.');
         }
 
+        //@phpstan-ignore-next-line
         $value          = is_array($this->value) ? $this->value : iterator_to_array($this->value);
         $keys           = array_keys($value);
         $values         = array_values($value);

src/Expectations/HigherOrderExpectation.php

@@ -4,6 +4,7 @@ declare(strict_types=1);
 
 namespace Pest\Expectations;
 
+use Closure;
 use Pest\Concerns\Retrievable;
 use Pest\Expectation;
 
@@ -79,6 +80,31 @@ final class HigherOrderExpectation
         return $this->expect($value);
     }
 
+    /**
+     * Scope an expectation callback to the current value in
+     * the HigherOrderExpectation chain.
+     *
+     * @param Closure(Expectation<TValue>): void $expectation
+     *
+     * @return HigherOrderExpectation<TOriginalValue, TOriginalValue>
+     */
+    public function scoped(Closure $expectation): self
+    {
+        $expectation->__invoke($this->expectation);
+
+        return new self($this->original, $this->original->value);
+    }
+
+    /**
+     * Creates a new expectation with the decoded JSON value.
+     *
+     * @return self<TOriginalValue, array<string|int, mixed>|bool>
+     */
+    public function json(): self
+    {
+        return new self($this->original, $this->expectation->json()->value);
+    }
+
     /**
      * Dynamically calls methods on the class with the given arguments.
      *

src/Support/Backtrace.php

@@ -26,6 +26,8 @@ final class Backtrace
         $current = null;
 
         foreach (debug_backtrace(self::BACKTRACE_OPTIONS) as $trace) {
+            assert(array_key_exists(self::FILE, $trace));
+
             if (Str::endsWith($trace[self::FILE], 'overrides/Runner/TestSuiteLoader.php')) {
                 break;
             }
@@ -45,7 +47,11 @@ final class Backtrace
      */
     public static function file(): string
     {
-        return debug_backtrace(self::BACKTRACE_OPTIONS)[1][self::FILE];
+        $trace = debug_backtrace(self::BACKTRACE_OPTIONS)[1];
+
+        assert(array_key_exists(self::FILE, $trace));
+
+        return $trace[self::FILE];
     }
 
     /**
@@ -53,7 +59,11 @@ final class Backtrace
      */
     public static function dirname(): string
     {
-        return dirname(debug_backtrace(self::BACKTRACE_OPTIONS)[1][self::FILE]);
+        $trace = debug_backtrace(self::BACKTRACE_OPTIONS)[1];
+
+        assert(array_key_exists(self::FILE, $trace));
+
+        return dirname($trace[self::FILE]);
     }
 
     /**
@@ -61,6 +71,10 @@ final class Backtrace
      */
     public static function line(): int
     {
-        return debug_backtrace(self::BACKTRACE_OPTIONS)[1]['line'];
+        $trace = debug_backtrace(self::BACKTRACE_OPTIONS)[1];
+
+        assert(array_key_exists('line', $trace));
+
+        return $trace['line'];
     }
 }

src/Support/HigherOrderCallables.php

@@ -44,7 +44,7 @@ final class HigherOrderCallables
      *
      * @param callable|TValue $value
      *
-     * @return Expectation<TValue>
+     * @return Expectation<(callable(): mixed)|TValue>
      */
     public function and(mixed $value)
     {
@@ -52,9 +52,9 @@ final class HigherOrderCallables
     }
 
     /**
-     * Tap into the test case to perform an action and return the test case.
+     * Execute the given callable after the test has executed the setup method.
      */
-    public function tap(callable $callable): object
+    public function defer(callable $callable): object
     {
         Reflection::bindCallableWithData($callable);