alezhu/phpunit-array-contains-asserts

Provides PHPUnit assertions to test array contains data or structure

10.0.5 2025-01-30 08:13 UTC

Requires

• php: ~8.1

Requires (Dev)

• phpunit/phpunit: ^10 || ^11

MIT

• Alexandr Zhuravlev

• php
• phpunit
• phpunit-extension
• phpunit-assertions

README

Provides PHPUnit assertions to test when array-like data contains expected data with expected structure.

This PHPUnit extension was written for PHPUnit 10, but also has branches for PHPUnit 8 and PHPUnit 9 . If it doesn't work properly, please don't hesitate to open a new Issue on GitHub, or, even better, create a Pull Request with a proposed fix .

Table of contents:

1. Install
2. Usage
   1. Constraint ArrayContains
   2. Constraint ArrayContainsOnly

Install

PHPUnit arrayContains asserts is available on Packagist.org and can be installed using Composer:

composer require --dev alezhu/phpunit-array-contains-asserts

Usage

There are three (basically equivalent) options to use PHPUnitArrayAssertions:

• By using the static class Alezhu\PHPUnitArrayContainsAsserts\Assert
• By using the trait Alezhu\PHPUnitArrayContainsAsserts\ArrayContainsTrait in your test case
• By creating new constraint instances ( Alezhu\PHPUnitArrayContainsAsserts\Constraint\…)

All options do the same, the only difference is that the static class and trait both throw class Alezhu\PHPUnitArrayContainsAsserts\Exception\InvalidArgumentTypeException ( or PHPUnit\Framework\InvalidArgumentException for PHPUnit 9 and 8) exceptions for invalid parameters. Creating new constraint instances is useful for advanced assertions, e.g. together with PHPUnit\Framework\Constraint\LogicalAnd.

Constraint ArrayContains

The ArrayContains constraint asserts that an array contains all expected values (for non-associative arrays) or all expected keys with expected values (for associative arrays).

Expected values can be set directly or via another PHPUnit constraints (PHPUnit\Framework\Constraint\...).

Expected and actual data can be array or iterator or inherit ArrayObject or implements ArrayAccess+Countable interfaces.

Expected and actual data must have same associative kind.

Usage:

use Alezhu\PHPUnitArrayContainsAsserts\Assert;
use PHPUnit\Framework\Constraint\IsType;

//Passed
Assert::assertArrayContains(
    [
        "foo" => new isType(IsType::TYPE_STRING), 
        "baz" => 1
    ], 
    [
        "foo" => "value",
        "bar" => true, 
        "baz" => 1
    ]
); 
//Not Passed
Assert::assertArrayContains(
    [
        "foo" => new isType(IsType::TYPE_STRING), 
        "baz" => 1
    ], 
    [
        "foo" => "bar", 
    ]
); 

Constraint ArrayContainsOnly

The ArrayContainsOnly constraint asserts that an array contains only all expected values (for non-associative arrays) or only all expected keys with expected values (for associative arrays).

Expected values can be set directly or via another PHPUnit constraints (PHPUnit\Framework\Constraint\...).

Expected and actual data can be array or iterator or inherit ArrayObject or implements ArrayAccess+Countable interfaces.

Expected and actual data must have same associative kind.

Usage:

use Alezhu\PHPUnitArrayContainsAsserts\Assert;
use PHPUnit\Framework\Constraint\IsType;

//Passed
Assert::assertArrayContainsOnly(
    [
        "foo" => new isType(IsType::TYPE_STRING), 
        "baz" => 1
    ], 
    [
        "foo" => "value",
        "baz" => 1
    ]
); 
//Not Passed
Assert::assertArrayContainsOnly(
    [
        "foo" => new isType(IsType::TYPE_STRING), 
        "baz" => 1
    ], 
    [
        "foo" => "bar",
        "bar" => true, 
        "baz" => 1         
    ]
);