Phpunit Arraysubset Asserts Laravel Package

Getting Started

Install the package with Composer in your --dev dependencies:

composer require --dev dms/phpunit-arraysubset-asserts

Once installed, you can begin using assertArraySubset() immediately. This is especially valuable if your tests rely on the removed assertArraySubset() method from PHPUnit 8+ — the package acts as a drop-in polyfill.

First use case: Verify a subset of keys/values exists in an associative array (e.g., asserting a subset of a database result or API response):

$this->assertArraySubset(['name' => 'John'], $user);

Start with the trait approach to preserve existing test code:

use DMS\PHPUnitExtensions\ArraySubset\ArraySubsetAsserts;

class UserTest extends TestCase
{
    use ArraySubsetAsserts;
    // ...
}

Implementation Patterns

• Trait usage (recommended for most teams)
  Add ArraySubsetAsserts trait to your test classes or base TestCase. This maintains the familiar assertArraySubset() method signature without modifying calls. Ideal when migrating from older PHPUnit versions.

• Static class usage (Assert)
  Use Assert::assertArraySubset() when traits aren’t preferred (e.g., for explicit clarity or in shared test utilities). Avoids trait naming conflicts and can be easier to stub/mock.

• Loose vs strict comparison
  The third parameter enables strict mode:

  // Loose (default): '0' == 0
  $this->assertArraySubset(['count' => 0], ['count' => '0']); // passes
  
  // Strict: '0' !== 0
  $this->assertArraySubset(['count' => 0], ['count' => '0'], true); // fails
  

• Nested subsets
  Supports nested array subsets recursively:

  $expected = ['user' => ['name' => 'Alice', 'role' => 'admin']];
  $actual   = ['user' => ['name' => 'Alice', 'role' => 'admin', 'extra' => 'ignored']];
  $this->assertArraySubset($expected, $actual);
  

• Object-to-array conversion
  Works with ArrayObject, Traversables, and custom classes implementing \ArrayAccess — the package auto-converts them to arrays before comparison.

Gotchas and Tips

• Version-aware behavior:
  In PHPUnit ≤7, the native assertArraySubset() is used. The polyfill only kicks in for PHPUnit 8+. If mixing environments (e.g., CI vs local), verify PHPUnit version to avoid surprises.

• Strict mode pitfalls:
  Strict mode (true third arg) does not compare object instances — only array structures and values. For deep object comparison, consider assertEquals or custom rules.

• PHP 8.1+ deprecation notice:
  Fixed in v0.3.1+ — ensure you’re on a recent version (^0.5.0) to avoid assertOptions() function signature warnings.

• Trailing whitespace/zero-padding:
  When using loose comparison, numeric strings like '007' and integer 7 match. Enable strict mode if precision matters.

• Missing keys vs null values:
  The assertion fails if a key is missing or if the value is null but expected key exists. To ignore nulls, filter your expected array before asserting.

• Debugging:
  Use --verbose flag in PHPUnit to get detailed diffs on failure, especially helpful for deeply nested subsets.

• Extensibility:
  The core logic lives in ArraySubsetAsserts — override methods in your TestCase base class if you need custom behavior (e.g., case-insensitive string matching on keys).