Merge pull request #324 from pestphp/nested-higher-order-expectations

Adds Nested Higher Order Expectations

src/Concerns/Expectable.php

@@ -12,9 +12,13 @@ use Pest\Expectation;
 trait Expectable
 {
     /**
+     * @template TValue
+     *
      * Creates a new expectation.
      *
-     * @param mixed $value
+     * @param TValue $value
+     *
+     * @return Expectation<TValue>
      */
     public function expect($value): Expectation
     {

src/Concerns/Extendable.php

@@ -4,8 +4,8 @@ declare(strict_types=1);
 
 namespace Pest\Concerns;
 
+use BadMethodCallException;
 use Closure;
-use Pest\HigherOrderExpectation;
 
 /**
  * @internal
@@ -43,7 +43,7 @@ trait Extendable
     public function __call(string $method, array $parameters)
     {
         if (!static::hasExtend($method)) {
-            return new HigherOrderExpectation($this, $method, $parameters);
+            throw new BadMethodCallException("$method is not a callable method name.");
         }
 
         /** @var Closure $extend */

src/Concerns/RetrievesValues.php

@@ -0,0 +1,31 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Pest\Concerns;
+
+/**
+ * @internal
+ */
+trait RetrievesValues
+{
+    /**
+     * @template TRetrievableValue
+     *
+     * Safely retrieve the value at the given key from an object or array.
+     *
+     * @param array<string, TRetrievableValue>|object $value
+     * @param TRetrievableValue|null                  $default
+     *
+     * @return TRetrievableValue|null
+     */
+    private function retrieve(string $key, $value, $default = null)
+    {
+        if (is_array($value)) {
+            return $value[$key] ?? $default;
+        }
+
+        // @phpstan-ignore-next-line
+        return $value->$key ?? $default;
+    }
+}

src/Expectation.php

@@ -6,6 +6,7 @@ namespace Pest;
 
 use BadMethodCallException;
 use Pest\Concerns\Extendable;
+use Pest\Concerns\RetrievesValues;
 use Pest\Support\Arr;
 use PHPUnit\Framework\Assert;
 use PHPUnit\Framework\Constraint\Constraint;
@@ -15,12 +16,17 @@ use SebastianBergmann\Exporter\Exporter;
 /**
  * @internal
  *
+ * @template TValue
+ *
  * @property Expectation $not  Creates the opposite expectation.
  * @property Each        $each Creates an expectation on each element on the traversable value.
  */
 final class Expectation
 {
-    use Extendable;
+    use Extendable {
+        __call as __extendsCall;
+    }
+    use RetrievesValues;
 
     /**
      * The expectation value.
@@ -43,7 +49,7 @@ final class Expectation
     /**
      * Creates a new expectation.
      *
-     * @param mixed $value
+     * @param TValue $value
      */
     public function __construct($value)
     {
@@ -53,7 +59,9 @@ final class Expectation
     /**
      * Creates a new expectation.
      *
-     * @param mixed $value
+     * @param TValue $value
+     *
+     * @return Expectation<TValue>
      */
     public function and($value): Expectation
     {
@@ -130,9 +138,9 @@ final class Expectation
     /**
      * Allows you to specify a sequential set of expectations for each item in a iterable "value".
      *
-     * @template TValue
+     * @template TSequenceValue
      *
-     * @param callable(self, self): void|TValue ...$callbacks
+     * @param callable(self, self): void|TSequenceValue ...$callbacks
      */
     public function sequence(...$callbacks): Expectation
     {
@@ -721,6 +729,24 @@ final class Expectation
         return $this->exporter->export($value);
     }
 
+    /**
+     * Dynamically handle calls to the class or
+     * creates a new higher order expectation.
+     *
+     * @param array<int, mixed> $parameters
+     *
+     * @return HigherOrderExpectation|mixed
+     */
+    public function __call(string $method, array $parameters)
+    {
+        if (!static::hasExtend($method)) {
+            /* @phpstan-ignore-next-line */
+            return new HigherOrderExpectation($this, $this->value->$method(...$parameters));
+        }
+
+        return $this->__extendsCall($method, $parameters);
+    }
+
     /**
      * Dynamically calls methods on the class without any arguments
      * or creates a new higher order expectation.
@@ -730,7 +756,7 @@ final class Expectation
     public function __get(string $name)
     {
         if (!method_exists($this, $name) && !static::hasExtend($name)) {
-            return new HigherOrderExpectation($this, $name);
+            return new HigherOrderExpectation($this, $this->retrieve($name, $this->value));
         }
 
         /* @phpstan-ignore-next-line */

src/HigherOrderExpectation.php

@@ -5,6 +5,7 @@ declare(strict_types=1);
 namespace Pest;
 
 use Pest\Concerns\Expectable;
+use Pest\Concerns\RetrievesValues;
 
 /**
  * @internal
@@ -14,6 +15,7 @@ use Pest\Concerns\Expectable;
 final class HigherOrderExpectation
 {
     use Expectable;
+    use RetrievesValues;
 
     /**
      * @var Expectation
@@ -30,6 +32,11 @@ final class HigherOrderExpectation
      */
     private $opposite = false;
 
+    /**
+     * @var bool
+     */
+    private $shouldReset = false;
+
     /**
      * @var string
      */
@@ -38,45 +45,12 @@ final class HigherOrderExpectation
     /**
      * Creates a new higher order expectation.
      *
-     * @param array<int|string, mixed>|null $parameters
-     * @phpstan-ignore-next-line
+     * @param mixed $value
      */
-    public function __construct(Expectation $original, string $name, ?array $parameters = null)
+    public function __construct(Expectation $original, $value)
     {
-        $this->original = $original;
-        $this->name     = $name;
-
-        $this->expectation = $this->expect(
-            is_null($parameters) ? $this->getPropertyValue() : $this->getMethodValue($parameters)
-        );
-    }
-
-    /**
-     * Retrieves the property value from the original expectation.
-     *
-     * @return mixed
-     */
-    private function getPropertyValue()
-    {
-        if (is_array($this->original->value)) {
-            return $this->original->value[$this->name];
-        }
-
-        // @phpstan-ignore-next-line
-        return $this->original->value->{$this->name};
-    }
-
-    /**
-     * Retrieves the value of the method from the original expectation.
-     *
-     * @param array<int|string, mixed> $arguments
-     *
-     * @return mixed
-     */
-    private function getMethodValue(array $arguments)
-    {
-        // @phpstan-ignore-next-line
-        return $this->original->value->{$this->name}(...$arguments);
+        $this->original     = $original;
+        $this->expectation  = $this->expect($value);
     }
 
     /**
@@ -92,12 +66,13 @@ final class HigherOrderExpectation
     /**
      * Dynamically calls methods on the class with the given arguments.
      *
-     * @param array<int|string, mixed> $arguments
+     * @param array<int, mixed> $arguments
      */
     public function __call(string $name, array $arguments): self
     {
-        if (!$this->originalHasMethod($name)) {
-            return new self($this->original, $name, $arguments);
+        if (!$this->expectationHasMethod($name)) {
+            /* @phpstan-ignore-next-line */
+            return new self($this->original, $this->getValue()->$name(...$arguments));
         }
 
         return $this->performAssertion($name, $arguments);
@@ -112,8 +87,8 @@ final class HigherOrderExpectation
             return $this->not();
         }
 
-        if (!$this->originalHasMethod($name)) {
-            return new self($this->original, $name);
+        if (!$this->expectationHasMethod($name)) {
+            return new self($this->original, $this->retrieve($name, $this->getValue()));
         }
 
         return $this->performAssertion($name, []);
@@ -122,25 +97,33 @@ final class HigherOrderExpectation
     /**
      * Determines if the original expectation has the given method name.
      */
-    private function originalHasMethod(string $name): bool
+    private function expectationHasMethod(string $name): bool
     {
         return method_exists($this->original, $name) || $this->original::hasExtend($name);
     }
 
+    /**
+     * Retrieve the applicable value based on the current reset condition.
+     *
+     * @return mixed
+     */
+    private function getValue()
+    {
+        return $this->shouldReset ? $this->original->value : $this->expectation->value;
+    }
+
     /**
      * Performs the given assertion with the current expectation.
      *
-     * @param array<int|string, mixed> $arguments
+     * @param array<int, mixed> $arguments
      */
     private function performAssertion(string $name, array $arguments): self
     {
-        $expectation = $this->opposite
-            ? $this->expectation->not()
-            : $this->expectation;
+        /* @phpstan-ignore-next-line */
+        $this->expectation = ($this->opposite ? $this->expectation->not() : $this->expectation)->{$name}(...$arguments);
 
-        $this->expectation = $expectation->{$name}(...$arguments); // @phpstan-ignore-line
-
-        $this->opposite = false;
+        $this->opposite    = false;
+        $this->shouldReset = true;
 
         return $this;
     }

tests/.snapshots/success.txt

@@ -111,9 +111,11 @@
   ✓ it works inside of each
   ✓ it works with sequence
   ✓ it can compose complex expectations
+  ✓ it can handle nested method calls
 
    PASS  Tests\Features\Expect\HigherOrder\methodsAndProperties
   ✓ it can access methods and properties
+  ✓ it can handle nested methods and properties
 
    PASS  Tests\Features\Expect\HigherOrder\properties
   ✓ it allows properties to be accessed from the value
@@ -124,6 +126,7 @@
   ✓ it works with sequence
   ✓ it can compose complex expectations
   ✓ it works with objects
+  ✓ it works with nested properties
 
    PASS  Tests\Features\Expect\each
   ✓ an exception is thrown if the the type is not iterable
@@ -575,5 +578,5 @@
   ✓ it is a test
   ✓ it uses correct parent class
 
-  Tests:  4 incompleted, 7 skipped, 359 passed
+  Tests:  4 incompleted, 7 skipped, 362 passed
   

tests/Features/Expect/HigherOrder/methods.php

@@ -59,6 +59,14 @@ it('can compose complex expectations', function () {
         );
 });
 
+it('can handle nested method calls', function () {
+    expect(new HasMethods())
+        ->newInstance()->newInstance()->name()->toEqual('Has Methods')->toBeString()
+        ->newInstance()->name()->toEqual('Has Methods')->not->toBeInt
+        ->name()->toEqual('Has Methods')
+        ->books()->each->toBeArray();
+});
+
 class HasMethods
 {
     public function name()
@@ -97,4 +105,9 @@ class HasMethods
             ],
         ];
     }
+
+    public function newInstance()
+    {
+        return new static();
+    }
 }

tests/Features/Expect/HigherOrder/methodsAndProperties.php

@@ -14,10 +14,20 @@ it('can access methods and properties', function () {
         );
 });
 
+it('can handle nested methods and properties', function () {
+    expect(new HasMethodsAndProperties())
+        ->meta->foo->bar->toBeString()->toEqual('baz')->not->toBeInt
+        ->newInstance()->meta->foo->toBeArray()
+        ->newInstance()->multiply(2, 2)->toEqual(4)->not->toEqual(5)
+        ->newInstance()->books()->toBeArray();
+});
+
 class HasMethodsAndProperties
 {
     public $name = 'Has Methods and Properties';
 
+    public $meta = ['foo' => ['bar' => 'baz']];
+
     public $posts = [
         [
             'is_published' => true,
@@ -47,4 +57,9 @@ class HasMethodsAndProperties
     {
         return $x * $y;
     }
+
+    public function newInstance()
+    {
+        return new static();
+    }
 }

tests/Features/Expect/HigherOrder/properties.php

@@ -58,6 +58,12 @@ it('works with objects', function () {
         );
 });
 
+it('works with nested properties', function () {
+    expect(new HasProperties())
+        ->nested->foo->bar->toBeString()->toEqual('baz')
+        ->posts->toBeArray()->toHaveCount(2);
+});
+
 class HasProperties
 {
     public $name = 'foo';
@@ -72,4 +78,8 @@ class HasProperties
             'title'        => 'Bar',
         ],
     ];
+
+    public $nested = [
+        'foo' => ['bar' => 'baz'],
+    ];
 }