Closes #5600

sebastianbergmann · Dec 12, 2023 · 04a892c · 04a892c
1 parent 0fc2a23
commit 04a892c
Show file tree

Hide file tree

Showing 4 changed files with 214 additions and 0 deletions.
diff --git a/ChangeLog-11.0.md b/ChangeLog-11.0.md
@@ -4,6 +4,10 @@ All notable changes of the PHPUnit 11.0 release series are documented in this fi
 
 ## [11.0.0] - 2024-02-02
 
+### Added
+
+* [#5600](https://github.com/sebastianbergmann/phpunit/pull/5600): Assertions for comparing arrays while ignoring a specified list of keys
+
 ### Changed
 
 * [#5213](https://github.com/sebastianbergmann/phpunit/issues/5213): Make `TestCase` methods `protected` that should have been `protected` all along

diff --git a/src/Framework/Assert.php b/src/Framework/Assert.php
@@ -9,9 +9,11 @@
  */
 namespace PHPUnit\Framework;
 
+use function array_keys;
 use function class_exists;
 use function count;
 use function file_get_contents;
+use function in_array;
 use function interface_exists;
 use function is_bool;
 use ArrayAccess;
@@ -72,6 +74,90 @@ abstract class Assert
 {
     private static int $count = 0;
 
+    /**
+     * Asserts that two arrays are equal while only considering a list of keys.
+     *
+     * @psalm-param non-empty-list<array-key> $keysToBeConsidered
+     *
+     * @throws Exception
+     * @throws ExpectationFailedException
+     */
+    final public static function assertArrayIsEqualToArrayOnlyConsideringListOfKeys(array $expected, array $actual, array $keysToBeConsidered, string $message = ''): void
+    {
+        foreach (array_keys($expected) as $key) {
+            if (!in_array($key, $keysToBeConsidered, true)) {
+                unset($expected[$key]);
+            }
+        }
+
+        foreach (array_keys($actual) as $key) {
+            if (!in_array($key, $keysToBeConsidered, true)) {
+                unset($actual[$key]);
+            }
+        }
+
+        static::assertEquals($expected, $actual, $message);
+    }
+
+    /**
+     * Asserts that two arrays are equal while ignoring a list of keys.
+     *
+     * @psalm-param non-empty-list<array-key> $keysToBeIgnored
+     *
+     * @throws Exception
+     * @throws ExpectationFailedException
+     */
+    final public static function assertArrayIsEqualToArrayIgnoringListOfKeys(array $expected, array $actual, array $keysToBeIgnored, string $message = ''): void
+    {
+        foreach ($keysToBeIgnored as $key) {
+            unset($expected[$key], $actual[$key]);
+        }
+
+        static::assertEquals($expected, $actual, $message);
+    }
+
+    /**
+     * Asserts that two arrays are identical while only considering a list of keys.
+     *
+     * @psalm-param non-empty-list<array-key> $keysToBeConsidered
+     *
+     * @throws Exception
+     * @throws ExpectationFailedException
+     */
+    final public static function assertArrayIsIdenticalToArrayOnlyConsideringListOfKeys(array $expected, array $actual, array $keysToBeConsidered, string $message = ''): void
+    {
+        foreach (array_keys($expected) as $key) {
+            if (!in_array($key, $keysToBeConsidered, true)) {
+                unset($expected[$key]);
+            }
+        }
+
+        foreach (array_keys($actual) as $key) {
+            if (!in_array($key, $keysToBeConsidered, true)) {
+                unset($actual[$key]);
+            }
+        }
+
+        static::assertSame($expected, $actual, $message);
+    }
+
+    /**
+     * Asserts that two arrays are equal while ignoring a list of keys.
+     *
+     * @psalm-param non-empty-list<array-key> $keysToBeIgnored
+     *
+     * @throws Exception
+     * @throws ExpectationFailedException
+     */
+    final public static function assertArrayIsIdenticalToArrayIgnoringListOfKeys(array $expected, array $actual, array $keysToBeIgnored, string $message = ''): void
+    {
+        foreach ($keysToBeIgnored as $key) {
+            unset($expected[$key], $actual[$key]);
+        }
+
+        static::assertSame($expected, $actual, $message);
+    }
+
     /**
      * Asserts that an array has a specified key.
      *

diff --git a/src/Framework/Assert/Functions.php b/src/Framework/Assert/Functions.php
@@ -69,6 +69,82 @@
 use PHPUnit\Util\Xml\XmlException;
 use Throwable;
 
+if (!function_exists('PHPUnit\Framework\assertArrayIsEqualToArrayOnlyConsideringListOfKeys')) {
+    /**
+     * Asserts that two arrays are equal while only considering a list of keys.
+     *
+     * @psalm-param list<array-key> $keysToBeConsidered
+     *
+     * @throws Exception
+     * @throws ExpectationFailedException
+     *
+     * @no-named-arguments Parameter names are not covered by the backward compatibility promise for PHPUnit
+     *
+     * @see Assert::assertArrayIsEqualToArrayOnlyConsideringListOfKeys
+     */
+    function assertArrayIsEqualToArrayOnlyConsideringListOfKeys(array $expected, array $actual, array $keysToBeConsidered, string $message = ''): void
+    {
+        Assert::assertArrayIsEqualToArrayOnlyConsideringListOfKeys(...func_get_args());
+    }
+}
+
+if (!function_exists('PHPUnit\Framework\assertArrayIsEqualToArrayIgnoringListOfKeys')) {
+    /**
+     * Asserts that two arrays are equal while ignoring a list of keys.
+     *
+     * @psalm-param list<array-key> $keysToBeIgnored
+     *
+     * @throws Exception
+     * @throws ExpectationFailedException
+     *
+     * @no-named-arguments Parameter names are not covered by the backward compatibility promise for PHPUnit
+     *
+     * @see Assert::assertArrayIsEqualToArrayIgnoringListOfKeys
+     */
+    function assertArrayIsEqualToArrayIgnoringListOfKeys(array $expected, array $actual, array $keysToBeIgnored, string $message = ''): void
+    {
+        Assert::assertArrayIsEqualToArrayIgnoringListOfKeys(...func_get_args());
+    }
+}
+
+if (!function_exists('PHPUnit\Framework\assertArrayIsIdenticalToArrayOnlyConsideringListOfKeys')) {
+    /**
+     * Asserts that two arrays are identical while only considering a list of keys.
+     *
+     * @psalm-param list<array-key> $keysToBeConsidered
+     *
+     * @throws Exception
+     * @throws ExpectationFailedException
+     *
+     * @no-named-arguments Parameter names are not covered by the backward compatibility promise for PHPUnit
+     *
+     * @see Assert::assertArrayIsIdenticalToArrayOnlyConsideringListOfKeys
+     */
+    function assertArrayIsIdenticalToArrayOnlyConsideringListOfKeys(array $expected, array $actual, array $keysToBeConsidered, string $message = ''): void
+    {
+        Assert::assertArrayIsIdenticalToArrayOnlyConsideringListOfKeys(...func_get_args());
+    }
+}
+
+if (!function_exists('PHPUnit\Framework\assertArrayIsIdenticalToArrayIgnoringListOfKeys')) {
+    /**
+     * Asserts that two arrays are equal while ignoring a list of keys.
+     *
+     * @psalm-param list<array-key> $keysToBeIgnored
+     *
+     * @throws Exception
+     * @throws ExpectationFailedException
+     *
+     * @no-named-arguments Parameter names are not covered by the backward compatibility promise for PHPUnit
+     *
+     * @see Assert::assertArrayIsIdenticalToArrayIgnoringListOfKeys
+     */
+    function assertArrayIsIdenticalToArrayIgnoringListOfKeys(array $expected, array $actual, array $keysToBeIgnored, string $message = ''): void
+    {
+        Assert::assertArrayIsIdenticalToArrayIgnoringListOfKeys(...func_get_args());
+    }
+}
+
 if (!function_exists('PHPUnit\Framework\assertArrayHasKey')) {
     /**
      * Asserts that an array has a specified key.

diff --git a/tests/unit/Framework/AssertTest.php b/tests/unit/Framework/AssertTest.php
@@ -143,6 +143,54 @@ public function testAssertContainsOnlyInstancesOf(): void
         $this->assertContainsOnlyInstancesOf(Book::class, $test2);
     }
 
+    public function testAssertArrayIsEqualToArrayOnlyConsideringListOfKeys(): void
+    {
+        $expected = ['a' => 'b', 'b' => 'c', 0 => 1, 1 => 2];
+        $actual   = ['a' => 'b', 'b' => 'b', 0 => 1, 1 => 3];
+
+        $this->assertArrayIsEqualToArrayOnlyConsideringListOfKeys($expected, $actual, ['a', 0]);
+
+        $this->expectException(AssertionFailedError::class);
+
+        $this->assertArrayIsEqualToArrayOnlyConsideringListOfKeys($expected, $actual, ['b']);
+    }
+
+    public function testAssertArrayIsEqualToArrayIgnoringListOfKeys(): void
+    {
+        $expected = ['a' => 'b', 'b' => 'c', 0 => 1, 1 => 2];
+        $actual   = ['a' => 'b', 'b' => 'b', 0 => 1, 1 => 3];
+
+        $this->assertArrayIsEqualToArrayIgnoringListOfKeys($expected, $actual, ['b', 1]);
+
+        $this->expectException(AssertionFailedError::class);
+
+        $this->assertArrayIsEqualToArrayIgnoringListOfKeys($expected, $actual, ['b']);
+    }
+
+    public function testAssertArrayIsIdenticalToArrayOnlyConsideringListOfKeys(): void
+    {
+        $expected = ['a' => 'b', 'b' => 'c', 0 => 1, 1 => 2];
+        $actual   = ['a' => 'b', 'b' => 'b', 0 => 1, 1 => 3];
+
+        $this->assertArrayIsIdenticalToArrayOnlyConsideringListOfKeys($expected, $actual, ['a', 0]);
+
+        $this->expectException(AssertionFailedError::class);
+
+        $this->assertArrayIsIdenticalToArrayOnlyConsideringListOfKeys($expected, $actual, ['b']);
+    }
+
+    public function testAssertArrayIsIdenticalToArrayIgnoringListOfKeys(): void
+    {
+        $expected = ['a' => 'b', 'b' => 'c', 0 => 1, 1 => 2];
+        $actual   = ['a' => 'b', 'b' => 'b', 0 => 1, 1 => 3];
+
+        $this->assertArrayIsIdenticalToArrayIgnoringListOfKeys($expected, $actual, ['b', 1]);
+
+        $this->expectException(AssertionFailedError::class);
+
+        $this->assertArrayIsIdenticalToArrayIgnoringListOfKeys($expected, $actual, ['b']);
+    }
+
     public function testAssertArrayHasIntegerKey(): void
     {
         $this->assertArrayHasKey(0, ['foo']);