ArrayAssertsTrait: Add methods to create constraint instances

Author: PhrozenByte

README.md

@@ -68,10 +68,10 @@ $data = [
 //     - "id" with a numeric value,
 //     - "name" with the value "Arthur Dent", and
 //     - "options" with another associative array with the key "panic", whose value must be a boolean
-self::assertAssociativeArray([
-    'id'      => new IsType(IsType::TYPE_INT),
-    'name'    => new IsIdentical('Arthur Dent'),
-    'options' => new AssociativeArray([ 'panic' => new IsType(IsType::TYPE_BOOL) ], true)
+$this->assertAssociativeArray([
+    'id'      => $this->isType(IsType::TYPE_INT),
+    'name'    => $this->identicalTo('Arthur Dent'),
+    'options' => $this->associativeArray([ 'panic' => $this->isType(IsType::TYPE_BOOL) ], true)
 ], $data);
 ```
 
@@ -109,7 +109,7 @@ $data = [
 ];
 
 // asserts that $data has the item `name` with the value "Arthur Dent"
-self::ArrayHasKeyWith('name', new IsIdentical('Arthur Dent'), $data);
+$this->assertArrayHasKeyWith('name', $this->identicalTo('Arthur Dent'), $data);
 ```
 
 ### Constraint `SequentialArray`
@@ -153,7 +153,7 @@ $data = [
 ];
 
 // asserts that `$data` is a non-empty sequential array with non-empty items
-self::assertSequentialArray($data, 1, null, self::logicalNot(new IsEmpty()));
+$this->assertSequentialArray($data, 1, null, $this->logicalNot($this->isEmpty()));
 ```
 
 ### Constraint `ArrayHasItemWith`
@@ -195,7 +195,7 @@ $data = [
 ];
 
 // asserts that `$data` contains "Life, the Universe and Everything" as third item (i.e. at index 2)
-self::ArrayHasItemWith(2, new IsIdentical("Life, the Universe and Everything""));
+$this->assertArrayHasItemWith(2, $this->identicalTo("Life, the Universe and Everything"));
 ```
 
 Example
@@ -207,19 +207,18 @@ declare(strict_types=1);
 
 namespace YourName\YourProject\Tests;
 
-use PHPUnit\Framework\Constraint\IsIdentical;
 use PHPUnit\Framework\Constraint\IsType;
 use PHPUnit\Framework\TestCase;
 use PhrozenByte\PHPUnitArrayAsserts\ArrayAssertsTrait;
-use PhrozenByte\PHPUnitArrayAsserts\Constraint\AssociativeArray;
-use PhrozenByte\PHPUnitArrayAsserts\Constraint\SequentialArray;
 
 class MyTest extends TestCase
 {
     use ArrayAssertsTrait;
 
     public function testWithPHPUnitArrayAsserts(): void
     {
+        // 7 lines of easy to understand code to check the API response *with* PHPUnitArrayAsserts
+
         // implement your test, the result is stored in $responseData
 
         $responseData = [
@@ -232,19 +231,19 @@ class MyTest extends TestCase
             ]
         ];
 
-        $this->assertArrayHasKeyWith('users', new SequentialArray(1), $responseData);
+        $this->assertArrayHasKeyWith('users', $this->sequentialArray(1), $responseData);
 
         $this->assertAssociativeArray([
-            'id'      => new IsType(IsType::TYPE_INT),
-            'name'    => new IsIdentical('Arthur Dent'),
-            'options' => new AssociativeArray([ 'panic' => new IsType(IsType::TYPE_BOOL) ], true)
+            'id'      => $this->isType(IsType::TYPE_INT),
+            'name'    => $this->identicalTo('Arthur Dent'),
+            'options' => $this->associativeArray([ 'panic' => $this->isType(IsType::TYPE_BOOL) ], true)
         ], $responseData['users'][0]);
-
-        // 7 lines of easier to understand code to check the API response *with* PHPUnitArrayAsserts
     }
 
     public function testWithoutPHPUnitArrayAsserts(): void
     {
+        // 18 lines of pretty repetitive code to check the API response *without* PHPUnitArrayAsserts
+
         // implement your test, the result is stored in $responseData
 
         $responseData = [
@@ -275,8 +274,6 @@ class MyTest extends TestCase
 
         $this->assertArrayHasKey('panic', $userData['options']);
         $this->assertIsBool($userData['options']['bool']);
-
-        // 18 lines of pretty repetitive code to check the API response *without* PHPUnitArrayAsserts
     }
 }
 ```

src/ArrayAssertsTrait.php

@@ -67,6 +67,25 @@ public static function assertAssociativeArray(
         PHPUnitAssert::assertThat($array, $constraint, $message);
     }
 
+    /**
+     * Returns a new instance of the AssociativeArray constraint.
+     *
+     * @param Constraint[] $constraints     an associative array with the expected keys and constraints to apply
+     * @param bool         $allowAdditional whether additional items should fail the constraint (defaults to FALSE)
+     * @param bool         $allowMissing    whether missing items should fail the constraint (defaults to FALSE)
+     *
+     * @return AssociativeArray
+     *
+     * @throws Exception
+     */
+    public static function associativeArray(
+        array $constraints,
+        bool $allowAdditional = false,
+        bool $allowMissing = false
+    ): AssociativeArray {
+        return new AssociativeArray($constraints, $allowAdditional, $allowMissing);
+    }
+
     /**
      * Asserts that an array has a given key and that its value passes another
      * constraint.
@@ -94,6 +113,21 @@ public static function assertArrayHasKeyWith($key, Constraint $constraint, $arra
         PHPUnitAssert::assertThat($array, $constraint, $message);
     }
 
+    /**
+     * Returns a new instance of the ArrayHasKeyWith constraint.
+     *
+     * @param int|string $key        the key of the item to check
+     * @param Constraint $constraint the constraint the item's value is applied to
+     *
+     * @return ArrayHasKeyWith
+     *
+     * @throws Exception
+     */
+    public static function arrayHasKeyWith($key, Constraint $constraint): ArrayHasKeyWith
+    {
+        return new ArrayHasKeyWith($key, $constraint);
+    }
+
     /**
      * 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.
@@ -135,6 +169,25 @@ public static function assertSequentialArray(
         PHPUnitAssert::assertThat($array, $constraint, $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)
+     *
+     * @return SequentialArray
+     *
+     * @throws Exception
+     */
+    public static function sequentialArray(
+        int $minItems,
+        int $maxItems = null,
+        Constraint $constraint = null
+    ): SequentialArray {
+        return new SequentialArray($minItems, $maxItems, $constraint);
+    }
+
     /**
      * Asserts that an array has a item at a given index and that its value
      * passes another constraint.
@@ -157,4 +210,19 @@ public static function assertArrayHasItemWith(int $index, Constraint $constraint
         $constraint = new ArrayHasItemWith($index, $constraint);
         PHPUnitAssert::assertThat($array, $constraint, $message);
     }
+
+    /**
+     * Returns a new instance of the ArrayHasItemWith constraint.
+     *
+     * @param int        $index      the index of the item to check
+     * @param Constraint $constraint the constraint the item's value is applied to
+     *
+     * @return ArrayHasItemWith
+     *
+     * @throws Exception
+     */
+    public static function arrayHasItemWith(int $index, Constraint $constraint): ArrayHasItemWith
+    {
+        return new ArrayHasItemWith($index, $constraint);
+    }
 }