AssociativeArray: Allow passing static values as constraint

PhrozenByte · PhrozenByte · commit 57b960d7f6f2 · 2021-01-30T23:41:59.000+01:00
diff --git a/README.md b/README.md
@@ -48,7 +48,7 @@ All options do the same, the only difference is that the static class and trait
 
 The [`AssociativeArray` constraint](https://github.com/PhrozenByte/phpunit-array-asserts/blob/master/src/Constraint/AssociativeArray.php) asserts that a value is an associative array matching a given structure and that the array's items pass other constraints.
 
-Any native array and `ArrayAccess` object is considered an associative array, no matter which keys they use. However, the array's items are applied to the matching constraint (parameter `$consotraints`). By default, missing items will fail the constraint (parameter `$allowMissing`, defaults to `false`). Additional items will be ignored by default (parameter `$allowAdditional`, defaults to `true`). If you want the constraint to fail when additional items exist, set this option to `true`, however, please note that this works for native arrays only. The expected keys and constraints to apply, as well as whether missing and/or additional items should fail the constraint, are passed in the constructor.
+Any native array and `ArrayAccess` object is considered an associative array, no matter which keys they use. However, the array's items are applied to the matching constraint (parameter `$consotraints`). By default, missing items will fail the constraint (parameter `$allowMissing`, defaults to `false`). Additional items will be ignored by default (parameter `$allowAdditional`, defaults to `true`). If you want the constraint to fail when additional items exist, set this option to `true`, however, please note that this works for native arrays only. The expected keys and constraints to apply, as well as whether missing and/or additional items should fail the constraint, are passed in the constructor. Constraints can either be arbitrary `Constraint` instances (e.g. `PHPUnit\Framework\Constraint\StringContains`), or any static value, requiring exact matches of the values.
 
 The `ArrayAssertsTrait` trait exposes two public methods for the `AssociativeArray` constraint: Use `ArrayAssertsTrait::assertAssociativeArray()` to perform an assertion, and `ArrayAssertsTrait::associativeArray()` to create a new instance of the `AssociativeArray` constraint.
 
@@ -57,10 +57,10 @@ The `ArrayAssertsTrait` trait exposes two public methods for the `AssociativeArr
 ```php
 // using `\PhrozenByte\PHPUnitArrayAsserts\ArrayAssertsTrait` trait
 ArrayAssertsTrait::assertAssociativeArray(
-    array $constraints,            // an associative array with the expected keys and constraints to apply
+    array $constraints,            // an array with the expected keys and constraints to apply
     array|ArrayAccess $array,      // the associative array to check
-    bool $allowMissing = false,    // whether missing items should fail the constraint
-    bool $allowAdditional = true,  // whether additional items should fail the constraint
+    bool $allowMissing = false,    // whether missing items fail the constraint
+    bool $allowAdditional = true,  // whether additional items fail the constraint
     string $message = ''           // additional information about the test
 );
 
@@ -87,7 +87,7 @@ $data = [
 //     - "options" with another associative array with the key "panic", whose value must be a boolean
 $this->assertAssociativeArray([
     'id'      => $this->isType(IsType::TYPE_INT),
-    'name'    => $this->identicalTo('Arthur Dent'),
+    'name'    => 'Arthur Dent',
     'options' => $this->associativeArray([ 'panic' => $this->isType(IsType::TYPE_BOOL) ], true)
 ], $data);
 ```
@@ -100,17 +100,17 @@ $data = [
 ];
 
 $this->assertAssociativeArray([
-    'answer' => $this->identicalTo(42)
+    'answer' => 42
 ], $data);
 
 // Will fail with the following message:
 //
 //     Failed asserting that associative array matches constraints.
-//     +----------+-------+--------------------------+
-//     | Key      | Value | Constraint               |
-//     +----------+-------+--------------------------+
-//     | 'answer' | 21    | Value is identical to 42 |
-//     +----------+-------+--------------------------+
+//     +----------+-------+----------------------+
+//     | Key      | Value | Constraint           |
+//     +----------+-------+----------------------+
+//     | 'answer' | 21    | Value is equal to 42 |
+//     +----------+-------+----------------------+
 //     [ ] Allow missing; [x] Allow additional
 ```
 
@@ -321,7 +321,7 @@ class MyTest extends TestCase
 
         $this->assertAssociativeArray([
             'id'      => $this->isType(IsType::TYPE_INT),
-            'name'    => $this->identicalTo('Arthur Dent'),
+            'name'    => 'Arthur Dent',
             'options' => $this->associativeArray([ 'panic' => $this->isType(IsType::TYPE_BOOL) ])
         ], $responseData['users'][0]);
     }
diff --git a/src/ArrayAssertsTrait.php b/src/ArrayAssertsTrait.php
@@ -52,12 +52,12 @@ trait ArrayAssertsTrait
      * Asserts that a value is an associative array matching a given structure
      * and that the array's items pass other constraints.
      *
-     * @param Constraint[]      $constraints     an associative array with the expected keys and constraints to apply
-     * @param array|ArrayAccess $array           the associative array to check
-     * @param bool              $allowMissing    whether missing items should fail the constraint (defaults to FALSE)
-     * @param bool              $allowAdditional whether additional items should fail the constraint (defaults to TRUE);
-     *                                           this option works for native arrays only
-     * @param string            $message         additional information about the test
+     * @param Constraint[]|mixed[] $constraints     an array with the expected keys and constraints to apply
+     * @param array|ArrayAccess    $array           the associative array to check
+     * @param bool                 $allowMissing    whether missing items fail the constraint (defaults to FALSE)
+     * @param bool                 $allowAdditional whether additional items fail the constraint (defaults to TRUE);
+     *                                              this option works for native arrays only
+     * @param string               $message         additional information about the test
      *
      * @throws ExpectationFailedException
      * @throws InvalidArgumentException
@@ -85,10 +85,10 @@ public static function assertAssociativeArray(
     /**
      * Returns a new instance of the AssociativeArray constraint.
      *
-     * @param Constraint[] $constraints     an associative array with the expected keys and constraints to apply
-     * @param bool         $allowMissing    whether missing items should fail the constraint (defaults to FALSE)
-     * @param bool         $allowAdditional whether additional items should fail the constraint (defaults to TRUE);
-     *                                      this option works for native arrays only
+     * @param Constraint[]|mixed[] $constraints     an array with the expected keys and constraints to apply
+     * @param bool                 $allowMissing    whether missing items fail the constraint (defaults to FALSE)
+     * @param bool                 $allowAdditional whether additional items fail the constraint (defaults to TRUE);
+     *                                              this option works for native arrays only
      *
      * @return AssociativeArray
      *
diff --git a/src/Constraint/AssociativeArray.php b/src/Constraint/AssociativeArray.php
@@ -22,6 +22,7 @@
 use ArrayAccess;
 use LucidFrame\Console\ConsoleTable;
 use PHPUnit\Framework\Constraint\Constraint;
+use PHPUnit\Framework\Constraint\IsEqual;
 use PHPUnit\Framework\InvalidArgumentException;
 
 /**
@@ -35,7 +36,9 @@
  *
  * The expected keys and constraints to apply, as well as whether additional
  * and/or missing items should fail the constraint, are passed in the
- * constructor.
+ * constructor. Constraints can either be arbitrary `Constraint` instances
+ * (e.g. `PHPUnit\Framework\Constraint\StringContains`), or any static value,
+ * requiring exact matches of the values.
  */
 class AssociativeArray extends Constraint
 {
@@ -51,21 +54,23 @@ class AssociativeArray extends Constraint
     /**
      * AssociativeArray constructor.
      *
-     * @param Constraint[] $constraints     an associative array with the expected keys and constraints to apply
-     * @param bool         $allowMissing    whether missing items should fail the constraint (defaults to FALSE)
-     * @param bool         $allowAdditional whether additional items should fail the constraint (defaults to TRUE);
-     *                                      this option works for native arrays only
+     * @param Constraint[]|mixed[] $constraints     an array with the expected keys and constraints to apply
+     * @param bool                 $allowMissing    whether missing items fail the constraint (defaults to FALSE)
+     * @param bool                 $allowAdditional whether additional items fail the constraint (defaults to TRUE);
+     *                                              this option works for native arrays only
      *
      * @throws InvalidArgumentException
      */
     public function __construct(array $constraints, bool $allowMissing = false, bool $allowAdditional = true)
     {
-        $isNoConstraint = static function ($constraint): bool { return !($constraint instanceof Constraint); };
-        if (array_filter($constraints, $isNoConstraint)) {
-            throw InvalidArgumentException::create(1, sprintf('array of %s', Constraint::class));
+        foreach ($constraints as $key => $constraint) {
+            if (!($constraint instanceof Constraint)) {
+                $constraint = new IsEqual($constraint);
+            }
+
+            $this->constraints[$key] = $constraint;
         }
 
-        $this->constraints = $constraints;
         $this->allowMissing = $allowMissing;
         $this->allowAdditional = $allowAdditional;
     }
diff --git a/tests/TestCase.php b/tests/TestCase.php
@@ -43,17 +43,21 @@ abstract class TestCase extends \PHPUnit\Framework\TestCase
     /**
      * Mocks a constraint.
      *
-     * @param Constraint        $constraint         the original constraint
+     * @param Constraint|mixed  $constraint         the original constraint
      * @param InvocationOrder[] $invocationRules    invocation rules for public methods
      * @param mixed[]|null      $evaluateParameters the expected arguments passed to the `evaluate()` method
      *
-     * @return Constraint
+     * @return Constraint|mixed
      */
     protected function mockConstraint(
-        Constraint $constraint,
+        $constraint,
         array $invocationRules = [],
         array $evaluateParameters = null
-    ): Constraint {
+    ) {
+        if (!($constraint instanceof Constraint)) {
+            return $constraint;
+        }
+
         /** @var Constraint|MockObject $mockedConstraint */
         $mockedConstraint = $this->getMockBuilder(get_class($constraint))
             ->disableOriginalConstructor()
diff --git a/tests/Unit/Constraint/AssociativeArrayTest.php b/tests/Unit/Constraint/AssociativeArrayTest.php
@@ -34,42 +34,13 @@
  */
 class AssociativeArrayTest extends TestCase
 {
-    /**
-     * @dataProvider dataProviderInvalidParameters
-     *
-     * @param Constraint[] $constraints
-     * @param bool         $allowMissing
-     * @param bool         $allowAdditional
-     * @param string       $expectedException
-     * @param string       $expectedExceptionMessage
-     */
-    public function testInvalidParameters(
-        array $constraints,
-        bool $allowMissing,
-        bool $allowAdditional,
-        string $expectedException,
-        string $expectedExceptionMessage
-    ): void {
-        $this->assertCallableThrows(static function () use ($constraints, $allowMissing, $allowAdditional) {
-            new AssociativeArray($constraints, $allowMissing, $allowAdditional);
-        }, $expectedException, $expectedExceptionMessage);
-    }
-
-    /**
-     * @return array[]
-     */
-    public function dataProviderInvalidParameters(): array
-    {
-        return $this->getTestDataSets('testInvalidParameters');
-    }
-
     /**
      * @dataProvider dataProviderSelfDescribing
      *
-     * @param Constraint[] $constraints
-     * @param bool         $allowMissing
-     * @param bool         $allowAdditional
-     * @param string       $expectedDescription
+     * @param Constraint[]|mixed[] $constraints
+     * @param bool                 $allowMissing
+     * @param bool                 $allowAdditional
+     * @param string               $expectedDescription
      */
     public function testSelfDescribing(
         array $constraints,
@@ -94,11 +65,11 @@ public function dataProviderSelfDescribing(): array
     /**
      * @dataProvider dataProviderEvaluate
      *
-     * @param Constraint[] $constraints
-     * @param bool         $allowMissing
-     * @param bool         $allowAdditional
-     * @param mixed        $other
-     * @param mixed[]      $expectedEvaluationValues
+     * @param Constraint[]|mixed[] $constraints
+     * @param bool                 $allowMissing
+     * @param bool                 $allowAdditional
+     * @param mixed                $other
+     * @param mixed[]              $expectedEvaluationValues
      */
     public function testEvaluate(
         array $constraints,
@@ -139,12 +110,12 @@ public function dataProviderEvaluate(): array
     /**
      * @dataProvider dataProviderEvaluateFail
      *
-     * @param Constraint[] $constraints
-     * @param bool         $allowMissing
-     * @param bool         $allowAdditional
-     * @param mixed        $other
-     * @param mixed[]      $expectedEvaluationValues
-     * @param string       $expectedExceptionMessage
+     * @param Constraint[]|mixed[] $constraints
+     * @param bool                 $allowMissing
+     * @param bool                 $allowAdditional
+     * @param mixed                $other
+     * @param mixed[]              $expectedEvaluationValues
+     * @param string               $expectedExceptionMessage
      */
     public function testEvaluateFail(
         array $constraints,
@@ -187,11 +158,11 @@ public function dataProviderEvaluateFail(): array
     /**
      * @dataProvider dataProviderPreEvaluateFail
      *
-     * @param Constraint[] $constraints
-     * @param bool         $allowMissing
-     * @param bool         $allowAdditional
-     * @param mixed        $other
-     * @param string       $expectedExceptionMessage
+     * @param Constraint[]|mixed[] $constraints
+     * @param bool                 $allowMissing
+     * @param bool                 $allowAdditional
+     * @param mixed                $other
+     * @param string               $expectedExceptionMessage
      */
     public function testPreEvaluateFail(
         array $constraints,
@@ -222,10 +193,10 @@ public function dataProviderPreEvaluateFail(): array
     /**
      * @dataProvider dataProviderCountable
      *
-     * @param Constraint[] $constraints
-     * @param bool         $allowMissing
-     * @param bool         $allowAdditional
-     * @param int          $expectedCount
+     * @param Constraint[]|mixed[] $constraints
+     * @param bool                 $allowMissing
+     * @param bool                 $allowAdditional
+     * @param int                  $expectedCount
      */
     public function testCountable(
         array $constraints,
@@ -248,9 +219,9 @@ public function dataProviderCountable(): array
     }
 
     /**
-     * @param Constraint[]      $constraints
-     * @param InvocationOrder[] $invocationRules
-     * @param mixed[][]         $evaluateParameters
+     * @param Constraint[]|mixed[] $constraints
+     * @param InvocationOrder[]    $invocationRules
+     * @param mixed[][]            $evaluateParameters
      *
      * @return Constraint[]
      */
diff --git a/tests/data/AssociativeArrayTest.yml b/tests/data/AssociativeArrayTest.yml
@@ -60,6 +60,9 @@
                     toString: matches something
                     matches: false
                     count: 4
+    constraintsStatic: &constraintsStatic
+        constraints:
+            item: static value
 
     constraintsNoneMatch: &constraintsNoneMatch
         <<: *constraintsNone
@@ -76,16 +79,6 @@
                 item2: { options: { matches: true } }
                 item3: { options: { matches: true } }
 
-testInvalidParameters:
-    -   constraints:
-            - "this is no constraint"
-        allowMissing: false
-        allowAdditional: true
-        expectedException: PHPUnit\Framework\InvalidArgumentException
-        expectedExceptionMessage: >-
-            Argument #1 of PhrozenByte\PHPUnitArrayAsserts\Constraint\AssociativeArray::__construct()
-            must be an array of PHPUnit\Framework\Constraint\Constraint
-
 testSelfDescribing:
     -   <<: [ *constraintsNone, *paramsDefault ]
         expectedDescription: is an associative array
@@ -143,10 +136,21 @@ testSelfDescribing:
             the key 'item2' whose value is funny, and/or
             the key 'item3' whose value matches something
 
+    -   <<: [ *constraintsStatic, *paramsDefault ]
+        expectedDescription: >-
+            is an associative array that
+            has the key 'item' whose value is equal to 'static value', and
+            any other item
+
 testEvaluate:
     -   <<: [ *constraintsNoneMatch, *paramsDefault ]
         other: ~
         expectedEvaluationValues: {}
+    -   <<: [ *constraintsStatic, *paramsDefault ]
+        other:
+            item: static value
+        expectedEvaluationValues:
+            item: static value
 
     -   <<: [ *constraintsNoneMatch, *paramsDefault ]
         other: {}
@@ -239,6 +243,19 @@ testEvaluateFail:
             | 'item3' |        | Value matches something |
             +---------+--------+-------------------------+
             [x] Allow missing; [x] Allow additional
+    -   <<: [ *constraintsStatic, *paramsDefault ]
+        other:
+            item: other value
+        expectedEvaluationValues:
+            item: other value
+        expectedExceptionMessage: |
+            Failed asserting that associative array matches constraints.
+            +--------+---------------+----------------------------------+
+            | Key    | Value         | Constraint                       |
+            +--------+---------------+----------------------------------+
+            | 'item' | 'other value' | Value is equal to 'static value' |
+            +--------+---------------+----------------------------------+
+            [ ] Allow missing; [x] Allow additional
 
 testPreEvaluateFail:
     -   <<: [ *constraintsSingle, *paramsDefault ]
@@ -340,3 +357,5 @@ testCountable:
         expectedCount: 1
     -   <<: [ *constraintsMultiple, *paramsDefault ]
         expectedCount: 10
+    -   <<: [ *constraintsStatic, *paramsDefault ]
+        expectedCount: 2
