SequentialArray: Allow passing a static value as constraint

PhrozenByte · PhrozenByte · commit afc8c02b8ed2 · 2021-02-03T22:35:04.000+01:00
diff --git a/README.md b/README.md
@@ -170,7 +170,7 @@ $this->assertArrayHasKeyWith('answer', 42, $data);
 
 The [`SequentialArray` constraint](https://github.com/PhrozenByte/phpunit-array-asserts/blob/master/src/Constraint/SequentialArray.php) asserts that a value is like a sequential array, has a minimum and/or maximum number of items, and that all items pass another constraint.
 
-Sequential arrays are defined as ordered lists with incrementing numeric keys starting from zero. This is especially true for native sequential arrays like `[ "foo", "bar" ]`. Empty arrays are considered valid, too. `Traversable` objects must have sequential keys to be considered valid. The expected minimum (parameter `$minItems`, defaults to `0`) and/or maximum (parameter `$maxItems`, defaults to `null`, meaning infinite) number of items, and the constraint to apply all items to (optional parameter `$constraint`), are passed in the constructor.
+Sequential arrays are defined as ordered lists with incrementing numeric keys starting from zero. This is especially true for native sequential arrays like `[ "foo", "bar" ]`. Empty arrays are considered valid, too. `Traversable` objects must have sequential keys to be considered valid. The expected minimum (parameter `$minItems`, defaults to `0`) and/or maximum (parameter `$maxItems`, defaults to `null`, meaning infinite) number of items, and the constraint to apply all items to (optional parameter `$constraint`), are passed in the constructor. The constraint can either be an arbitrary `Constraint` instance (e.g. `PHPUnit\Framework\Constraint\StringContains`), or any static value, requiring an exact match of the value.
 
 This constraint will fully traverse any `Traversable` object given. This also means that any `Generator` will be fully exhausted. If possible, it will try to restore an `Iterator`'s pointer to its previous state.
 
@@ -181,18 +181,18 @@ The `ArrayAssertsTrait` trait exposes two public methods for the `SequentialArra
 ```php
 // using `\PhrozenByte\PHPUnitArrayAsserts\ArrayAssertsTrait` trait
 ArrayAssertsTrait::assertSequentialArray(
-    array|Traversable $array,      // the sequential array to check
-    int $minItems,                 // required minimum number of items
-    int $maxItems = null,          // required maximum number of items (pass null for infinite)
-    Constraint $constraint = null, // optional constraint to apply all items to
-    string $message = ''           // additional information about the test
+    array|Traversable $array,            // the sequential array to check
+    int $minItems,                       // required minimum number of items
+    int $maxItems = null,                // required maximum number of items (pass null for infinite)
+    Constraint|mixed $constraint = null, // optional constraint to apply all items to
+    string $message = ''                 // additional information about the test
 );
 
 // using new instance of `\PhrozenByte\PHPUnitArrayAsserts\Constraint\SequentialArray`
 new SequentialArray(
     int $minItems = 0,
     int $maxItems = null,
-    Constraint $constraint = null
+    Constraint|mixed $constraint = null
 );
 ```
 
diff --git a/src/ArrayAssertsTrait.php b/src/ArrayAssertsTrait.php
@@ -144,11 +144,11 @@ public static function arrayHasKeyWith($key, $constraint): ArrayHasKeyWith
      * Asserts that a value is like a sequential array, has a minimum and/or
      * maximum number of items, and that all items pass another constraint.
      *
-     * @param array|Traversable $array      the sequential array to check
-     * @param int               $minItems   required minimum number of items, defaults to 0
-     * @param int|null          $maxItems   required maximum number of items, defaults to NULL (infinite)
-     * @param Constraint|null   $constraint optional constraint to apply all items to (defaults to NULL)
-     * @param string            $message    additional information about the test
+     * @param array|Traversable     $array      the sequential array to check
+     * @param int                   $minItems   required minimum number of items, defaults to 0
+     * @param int|null              $maxItems   required maximum number of items, defaults to NULL (infinite)
+     * @param Constraint|mixed|null $constraint optional constraint to apply all items to (defaults to NULL)
+     * @param string                $message    additional information about the test
      *
      * @throws ExpectationFailedException
      * @throws InvalidArgumentException
@@ -158,33 +158,30 @@ public static function assertSequentialArray(
         $array,
         int $minItems,
         int $maxItems = null,
-        Constraint $constraint = null,
+        $constraint = null,
         string $message = ''
     ): void {
         if (!(is_array($array) || ($array instanceof Traversable))) {
             throw InvalidArgumentException::create(1, 'array or Traversable');
         }
 
-        $constraint = new SequentialArray($minItems, $maxItems, $constraint);
-        PHPUnitAssert::assertThat($array, $constraint, $message);
+        $itemConstraint = new SequentialArray($minItems, $maxItems, $constraint);
+        PHPUnitAssert::assertThat($array, $itemConstraint, $message);
     }
 
     /**
      * Returns a new instance of the SequentialArray constraint.
      *
-     * @param int             $minItems   required minimum number of items, defaults to 0
-     * @param int|null        $maxItems   required maximum number of items, defaults to NULL (infinite)
-     * @param Constraint|null $constraint optional constraint to apply all items to (defaults to NULL)
+     * @param int                   $minItems   required minimum number of items, defaults to 0
+     * @param int|null              $maxItems   required maximum number of items, defaults to NULL (infinite)
+     * @param Constraint|mixed|null $constraint optional constraint to apply all items to (defaults to NULL)
      *
      * @return SequentialArray
      *
      * @throws InvalidArgumentException
      */
-    public static function sequentialArray(
-        int $minItems,
-        int $maxItems = null,
-        Constraint $constraint = null
-    ): SequentialArray {
+    public static function sequentialArray(int $minItems, int $maxItems = null, $constraint = null): SequentialArray
+    {
         return new SequentialArray($minItems, $maxItems, $constraint);
     }
 
diff --git a/src/Constraint/SequentialArray.php b/src/Constraint/SequentialArray.php
@@ -25,6 +25,7 @@
 use IteratorAggregate;
 use NoRewindIterator;
 use PHPUnit\Framework\Constraint\Constraint;
+use PHPUnit\Framework\Constraint\IsEqual;
 use PHPUnit\Framework\InvalidArgumentException;
 use Traversable;
 
@@ -42,8 +43,11 @@
  * means that any Generator will be fully exhausted. If possible, it will try
  * to restore an Iterator's pointer to its previous state.
  *
- * The expected minimum and/or maximum number of items, and the constraint
- * to apply all items to, are passed in the constructor.
+ * The expected minimum and/or maximum number of items, as well as the
+ * constraint to apply all items to, are passed in the constructor. The
+ * constraint can either be an arbitrary `Constraint` instance (e.g.
+ * `PHPUnit\Framework\Constraint\StringContains`), or any static value,
+ * requiring an exact match of the value.
  */
 class SequentialArray extends Constraint
 {
@@ -59,13 +63,13 @@ class SequentialArray extends Constraint
     /**
      * SequentialArray constructor.
      *
-     * @param int             $minItems   required minimum number of items, defaults to 0
-     * @param int|null        $maxItems   required maximum number of items, defaults to NULL (infinite)
-     * @param Constraint|null $constraint optional constraint to apply all items to (defaults to NULL)
+     * @param int                   $minItems   required minimum number of items, defaults to 0
+     * @param int|null              $maxItems   required maximum number of items, defaults to NULL (infinite)
+     * @param Constraint|mixed|null $constraint optional constraint to apply all items to (defaults to NULL)
      *
      * @throws InvalidArgumentException
      */
-    public function __construct(int $minItems = 0, int $maxItems = null, Constraint $constraint = null)
+    public function __construct(int $minItems = 0, int $maxItems = null, $constraint = null)
     {
         if ($minItems < 0) {
             throw InvalidArgumentException::create(1, 'non-negative integer');
@@ -81,7 +85,10 @@ public function __construct(int $minItems = 0, int $maxItems = null, Constraint
 
         $this->minItems = $minItems;
         $this->maxItems = $maxItems;
-        $this->constraint = $constraint;
+
+        if ($constraint !== null) {
+            $this->constraint = !($constraint instanceof Constraint) ? new IsEqual($constraint) : $constraint;
+        }
     }
 
     /**
diff --git a/tests/Unit/Constraint/SequentialArrayTest.php b/tests/Unit/Constraint/SequentialArrayTest.php
@@ -39,16 +39,16 @@ class SequentialArrayTest extends TestCase
     /**
      * @dataProvider dataProviderInvalidParameters
      *
-     * @param int             $minItems
-     * @param int|null        $maxItems
-     * @param Constraint|null $constraint
-     * @param string          $expectedException
-     * @param string          $expectedExceptionMessage
+     * @param int                   $minItems
+     * @param int|null              $maxItems
+     * @param Constraint|mixed|null $constraint
+     * @param string                $expectedException
+     * @param string                $expectedExceptionMessage
      */
     public function testInvalidParameters(
         int $minItems,
         ?int $maxItems,
-        ?Constraint $constraint,
+        $constraint,
         string $expectedException,
         string $expectedExceptionMessage
     ): void {
@@ -68,18 +68,17 @@ public function dataProviderInvalidParameters(): array
     /**
      * @dataProvider dataProviderSelfDescribing
      *
-     * @param int             $minItems
-     * @param int|null        $maxItems
-     * @param Constraint|null $constraint
-     * @param string          $expectedDescription
+     * @param int                   $minItems
+     * @param int|null              $maxItems
+     * @param Constraint|mixed|null $constraint
+     * @param string                $expectedDescription
      */
-    public function testSelfDescribing(
-        int $minItems,
-        ?int $maxItems,
-        ?Constraint $constraint,
-        string $expectedDescription
-    ): void {
-        $mockedConstraint = $constraint ? $this->mockConstraint($constraint, [ 'toString' => $this->once() ]) : null;
+    public function testSelfDescribing(int $minItems, ?int $maxItems, $constraint, string $expectedDescription): void
+    {
+        $mockedConstraint = null;
+        if ($constraint !== null) {
+            $mockedConstraint = $this->mockConstraint($constraint, [ 'toString' => $this->once() ]);
+        }
 
         $itemConstraint = new SequentialArray($minItems, $maxItems, $mockedConstraint);
         $this->assertSame($expectedDescription, $itemConstraint->toString());
@@ -96,12 +95,12 @@ public function dataProviderSelfDescribing(): array
     /**
      * @dataProvider dataProviderEvaluate
      *
-     * @param int             $minItems
-     * @param int|null        $maxItems
-     * @param Constraint|null $constraint
-     * @param mixed           $other
+     * @param int                   $minItems
+     * @param int|null              $maxItems
+     * @param Constraint|mixed|null $constraint
+     * @param mixed                 $other
      */
-    public function testEvaluate(int $minItems, ?int $maxItems, ?Constraint $constraint, $other): void
+    public function testEvaluate(int $minItems, ?int $maxItems, $constraint, $other): void
     {
         $mockedConstraint = null;
         if ($constraint !== null) {
@@ -130,17 +129,17 @@ public function dataProviderEvaluate(): array
     /**
      * @dataProvider dataProviderEvaluateFail
      *
-     * @param int             $minItems
-     * @param int|null        $maxItems
-     * @param Constraint|null $constraint
-     * @param mixed           $other
-     * @param int             $expectedEvaluationCount
-     * @param string          $expectedExceptionMessage
+     * @param int                   $minItems
+     * @param int|null              $maxItems
+     * @param Constraint|mixed|null $constraint
+     * @param mixed                 $other
+     * @param int                   $expectedEvaluationCount
+     * @param string                $expectedExceptionMessage
      */
     public function testEvaluateFail(
         int $minItems,
         ?int $maxItems,
-        ?Constraint $constraint,
+        $constraint,
         $other,
         int $expectedEvaluationCount,
         string $expectedExceptionMessage
@@ -173,20 +172,20 @@ public function dataProviderEvaluateFail(): array
     /**
      * @dataProvider dataProviderPreEvaluateFail
      *
-     * @param int             $minItems
-     * @param int|null        $maxItems
-     * @param Constraint|null $constraint
-     * @param mixed           $other
-     * @param string          $expectedExceptionMessage
+     * @param int                   $minItems
+     * @param int|null              $maxItems
+     * @param Constraint|mixed|null $constraint
+     * @param mixed                 $other
+     * @param string                $expectedExceptionMessage
      */
     public function testPreEvaluateFail(
         int $minItems,
         ?int $maxItems,
-        ?Constraint $constraint,
+        $constraint,
         $other,
         string $expectedExceptionMessage
     ): void {
-        $mockedConstraint = $constraint ? $this->mockConstraint($constraint) : null;
+        $mockedConstraint = ($constraint !== null) ? $this->mockConstraint($constraint) : null;
 
         $itemConstraint = new SequentialArray($minItems, $maxItems, $mockedConstraint);
 
@@ -234,18 +233,21 @@ public function __construct()
     /**
      * @dataProvider dataProviderCountable
      *
-     * @param int             $minItems
-     * @param int|null        $maxItems
-     * @param Constraint|null $constraint
-     * @param int             $expectedCount
+     * @param int                   $minItems
+     * @param int|null              $maxItems
+     * @param Constraint|mixed|null $constraint
+     * @param int                   $expectedCount
      */
     public function testCountable(
         int $minItems,
         ?int $maxItems,
-        ?Constraint $constraint,
+        $constraint,
         int $expectedCount
     ): void {
-        $mockedConstraint = $constraint ? $this->mockConstraint($constraint, [ 'count' => $this->once() ]) : null;
+        $mockedConstraint = null;
+        if ($constraint !== null) {
+            $mockedConstraint = $this->mockConstraint($constraint, [ 'count' => $this->once() ]);
+        }
 
         $itemConstraint = new SequentialArray($minItems, $maxItems, $mockedConstraint);
         $this->assertSame($expectedCount, $itemConstraint->count());
diff --git a/tests/data/SequentialArrayTest.yml b/tests/data/SequentialArrayTest.yml
@@ -127,6 +127,37 @@ testSelfDescribing:
         constraint: *constraint
         expectedDescription: is a sequential array with ≥ 1 and ≤ 2 items matching the constraint "is awesome"
 
+    -   minItems: 0
+        maxItems: ~
+        constraint: static value
+        expectedDescription: >-
+            is a sequential array whose items match the constraint "is equal to 'static value'"
+    -   minItems: 1
+        maxItems: ~
+        constraint: static value
+        expectedDescription: >-
+            is a non-empty sequential array whose items match the constraint "is equal to 'static value'"
+    -   minItems: 2
+        maxItems: ~
+        constraint: static value
+        expectedDescription: >-
+            is a sequential array with ≥ 2 items matching the constraint "is equal to 'static value'"
+    -   minItems: 0
+        maxItems: 1
+        constraint: static value
+        expectedDescription: >-
+            is a sequential array with ≤ 1 items matching the constraint "is equal to 'static value'"
+    -   minItems: 1
+        maxItems: 1
+        constraint: static value
+        expectedDescription: >-
+            is a sequential array with exactly 1 item matching the constraint "is equal to 'static value'"
+    -   minItems: 1
+        maxItems: 2
+        constraint: static value
+        expectedDescription: >-
+            is a sequential array with ≥ 1 and ≤ 2 items matching the constraint "is equal to 'static value'"
+
 testEvaluate:
     -   minItems: 0
         maxItems: ~
@@ -171,14 +202,19 @@ testEvaluate:
         maxItems: ~
         constraint: *constraintMatch
         other: [ 1, 2, 3 ]
+    -   minItems: 0
+        maxItems: ~
+        constraint: static value
+        other: [ "static value", "static value" ]
 
 testEvaluateFail:
     -   minItems: 0
         maxItems: ~
         constraint: *constraint
         other: [ "foo", "bar", "baz" ]
         expectedEvaluationCount: 1
-        expectedExceptionMessage: Failed asserting that %s is a sequential array whose items match the constraint "is awesome".
+        expectedExceptionMessage: >-
+            Failed asserting that %s is a sequential array whose items match the constraint "is awesome".
     -   minItems: 0
         maxItems: ~
         constraint: *constraint
@@ -188,7 +224,16 @@ testEvaluateFail:
                 ~object: ArrayIterator
                 array: [ 1, 2, 3 ]
         expectedEvaluationCount: 1
-        expectedExceptionMessage: Failed asserting that %s is a sequential array whose items match the constraint "is awesome".
+        expectedExceptionMessage: >-
+            Failed asserting that %s is a sequential array whose items match the constraint "is awesome".
+    -   minItems: 0
+        maxItems: ~
+        constraint: static value
+        other: [ "other value" ]
+        expectedEvaluationCount: 1
+        expectedExceptionMessage: >-
+            Failed asserting that %s is a sequential array whose items
+            match the constraint "is equal to 'static value'".
 
 testPreEvaluateFail:
     -   minItems: 0
@@ -255,3 +300,7 @@ testCountable:
         maxItems: ~
         constraint: *constraint
         expectedCount: 3
+    -   minItems: 0
+        maxItems: ~
+        constraint: static value
+        expectedCount: 2
