1. Assertions

This appendix lists the various assertion methods that are available.

Static vs. Non-Static Usage of Assertion Methods

PHPUnit’s assertions are implemented in PHPUnit\Framework\Assert. PHPUnit\Framework\TestCase inherits from PHPUnit\Framework\Assert.

The assertion methods are declared static and can be invoked from any context using PHPUnit\Framework\Assert::assertTrue(), for instance, or using $this->assertTrue() or self::assertTrue(), for instance, in a class that extends PHPUnit\Framework\TestCase. You can even use global function wrappers such as assertTrue().

A common question, especially from developers new to PHPUnit, is whether using $this->assertTrue() or self::assertTrue(), for instance, is “the right way” to invoke an assertion. The short answer is: there is no right way. And there is no wrong way, either. It is a matter of personal preference.

For most people it just “feels right” to use $this->assertTrue() because the test method is invoked on a test object. The fact that the assertion methods are declared static allows for (re)using them outside the scope of a test object. Lastly, the global function wrappers allow developers to type less characters (assertTrue() instead of $this->assertTrue() or self::assertTrue()).

Boolean

assertTrue()

assertTrue(bool $condition[, string $message])

Reports an error identified by $message if $condition is false.

assertNotTrue() is the inverse of this assertion and takes the same arguments.

Example 1.1 Usage of assertTrue()
<?php declare(strict_types=1);
use PHPUnit\Framework\TestCase;

final class TrueTest extends TestCase
{
    public function testFailure(): void
    {
        $this->assertTrue(false);
    }
}

Running the test shown above yields the output shown below:

./tools/phpunit tests/TrueTest.php
PHPUnit 11.4.3 by Sebastian Bergmann and contributors.

Runtime:       PHP 8.4.1

F                                                                   1 / 1 (100%)

Time: 00:00, Memory: 25.14 MB

There was 1 failure:

1) TrueTest::testFailure
Failed asserting that false is true.

/path/to/tests/TrueTest.php:8

FAILURES!
Tests: 1, Assertions: 1, Failures: 1.

assertFalse()

assertFalse(bool $condition[, string $message])

Reports an error identified by $message if $condition is true.

assertNotFalse() is the inverse of this assertion and takes the same arguments.

Example 1.2 Usage of assertFalse()
<?php declare(strict_types=1);
use PHPUnit\Framework\TestCase;

final class FalseTest extends TestCase
{
    public function testFailure(): void
    {
        $this->assertFalse(true);
    }
}

Running the test shown above yields the output shown below:

./tools/phpunit tests/FalseTest.php
PHPUnit 11.4.3 by Sebastian Bergmann and contributors.

Runtime:       PHP 8.4.1

F                                                                   1 / 1 (100%)

Time: 00:00, Memory: 25.14 MB

There was 1 failure:

1) FalseTest::testFailure
Failed asserting that true is false.

/path/to/tests/FalseTest.php:8

FAILURES!
Tests: 1, Assertions: 1, Failures: 1.

Identity

assertSame()

assertSame(mixed $expected, mixed $actual[, string $message])

Reports an error identified by $message if the two variables $expected and $actual do not have the same type and value.

assertNotSame() is the inverse of this assertion and takes the same arguments.

Example 1.3 Usage of assertSame()
<?php declare(strict_types=1);
use PHPUnit\Framework\TestCase;

final class SameWithMixedTest extends TestCase
{
    public function testFailure(): void
    {
        $this->assertSame('2204', 2204);
    }
}

Running the test shown above yields the output shown below:

./tools/phpunit tests/SameWithMixedTest.php
PHPUnit 11.4.3 by Sebastian Bergmann and contributors.

Runtime:       PHP 8.4.1

F                                                                   1 / 1 (100%)

Time: 00:00, Memory: 25.14 MB

There was 1 failure:

1) SameWithMixedTest::testFailure
Failed asserting that 2204 is identical to '2204'.

/path/to/tests/SameWithMixedTest.php:8

FAILURES!
Tests: 1, Assertions: 1, Failures: 1.

assertSame(object $expected, object $actual[, string $message])

Reports an error identified by $message if the two variables $expected and $actual do not reference the same object.

Example 1.4 Usage of assertSame() with objects
<?php declare(strict_types=1);
use PHPUnit\Framework\TestCase;

final class SameWithObjectsTest extends TestCase
{
    public function testFailure(): void
    {
        $this->assertSame(new stdClass, new stdClass);
    }
}

Running the test shown above yields the output shown below:

./tools/phpunit tests/SameWithObjectsTest.php
PHPUnit 11.4.3 by Sebastian Bergmann and contributors.

Runtime:       PHP 8.4.1

F                                                                   1 / 1 (100%)

Time: 00:00, Memory: 25.14 MB

There was 1 failure:

1) SameWithObjectsTest::testFailure
Failed asserting that two variables reference the same object.

/path/to/tests/SameWithObjectsTest.php:8

FAILURES!
Tests: 1, Assertions: 1, Failures: 1.

Identity is checked using the === operator.

assertArrayIsIdenticalToArrayOnlyConsideringListOfKeys()

assertArrayIsIdenticalToArrayOnlyConsideringListOfKeys(array $expected, array $actual, array $keysToBeConsidered[, string $message])

Reports an error identified by $message if two arrays are not identical while only considering array elements for which the keys have been specified.

Example 1.5 Usage of assertArrayIsIdenticalToArrayOnlyConsideringListOfKeys()
<?php declare(strict_types=1);
use PHPUnit\Framework\TestCase;

final class ArrayIsIdenticalToArrayOnlyConsideringListOfKeysTest extends TestCase
{
    public function testFailure(): void
    {
        $this->assertArrayIsIdenticalToArrayOnlyConsideringListOfKeys(
            [
                'timestamp' => time(),
                'foo'       => 'bar',
            ],
            [
                'timestamp' => time(),
                'foo'       => 'baz',
            ],
            [
                'foo',
            ]
        );
    }
}

Running the test shown above yields the output shown below:

./tools/phpunit tests/ArrayIsIdenticalToArrayOnlyConsideringListOfKeysTest.php
PHPUnit 11.4.3 by Sebastian Bergmann and contributors.

Runtime:       PHP 8.4.1

F                                                                   1 / 1 (100%)

Time: 00:00, Memory: 25.14 MB

There was 1 failure:

1) ArrayIsIdenticalToArrayOnlyConsideringListOfKeysTest::testFailure
Failed asserting that two arrays are identical.
--- Expected
+++ Actual
@@ @@
 Array &0 [
-    'foo' => 'bar',
+    'foo' => 'baz',
 ]

/path/to/tests/ArrayIsIdenticalToArrayOnlyConsideringListOfKeysTest.php:8

FAILURES!
Tests: 1, Assertions: 1, Failures: 1.

assertArrayIsIdenticalToArrayIgnoringListOfKeys()

assertArrayIsIdenticalToArrayIgnoringListOfKeys(array $expected, array $actual, array $keysToBeIgnored[, string $message])

Reports an error identified by $message if two arrays are not identical while only ignoring array elements for which the keys have been specified.

Example 1.6 Usage of assertArrayIsIdenticalToArrayIgnoringListOfKeys()
<?php declare(strict_types=1);
use PHPUnit\Framework\TestCase;

final class ArrayIsIdenticalToArrayIgnoringListOfKeysTest extends TestCase
{
    public function testFailure(): void
    {
        $this->assertArrayIsIdenticalToArrayIgnoringListOfKeys(
            [
                'timestamp' => time(),
                'foo'       => 'bar',
            ],
            [
                'timestamp' => time(),
                'foo'       => 'baz',
            ],
            [
                'timestamp',
            ]
        );
    }
}

Running the test shown above yields the output shown below:

./tools/phpunit tests/ArrayIsIdenticalToArrayIgnoringListOfKeysTest.php
PHPUnit 11.4.3 by Sebastian Bergmann and contributors.

Runtime:       PHP 8.4.1

F                                                                   1 / 1 (100%)

Time: 00:00, Memory: 25.14 MB

There was 1 failure:

1) ArrayIsIdenticalToArrayIgnoringListOfKeysTest::testFailure
Failed asserting that two arrays are identical.
--- Expected
+++ Actual
@@ @@
 Array &0 [
-    'foo' => 'bar',
+    'foo' => 'baz',
 ]

/path/to/tests/ArrayIsIdenticalToArrayIgnoringListOfKeysTest.php:8

FAILURES!
Tests: 1, Assertions: 1, Failures: 1.

Equality

assertEquals()

assertEquals(mixed $expected, mixed $actual[, string $message])

Reports an error identified by $message if the two variables $expected and $actual are not equal.

assertNotEquals() is the inverse of this assertion and takes the same arguments.

Example 1.7 Usage of assertEquals()
<?php declare(strict_types=1);
use PHPUnit\Framework\TestCase;

final class EqualsTest extends TestCase
{
    public function testFailure(): void
    {
        $this->assertEquals(1, 0);
    }

    public function testFailure2(): void
    {
        $this->assertEquals('bar', 'baz');
    }

    public function testFailure3(): void
    {
        $this->assertEquals("foo\nbar\nbaz\n", "foo\nbah\nbaz\n");
    }
}

Running the test shown above yields the output shown below:

./tools/phpunit tests/EqualsTest.php
PHPUnit 11.4.3 by Sebastian Bergmann and contributors.

Runtime:       PHP 8.4.1

FFF                                                                 3 / 3 (100%)

Time: 00:00.001, Memory: 25.14 MB

There were 3 failures:

1) EqualsTest::testFailure
Failed asserting that 0 matches expected 1.

/path/to/tests/EqualsTest.php:8

2) EqualsTest::testFailure2
Failed asserting that two strings are equal.
--- Expected
+++ Actual
@@ @@
-'bar'
+'baz'

/path/to/tests/EqualsTest.php:13

3) EqualsTest::testFailure3
Failed asserting that two strings are equal.
--- Expected
+++ Actual
@@ @@
 'foo\n
-bar\n
+bah\n
 baz\n
 '

/path/to/tests/EqualsTest.php:18

FAILURES!
Tests: 3, Assertions: 3, Failures: 3.

Equality is checked using the == operator, but more specialized comparisons are used for specific argument types for $expected and $actual, see below.

assertEquals(DateTimeInterface $expected, DateTimeInterface $actual[, string $message])

Reports an error identified by $message if the two points in time represented by the two DateTimeInterface objects $expected and $actual are not equal.

Example 1.8 Usage of assertEquals() with DateTimeImmutable objects
<?php declare(strict_types=1);
use PHPUnit\Framework\TestCase;

final class EqualsWithDateTimeImmutableTest extends TestCase
{
    public function testFailure(): void
    {
        $expected = new DateTimeImmutable('2023-02-23 01:23:45');
        $actual   = new DateTimeImmutable('2023-02-23 01:23:46');

        $this->assertEquals($expected, $actual);
    }
}

Running the test shown above yields the output shown below:

./tools/phpunit tests/EqualsWithDateTimeImmutableTest.php
PHPUnit 11.4.3 by Sebastian Bergmann and contributors.

Runtime:       PHP 8.4.1

F                                                                   1 / 1 (100%)

Time: 00:00, Memory: 25.14 MB

There was 1 failure:

1) EqualsWithDateTimeImmutableTest::testFailure
Failed asserting that two DateTime objects are equal.
--- Expected
+++ Actual
@@ @@
-2023-02-23T01:23:45.000000+0100
+2023-02-23T01:23:46.000000+0100

/path/to/tests/EqualsWithDateTimeImmutableTest.php:11

FAILURES!
Tests: 1, Assertions: 1, Failures: 1.

assertEquals(DOMDocument $expected, DOMDocument $actual[, string $message])

Reports an error identified by $message if the uncommented canonical form of the XML documents represented by the two DOMDocument objects $expected and $actual are not equal.

Example 1.9 Usage of assertEquals() with DOMDocument objects
<?php declare(strict_types=1);
use PHPUnit\Framework\TestCase;

final class EqualsWithDomDocumentTest extends TestCase
{
    public function testFailure(): void
    {
        $expected = new DOMDocument;
        $expected->loadXML('<foo><bar/></foo>');

        $actual = new DOMDocument;
        $actual->loadXML('<bar><foo/></bar>');

        $this->assertEquals($expected, $actual);
    }
}

Running the test shown above yields the output shown below:

./tools/phpunit tests/EqualsWithDomDocumentTest.php
PHPUnit 11.4.3 by Sebastian Bergmann and contributors.

Runtime:       PHP 8.4.1

F                                                                   1 / 1 (100%)

Time: 00:00, Memory: 25.14 MB

There was 1 failure:

1) EqualsWithDomDocumentTest::testFailure
Failed asserting that two DOM documents are equal.
--- Expected
+++ Actual
@@ @@
 <?xml version="1.0"?>
-<foo>
-  <bar/>
-</foo>
+<bar>
+  <foo/>
+</bar>

/path/to/tests/EqualsWithDomDocumentTest.php:14

FAILURES!
Tests: 1, Assertions: 1, Failures: 1.

assertEquals(object $expected, object $actual[, string $message])

Reports an error identified by $message if the two objects $expected and $actual do not have equal property values.

Example 1.10 Usage of assertEquals() with objects
<?php declare(strict_types=1);
use PHPUnit\Framework\TestCase;

final class EqualsWithObjectsTest extends TestCase
{
    public function testFailure(): void
    {
        $expected      = new stdClass;
        $expected->foo = 'foo';
        $expected->bar = 'bar';

        $actual      = new stdClass;
        $actual->foo = 'bar';
        $actual->baz = 'bar';

        $this->assertEquals($expected, $actual);
    }
}

Running the test shown above yields the output shown below:

./tools/phpunit tests/EqualsWithObjectsTest.php
PHPUnit 11.4.3 by Sebastian Bergmann and contributors.

Runtime:       PHP 8.4.1

F                                                                   1 / 1 (100%)

Time: 00:00, Memory: 25.14 MB

There was 1 failure:

1) EqualsWithObjectsTest::testFailure
Failed asserting that two objects are equal.
--- Expected
+++ Actual
@@ @@
 stdClass Object (
-    'foo' => 'foo'
-    'bar' => 'bar'
+    'foo' => 'bar'
+    'baz' => 'bar'
 )

/path/to/tests/EqualsWithObjectsTest.php:16

FAILURES!
Tests: 1, Assertions: 1, Failures: 1.

assertEquals(array $expected, array $actual[, string $message])

Reports an error identified by $message if the two arrays $expected and $actual are not equal.

Example 1.11 Usage of assertEquals() with arrays
<?php declare(strict_types=1);
use PHPUnit\Framework\TestCase;

final class EqualsWithArraysTest extends TestCase
{
    public function testFailure(): void
    {
        $this->assertEquals(['a', 'b', 'c'], ['a', 'c', 'd']);
    }
}

Running the test shown above yields the output shown below:

./tools/phpunit tests/EqualsWithArraysTest.php
PHPUnit 11.4.3 by Sebastian Bergmann and contributors.

Runtime:       PHP 8.4.1

F                                                                   1 / 1 (100%)

Time: 00:00, Memory: 25.14 MB

There was 1 failure:

1) EqualsWithArraysTest::testFailure
Failed asserting that two arrays are equal.
--- Expected
+++ Actual
@@ @@
 Array (
     0 => 'a'
-    1 => 'b'
-    2 => 'c'
+    1 => 'c'
+    2 => 'd'
 )

/path/to/tests/EqualsWithArraysTest.php:8

FAILURES!
Tests: 1, Assertions: 1, Failures: 1.

assertEqualsCanonicalizing()

assertEqualsCanonicalizing(mixed $expected, mixed $actual[, string $message])

Reports an error identified by $message if the two variables $expected and $actual are not equal.

The contents of $expected and $actual are canonicalized before they are compared. For instance, when the two variables $expected and $actual are arrays, then these arrays are sorted before they are compared. When $expected and $actual are objects, each object is converted to an array containing all private, protected and public properties.

assertNotEqualsCanonicalizing() is the inverse of this assertion and takes the same arguments.

Example 1.12 Usage of assertEqualsCanonicalizing()
<?php declare(strict_types=1);
use PHPUnit\Framework\TestCase;

final class EqualsWithArraysCanonicalizingTest extends TestCase
{
    public function testFailure(): void
    {
        $this->assertEqualsCanonicalizing([3, 2, 1], [2, 3, 0, 1]);
    }
}

Running the test shown above yields the output shown below:

./tools/phpunit tests/EqualsWithArraysCanonicalizingTest.php
PHPUnit 11.4.3 by Sebastian Bergmann and contributors.

Runtime:       PHP 8.4.1

F                                                                   1 / 1 (100%)

Time: 00:00, Memory: 25.14 MB

There was 1 failure:

1) EqualsWithArraysCanonicalizingTest::testFailure
Failed asserting that two arrays are equal.
--- Expected
+++ Actual
@@ @@
 Array (
-    0 => 1
-    1 => 2
-    2 => 3
+    0 => 0
+    1 => 1
+    2 => 2
+    3 => 3
 )

/path/to/tests/EqualsWithArraysCanonicalizingTest.php:8

FAILURES!
Tests: 1, Assertions: 1, Failures: 1.

assertEqualsIgnoringCase()

assertEqualsIgnoringCase(mixed $expected, mixed $actual[, string $message])

Reports an error identified by $message if the two variables $expected and $actual are not equal.

Differences in casing are ignored for the comparison of $expected and $actual.

assertNotEqualsIgnoringCase() is the inverse of this assertion and takes the same arguments.

Example 1.13 Usage of assertEqualsIgnoringCase()
<?php declare(strict_types=1);
use PHPUnit\Framework\TestCase;

final class EqualsWithStringsIgnoringCaseTest extends TestCase
{
    public function testFailure(): void
    {
        $this->assertEqualsIgnoringCase('foo', 'BAR');
    }
}

Running the test shown above yields the output shown below:

./tools/phpunit tests/EqualsWithStringsIgnoringCaseTest.php
PHPUnit 11.4.3 by Sebastian Bergmann and contributors.

Runtime:       PHP 8.4.1

F                                                                   1 / 1 (100%)

Time: 00:00, Memory: 25.14 MB

There was 1 failure:

1) EqualsWithStringsIgnoringCaseTest::testFailure
Failed asserting that two strings are equal.
--- Expected
+++ Actual
@@ @@
-'foo'
+'BAR'

/path/to/tests/EqualsWithStringsIgnoringCaseTest.php:8

FAILURES!
Tests: 1, Assertions: 1, Failures: 1.

assertEqualsWithDelta()

assertEqualsWithDelta(mixed $expected, mixed $actual, float $delta[, string $message])

Reports an error identified by $message if the absolute difference between $expected and $actual is greater than $delta.

Please read “What Every Computer Scientist Should Know About Floating-Point Arithmetic” to understand why $delta is necessary.

assertNotEqualsWithDelta() is the inverse of this assertion and takes the same arguments.

Example 1.14 Usage of assertEqualsWithDelta()
<?php declare(strict_types=1);
use PHPUnit\Framework\TestCase;

final class EqualsWithFloatsAndDeltaTest extends TestCase
{
    public function testFailure(): void
    {
        $this->assertEqualsWithDelta(1.0, 1.5, 0.1);
    }
}

Running the test shown above yields the output shown below:

./tools/phpunit tests/EqualsWithFloatsAndDeltaTest.php
PHPUnit 11.4.3 by Sebastian Bergmann and contributors.

Runtime:       PHP 8.4.1

F                                                                   1 / 1 (100%)

Time: 00:00, Memory: 25.14 MB

There was 1 failure:

1) EqualsWithFloatsAndDeltaTest::testFailure
Failed asserting that 1.5 matches expected 1.0.

/path/to/tests/EqualsWithFloatsAndDeltaTest.php:8

FAILURES!
Tests: 1, Assertions: 1, Failures: 1.

assertObjectEquals()

assertObjectEquals(object $expected, object $actual, string $method = 'equals'[, string $message])

Reports an error identified by $message if $actual is not equal to $expected according to $actual->$method($expected).

It is a bad practice to use assertEquals() (and its inverse, assertNotEquals()) on objects without registering a custom comparator that customizes how objects are compared. Unfortunately, though, implementing custom comparators for each and every object you want to assert in your tests is inconvenient at best.

The most common use case for custom comparators are Value Objects. These objects usually have an equals(self $other): bool method (or a method just like that but with a different name) for comparing two instances of the Value Object’s type. assertObjectEquals() makes custom comparison of objects convenient for this common use case:

assertObjectNotEquals() is the inverse of this assertion and takes the same arguments.

Example 1.15 Usage of assertObjectEquals()
<?php declare(strict_types=1);
use PHPUnit\Framework\TestCase;

final class ObjectEqualsTest extends TestCase
{
    public function testSomething(): void
    {
        $a = new Email('user@example.org');
        $b = new Email('user@example.org');
        $c = new Email('user@example.com');

        // This passes
        $this->assertObjectEquals($a, $b);

        // This fails
        $this->assertObjectEquals($a, $c);
    }
}

Running the test shown above yields the output shown below:

./tools/phpunit tests/ObjectEqualsTest.php
PHPUnit 11.4.3 by Sebastian Bergmann and contributors.

Runtime:       PHP 8.4.1

F                                                                   1 / 1 (100%)

Time: 00:00, Memory: 25.14 MB

There was 1 failure:

1) ObjectEqualsTest::testSomething
Failed asserting that two objects are equal.

/path/to/tests/ObjectEqualsTest.php:16

FAILURES!
Tests: 1, Assertions: 2, Failures: 1.
Example 1.16 Email value object with equals() method
<?php declare(strict_types=1);
final class Email
{
    private string $email;

    public function __construct(string $email)
    {
        $this->ensureIsValidEmail($email);

        $this->email = $email;
    }

    public function asString(): string
    {
        return $this->email;
    }

    public function equals(self $other): bool
    {
        return $this->asString() === $other->asString();
    }

    private function ensureIsValidEmail(string $email): void
    {
        // ...
    }
}

Please note:

  • A method with name $method must exist on the $actual object

  • The method must accept exactly one argument

  • The respective parameter must have a declared type

  • The $expected object must be compatible with this declared type

  • The method must have a declared bool return type

If any of the aforementioned assumptions is not fulfilled or if $actual->$method($expected) returns false then the assertion fails.

assertFileEquals()

assertFileEquals(string $expected, string $actual[, string $message])

Reports an error identified by $message if the file specified by $expected does not have the same contents as the file specified by $actual.

assertFileNotEquals() is the inverse of this assertion and takes the same arguments.

assertFileEqualsCanonicalizing() (and assertFileNotEqualsCanonicalizing()) as well as assertFileEqualsIgnoringCase() (and assertFileNotEqualsIgnoringCase()) do for files what assertEqualsCanonicalizing() (and assertNotEqualsCanonicalizing()) as well as assertEqualsIgnoringCase() (and assertNotEqualsIgnoringCase()) do for strings.

Example 1.17 Usage of assertFileEquals()
<?php declare(strict_types=1);
use PHPUnit\Framework\TestCase;

final class FileEqualsTest extends TestCase
{
    public function testFailure(): void
    {
        $this->assertFileEquals(
            __DIR__ . '/expected.txt',
            __DIR__ . '/actual.txt',
        );
    }
}

Running the test shown above yields the output shown below:

./tools/phpunit tests/FileEqualsTest.php
PHPUnit 11.4.3 by Sebastian Bergmann and contributors.

Runtime:       PHP 8.4.1

F                                                                   1 / 1 (100%)

Time: 00:00, Memory: 25.14 MB

There was 1 failure:

1) FileEqualsTest::testFailure
Failed asserting that two strings are equal.
--- Expected
+++ Actual
@@ @@
-'expected\n
+'actual\n
 '

/path/to/tests/FileEqualsTest.php:8

FAILURES!
Tests: 1, Assertions: 3, Failures: 1.

assertArrayIsEqualToArrayOnlyConsideringListOfKeys()

assertArrayIsEqualToArrayOnlyConsideringListOfKeys(array $expected, array $actual, array $keysToBeConsidered[, string $message])

Reports an error identified by $message if two arrays are not equal while only considering array elements for which the keys have been specified.

Example 1.18 Usage of assertArrayIsEqualToArrayOnlyConsideringListOfKeys()
<?php declare(strict_types=1);
use PHPUnit\Framework\TestCase;

final class ArrayIsEqualToArrayOnlyConsideringListOfKeysTest extends TestCase
{
    public function testFailure(): void
    {
        $this->assertArrayIsEqualToArrayOnlyConsideringListOfKeys(
            [
                'timestamp' => time(),
                'foo'       => 'bar',
            ],
            [
                'timestamp' => time(),
                'foo'       => 'baz',
            ],
            [
                'foo',
            ]
        );
    }
}

Running the test shown above yields the output shown below:

./tools/phpunit tests/ArrayIsEqualToArrayOnlyConsideringListOfKeysTest.php
PHPUnit 11.4.3 by Sebastian Bergmann and contributors.

Runtime:       PHP 8.4.1

F                                                                   1 / 1 (100%)

Time: 00:00, Memory: 25.14 MB

There was 1 failure:

1) ArrayIsEqualToArrayOnlyConsideringListOfKeysTest::testFailure
Failed asserting that two arrays are equal.
--- Expected
+++ Actual
@@ @@
 Array (
-    'foo' => 'bar'
+    'foo' => 'baz'
 )

/path/to/tests/ArrayIsEqualToArrayOnlyConsideringListOfKeysTest.php:8

FAILURES!
Tests: 1, Assertions: 1, Failures: 1.

assertArrayIsEqualToArrayIgnoringListOfKeys()

assertArrayIsEqualToArrayIgnoringListOfKeys(array $expected, array $actual, array $keysToBeIgnored[, string $message])

Reports an error identified by $message if two arrays are not equal while only ignoring array elements for which the keys have been specified.

Example 1.19 Usage of assertArrayIsEqualToArrayIgnoringListOfKeys()
<?php declare(strict_types=1);
use PHPUnit\Framework\TestCase;

final class ArrayIsEqualToArrayIgnoringListOfKeysTest extends TestCase
{
    public function testFailure(): void
    {
        $this->assertArrayIsEqualToArrayIgnoringListOfKeys(
            [
                'timestamp' => time(),
                'foo'       => 'bar',
            ],
            [
                'timestamp' => time(),
                'foo'       => 'baz',
            ],
            [
                'timestamp',
            ]
        );
    }
}

Running the test shown above yields the output shown below:

./tools/phpunit tests/ArrayIsEqualToArrayIgnoringListOfKeysTest.php
PHPUnit 11.4.3 by Sebastian Bergmann and contributors.

Runtime:       PHP 8.4.1

F                                                                   1 / 1 (100%)

Time: 00:00, Memory: 25.14 MB

There was 1 failure:

1) ArrayIsEqualToArrayIgnoringListOfKeysTest::testFailure
Failed asserting that two arrays are equal.
--- Expected
+++ Actual
@@ @@
 Array (
-    'foo' => 'bar'
+    'foo' => 'baz'
 )

/path/to/tests/ArrayIsEqualToArrayIgnoringListOfKeysTest.php:8

FAILURES!
Tests: 1, Assertions: 1, Failures: 1.

Iterable

assertArrayHasKey()

assertArrayHasKey(int|string $key, array|ArrayAccess $array[, string $message])

Reports an error identified by $message if $array does not have the $key.

assertArrayNotHasKey() is the inverse of this assertion and takes the same arguments.

Example 1.20 Usage of assertArrayHasKey()
<?php declare(strict_types=1);
use PHPUnit\Framework\TestCase;

final class ArrayHasKeyTest extends TestCase
{
    public function testFailure(): void
    {
        $this->assertArrayHasKey('foo', ['bar' => 'baz']);
    }
}

Running the test shown above yields the output shown below:

./tools/phpunit tests/ArrayHasKeyTest.php
PHPUnit 11.4.3 by Sebastian Bergmann and contributors.

Runtime:       PHP 8.4.1

F                                                                   1 / 1 (100%)

Time: 00:00, Memory: 25.14 MB

There was 1 failure:

1) ArrayHasKeyTest::testFailure
Failed asserting that an array has the key 'foo'.

/path/to/tests/ArrayHasKeyTest.php:8

FAILURES!
Tests: 1, Assertions: 1, Failures: 1.

assertContains()

assertContains(mixed $needle, iterable $haystack[, string $message])

Reports an error identified by $message if $needle is not an element of $haystack.

assertNotContains() is the inverse of this assertion and takes the same arguments.

Example 1.21 Usage of assertContains()
<?php declare(strict_types=1);
use PHPUnit\Framework\TestCase;

final class ContainsTest extends TestCase
{
    public function testFailure(): void
    {
        $this->assertContains(4, [1, 2, 3]);
    }
}

Running the test shown above yields the output shown below:

./tools/phpunit tests/ContainsTest.php
PHPUnit 11.4.3 by Sebastian Bergmann and contributors.

Runtime:       PHP 8.4.1

F                                                                   1 / 1 (100%)

Time: 00:00, Memory: 25.14 MB

There was 1 failure:

1) ContainsTest::testFailure
Failed asserting that an array contains 4.

/path/to/tests/ContainsTest.php:8

FAILURES!
Tests: 1, Assertions: 1, Failures: 1.

Whether $needle is an element of $haystack is checked using the === operator. You can use assertContainsEquals() (and assertNotContainsEquals()) if you need the comparison logic implemented by the == operator.

assertContainsOnly()

assertContainsOnly(string $type, iterable $haystack[, boolean $isNativeType = null, string $message = ''])

Reports an error identified by $message if $haystack does not contain only variables of type $type.

$isNativeType is a flag used to indicate whether $type is a native PHP type or not.

These are the strings supported for $type when $isNativeType is true: array, bool, boolean, callable, double, float, int, integer, iterable, null, numeric, object, real, resource, scalar, or string.

assertNotContainsOnly() is the inverse of this assertion and takes the same arguments.

Example 1.22 Usage of assertContainsOnly()
<?php declare(strict_types=1);
use PHPUnit\Framework\TestCase;

final class ContainsOnlyTest extends TestCase
{
    public function testFailure(): void
    {
        $this->assertContainsOnly('string', ['1', '2', 3]);
    }
}

Running the test shown above yields the output shown below:

./tools/phpunit tests/ContainsOnlyTest.php
PHPUnit 11.4.3 by Sebastian Bergmann and contributors.

Runtime:       PHP 8.4.1

F                                                                   1 / 1 (100%)

Time: 00:00, Memory: 25.14 MB

There was 1 failure:

1) ContainsOnlyTest::testFailure
Failed asserting that Array &0 [
    0 => '1',
    1 => '2',
    2 => 3,
] contains only values of type "string".

/path/to/tests/ContainsOnlyTest.php:8

FAILURES!
Tests: 1, Assertions: 1, Failures: 1.

assertContainsOnlyInstancesOf()

assertContainsOnlyInstancesOf(string $type, iterable $haystack[, string $message])

Reports an error identified by $message if $haystack does not contain only instances of class or interface $type.

Example 1.23 Usage of assertContainsOnlyInstancesOf()
<?php declare(strict_types=1);
use PHPUnit\Framework\TestCase;

final class ContainsOnlyInstancesOfTest extends TestCase
{
    public function testFailure(): void
    {
        $this->assertContainsOnlyInstancesOf(
            Foo::class,
            [new Foo, new Bar, new Foo],
        );
    }
}

Running the test shown above yields the output shown below:

./tools/phpunit tests/ContainsOnlyInstancesOfTest.php
PHPUnit 11.4.3 by Sebastian Bergmann and contributors.

Runtime:       PHP 8.4.1

F                                                                   1 / 1 (100%)

Time: 00:00, Memory: 25.14 MB

There was 1 failure:

1) ContainsOnlyInstancesOfTest::testFailure
Failed asserting that Array &0 [
    0 => Foo Object #302 (),
    1 => Bar Object #320 (),
    2 => Foo Object #306 (),
] contains only values of type "Foo".

/path/to/tests/ContainsOnlyInstancesOfTest.php:8

FAILURES!
Tests: 1, Assertions: 1, Failures: 1.

Objects

assertObjectHasProperty()

assertObjectHasProperty(string $propertyName, object $object, string $message = '')

Reports an error identified by $message if $object does not have a property with the name $propertyName.

assertObjectNotHasProperty() is the inverse of this assertion and takes the same arguments.

Example 1.24 Usage of assertObjectHasProperty()
<?php declare(strict_types=1);
use PHPUnit\Framework\TestCase;

final class ObjectHasPropertyTest extends TestCase
{
    public function testFailure(): void
    {
        $this->assertObjectHasProperty('propertyName', new stdClass);
    }
}

Running the test shown above yields the output shown below:

./tools/phpunit tests/ObjectHasPropertyTest.php
PHPUnit 11.4.3 by Sebastian Bergmann and contributors.

Runtime:       PHP 8.4.1

F                                                                   1 / 1 (100%)

Time: 00:00, Memory: 25.14 MB

There was 1 failure:

1) ObjectHasPropertyTest::testFailure
Failed asserting that object of class "stdClass" has property "propertyName".

/path/to/tests/ObjectHasPropertyTest.php:8

FAILURES!
Tests: 1, Assertions: 1, Failures: 1.

Cardinality

assertCount()

assertCount(int $expectedCount, Countable|iterable $haystack[, string $message])

Reports an error identified by $message if the number of elements in $haystack is not $expectedCount.

assertNotCount() is the inverse of this assertion and takes the same arguments.

Example 1.25 Usage of assertCount()
<?php declare(strict_types=1);
use PHPUnit\Framework\TestCase;

final class CountTest extends TestCase
{
    public function testFailure(): void
    {
        $this->assertCount(0, ['foo']);
    }
}

Running the test shown above yields the output shown below:

./tools/phpunit tests/CountTest.php
PHPUnit 11.4.3 by Sebastian Bergmann and contributors.

Runtime:       PHP 8.4.1

F                                                                   1 / 1 (100%)

Time: 00:00, Memory: 25.14 MB

There was 1 failure:

1) CountTest::testFailure
Failed asserting that actual size 1 matches expected size 0.

/path/to/tests/CountTest.php:8

FAILURES!
Tests: 1, Assertions: 1, Failures: 1.

Note

Please note that assertCount() and assertNotCount() do not support generators. Generators can only be iterated over once and they cannot be cloned. Passing a generator to assertCount() or assertNotCount() would therefore change the state of something that is supposed to be only verified.

assertSameSize()

assertSameSize(Countable|iterable $expected, Countable|iterable $actual[, string $message])

Reports an error identified by $message if the sizes of $actual and $expected are not the same.

assertNotSameSize() is the inverse of this assertion and takes the same arguments.

Example 1.26 Usage of assertSameSize()
<?php declare(strict_types=1);
use PHPUnit\Framework\TestCase;

final class SameSizeTest extends TestCase
{
    public function testFailure(): void
    {
        $this->assertSameSize([1, 2], [1]);
    }
}

Running the test shown above yields the output shown below:

./tools/phpunit tests/SameSizeTest.php
PHPUnit 11.4.3 by Sebastian Bergmann and contributors.

Runtime:       PHP 8.4.1

F                                                                   1 / 1 (100%)

Time: 00:00, Memory: 25.14 MB

There was 1 failure:

1) SameSizeTest::testFailure
Failed asserting that actual size 1 matches expected size 2.

/path/to/tests/SameSizeTest.php:8

FAILURES!
Tests: 1, Assertions: 1, Failures: 1.

Note

Please note that assertSameSize() and assertNotSameSize() do not support generators. Generators can only be iterated over once and they cannot be cloned. Passing a generator to assertSameSize() or assertNotSameSize() would therefore change the state of something that is supposed to be only verified.

assertEmpty()

assertEmpty(mixed $actual[, string $message])

Reports an error identified by $message if $actual is not empty.

assertNotEmpty() is the inverse of this assertion and takes the same arguments.

Example 1.27 Usage of assertEmpty()
<?php declare(strict_types=1);
use PHPUnit\Framework\TestCase;

final class EmptyTest extends TestCase
{
    public function testFailure(): void
    {
        $this->assertEmpty(['foo']);
    }
}

Running the test shown above yields the output shown below:

./tools/phpunit tests/EmptyTest.php
PHPUnit 11.4.3 by Sebastian Bergmann and contributors.

Runtime:       PHP 8.4.1

F                                                                   1 / 1 (100%)

Time: 00:00, Memory: 25.14 MB

There was 1 failure:

1) EmptyTest::testFailure
Failed asserting that an array is empty.

/path/to/tests/EmptyTest.php:8

FAILURES!
Tests: 1, Assertions: 1, Failures: 1.

Note

Please note that assertEmpty() and assertNotEmpty() do not support generators. Generators can only be iterated over once and they cannot be cloned. Passing a generator to assertEmpty() or assertNotEmpty() would therefore change the state of something that is supposed to be only verified.

assertGreaterThan()

assertGreaterThan(mixed $expected, mixed $actual[, string $message])

Reports an error identified by $message if the value of $actual is not greater than the value of $expected.

Example 1.28 Usage of assertGreaterThan()
<?php declare(strict_types=1);
use PHPUnit\Framework\TestCase;

final class GreaterThanTest extends TestCase
{
    public function testFailure(): void
    {
        $this->assertGreaterThan(2, 1);
    }
}

Running the test shown above yields the output shown below:

./tools/phpunit tests/GreaterThanTest.php
PHPUnit 11.4.3 by Sebastian Bergmann and contributors.

Runtime:       PHP 8.4.1

F                                                                   1 / 1 (100%)

Time: 00:00, Memory: 25.14 MB

There was 1 failure:

1) GreaterThanTest::testFailure
Failed asserting that 1 is greater than 2.

/path/to/tests/GreaterThanTest.php:8

FAILURES!
Tests: 1, Assertions: 1, Failures: 1.

assertGreaterThanOrEqual()

assertGreaterThanOrEqual(mixed $expected, mixed $actual[, string $message])

Reports an error identified by $message if the value of $actual is not greater than or equal to the value of $expected.

Example 1.29 Usage of assertGreaterThanOrEqual()
<?php declare(strict_types=1);
use PHPUnit\Framework\TestCase;

final class GreaterThanOrEqualTest extends TestCase
{
    public function testFailure(): void
    {
        $this->assertGreaterThanOrEqual(2, 1);
    }
}

Running the test shown above yields the output shown below:

./tools/phpunit tests/GreaterThanOrEqualTest.php
PHPUnit 11.4.3 by Sebastian Bergmann and contributors.

Runtime:       PHP 8.4.1

F                                                                   1 / 1 (100%)

Time: 00:00, Memory: 25.14 MB

There was 1 failure:

1) GreaterThanOrEqualTest::testFailure
Failed asserting that 1 is equal to 2 or is greater than 2.

/path/to/tests/GreaterThanOrEqualTest.php:8

FAILURES!
Tests: 1, Assertions: 2, Failures: 1.

assertLessThan()

assertLessThan(mixed $expected, mixed $actual[, string $message])

Reports an error identified by $message if the value of $actual is not less than the value of $expected.

Example 1.30 Usage of assertLessThan()
<?php declare(strict_types=1);
use PHPUnit\Framework\TestCase;

final class LessThanTest extends TestCase
{
    public function testFailure(): void
    {
        $this->assertLessThan(1, 2);
    }
}

Running the test shown above yields the output shown below:

./tools/phpunit tests/LessThanTest.php
PHPUnit 11.4.3 by Sebastian Bergmann and contributors.

Runtime:       PHP 8.4.1

F                                                                   1 / 1 (100%)

Time: 00:00, Memory: 25.14 MB

There was 1 failure:

1) LessThanTest::testFailure
Failed asserting that 2 is less than 1.

/path/to/tests/LessThanTest.php:8

FAILURES!
Tests: 1, Assertions: 1, Failures: 1.

assertLessThanOrEqual()

assertLessThanOrEqual(mixed $expected, mixed $actual[, string $message])

Reports an error identified by $message if the value of $actual is not less than or equal to the value of $expected.

Example 1.31 Usage of assertLessThanOrEqual()
<?php declare(strict_types=1);
use PHPUnit\Framework\TestCase;

final class LessThanOrEqualTest extends TestCase
{
    public function testFailure(): void
    {
        $this->assertLessThanOrEqual(1, 2);
    }
}

Running the test shown above yields the output shown below:

./tools/phpunit tests/LessThanOrEqualTest.php
PHPUnit 11.4.3 by Sebastian Bergmann and contributors.

Runtime:       PHP 8.4.1

F                                                                   1 / 1 (100%)

Time: 00:00, Memory: 25.14 MB

There was 1 failure:

1) LessThanOrEqualTest::testFailure
Failed asserting that 2 is equal to 1 or is less than 1.

/path/to/tests/LessThanOrEqualTest.php:8

FAILURES!
Tests: 1, Assertions: 2, Failures: 1.

Types

assertInstanceOf()

assertInstanceOf(string $expected, mixed $actual[, string $message])

Reports an error identified by $message if $actual is not an instance of $expected.

assertNotInstanceOf() is the inverse of this assertion and takes the same arguments.

Example 1.32 Usage of assertInstanceOf()
<?php declare(strict_types=1);
use PHPUnit\Framework\TestCase;

final class InstanceOfTest extends TestCase
{
    public function testFailure(): void
    {
        $this->assertInstanceOf(RuntimeException::class, new Exception);
    }
}

Running the test shown above yields the output shown below:

./tools/phpunit tests/InstanceOfTest.php
PHPUnit 11.4.3 by Sebastian Bergmann and contributors.

Runtime:       PHP 8.4.1

F                                                                   1 / 1 (100%)

Time: 00:00, Memory: 25.14 MB

There was 1 failure:

1) InstanceOfTest::testFailure
Failed asserting that an instance of class Exception is an instance of class RuntimeException.

/path/to/tests/InstanceOfTest.php:8

FAILURES!
Tests: 1, Assertions: 1, Failures: 1.

assertIsArray()

assertIsArray(mixed $actual[, string $message])

Reports an error identified by $message if $actual is not of type array.

assertIsNotArray() is the inverse of this assertion and takes the same arguments.

Example 1.33 Usage of assertIsArray()
<?php declare(strict_types=1);
use PHPUnit\Framework\TestCase;

final class IsArrayTest extends TestCase
{
    public function testFailure(): void
    {
        $this->assertIsArray(null);
    }
}

Running the test shown above yields the output shown below:

./tools/phpunit tests/IsArrayTest.php
PHPUnit 11.4.3 by Sebastian Bergmann and contributors.

Runtime:       PHP 8.4.1

F                                                                   1 / 1 (100%)

Time: 00:00, Memory: 25.14 MB

There was 1 failure:

1) IsArrayTest::testFailure
Failed asserting that null is of type array.

/path/to/tests/IsArrayTest.php:8

FAILURES!
Tests: 1, Assertions: 1, Failures: 1.

assertIsList()

assertIsList(mixed $actual[, string $message])

Reports an error identified by $message if $actual is not an array where the keys are consecutive numbers from 0 to count($actual) - 1.

Example 1.34 Usage of assertIsList()
<?php declare(strict_types=1);
use PHPUnit\Framework\TestCase;

final class IsListTest extends TestCase
{
    public function testFailure(): void
    {
        $this->assertIsList([1 => 'foo', '3' => 'bar']);
    }
}

Running the test shown above yields the output shown below:

./tools/phpunit tests/IsListTest.php
PHPUnit 11.4.3 by Sebastian Bergmann and contributors.

Runtime:       PHP 8.4.1

F                                                                   1 / 1 (100%)

Time: 00:00, Memory: 25.14 MB

There was 1 failure:

1) IsListTest::testFailure
Failed asserting that an array is a list.

/path/to/tests/IsListTest.php:8

FAILURES!
Tests: 1, Assertions: 1, Failures: 1.

assertIsBool()

assertIsBool(mixed $actual[, string $message])

Reports an error identified by $message if $actual is not of type bool.

assertIsNotBool() is the inverse of this assertion and takes the same arguments.

Example 1.35 Usage of assertIsBool()
<?php declare(strict_types=1);
use PHPUnit\Framework\TestCase;

final class IsBoolTest extends TestCase
{
    public function testFailure(): void
    {
        $this->assertIsBool(null);
    }
}

Running the test shown above yields the output shown below:

./tools/phpunit tests/IsBoolTest.php
PHPUnit 11.4.3 by Sebastian Bergmann and contributors.

Runtime:       PHP 8.4.1

F                                                                   1 / 1 (100%)

Time: 00:00, Memory: 25.14 MB

There was 1 failure:

1) IsBoolTest::testFailure
Failed asserting that null is of type bool.

/path/to/tests/IsBoolTest.php:8

FAILURES!
Tests: 1, Assertions: 1, Failures: 1.

assertIsCallable()

assertIsCallable(mixed $actual[, string $message])

Reports an error identified by $message if $actual is not of type callable.

assertIsNotCallable() is the inverse of this assertion and takes the same arguments.

Example 1.36 Usage of assertIsCallable()
<?php declare(strict_types=1);
use PHPUnit\Framework\TestCase;

final class IsCallableTest extends TestCase
{
    public function testFailure(): void
    {
        $this->assertIsCallable(null);
    }
}

Running the test shown above yields the output shown below:

./tools/phpunit tests/IsCallableTest.php
PHPUnit 11.4.3 by Sebastian Bergmann and contributors.

Runtime:       PHP 8.4.1

F                                                                   1 / 1 (100%)

Time: 00:00, Memory: 25.14 MB

There was 1 failure:

1) IsCallableTest::testFailure
Failed asserting that null is of type callable.

/path/to/tests/IsCallableTest.php:8

FAILURES!
Tests: 1, Assertions: 1, Failures: 1.

assertIsFloat()

assertIsFloat(mixed $actual[, string $message])

Reports an error identified by $message if $actual is not of type float.

assertIsNotFloat() is the inverse of this assertion and takes the same arguments.

Example 1.37 Usage of assertIsFloat()
<?php declare(strict_types=1);
use PHPUnit\Framework\TestCase;

final class IsFloatTest extends TestCase
{
    public function testFailure(): void
    {
        $this->assertIsFloat(null);
    }
}

Running the test shown above yields the output shown below:

./tools/phpunit tests/IsFloatTest.php
PHPUnit 11.4.3 by Sebastian Bergmann and contributors.

Runtime:       PHP 8.4.1

F                                                                   1 / 1 (100%)

Time: 00:00, Memory: 25.14 MB

There was 1 failure:

1) IsFloatTest::testFailure
Failed asserting that null is of type float.

/path/to/tests/IsFloatTest.php:8

FAILURES!
Tests: 1, Assertions: 1, Failures: 1.

assertIsInt()

assertIsInt(mixed $actual[, string $message])

Reports an error identified by $message if $actual is not of type int.

assertIsNotInt() is the inverse of this assertion and takes the same arguments.

Example 1.38 Usage of assertIsInt()
<?php declare(strict_types=1);
use PHPUnit\Framework\TestCase;

final class IsIntTest extends TestCase
{
    public function testFailure(): void
    {
        $this->assertIsInt(null);
    }
}

Running the test shown above yields the output shown below:

./tools/phpunit tests/IsIntTest.php
PHPUnit 11.4.3 by Sebastian Bergmann and contributors.

Runtime:       PHP 8.4.1

F                                                                   1 / 1 (100%)

Time: 00:00, Memory: 25.14 MB

There was 1 failure:

1) IsIntTest::testFailure
Failed asserting that null is of type int.

/path/to/tests/IsIntTest.php:8

FAILURES!
Tests: 1, Assertions: 1, Failures: 1.

assertIsIterable()

assertIsIterable(mixed $actual[, string $message])

Reports an error identified by $message if $actual is not of type iterable.

assertIsNotIterable() is the inverse of this assertion and takes the same arguments.

Example 1.39 Usage of assertIsIterable()
<?php declare(strict_types=1);
use PHPUnit\Framework\TestCase;

final class IsIterableTest extends TestCase
{
    public function testFailure(): void
    {
        $this->assertIsIterable(null);
    }
}

Running the test shown above yields the output shown below:

./tools/phpunit tests/IsIterableTest.php
PHPUnit 11.4.3 by Sebastian Bergmann and contributors.

Runtime:       PHP 8.4.1

F                                                                   1 / 1 (100%)

Time: 00:00, Memory: 25.14 MB

There was 1 failure:

1) IsIterableTest::testFailure
Failed asserting that null is of type iterable.

/path/to/tests/IsIterableTest.php:8

FAILURES!
Tests: 1, Assertions: 1, Failures: 1.

assertIsNumeric()

assertIsNumeric(mixed $actual[, string $message])

Reports an error identified by $message if $actual is not of type numeric.

assertIsNotNumeric() is the inverse of this assertion and takes the same arguments.

Example 1.40 Usage of assertIsNumeric()
<?php declare(strict_types=1);
use PHPUnit\Framework\TestCase;

final class IsNumericTest extends TestCase
{
    public function testFailure(): void
    {
        $this->assertIsNumeric(null);
    }
}

Running the test shown above yields the output shown below:

./tools/phpunit tests/IsNumericTest.php
PHPUnit 11.4.3 by Sebastian Bergmann and contributors.

Runtime:       PHP 8.4.1

F                                                                   1 / 1 (100%)

Time: 00:00, Memory: 25.14 MB

There was 1 failure:

1) IsNumericTest::testFailure
Failed asserting that null is of type numeric.

/path/to/tests/IsNumericTest.php:8

FAILURES!
Tests: 1, Assertions: 1, Failures: 1.

assertIsObject()

assertIsObject(mixed $actual[, string $message])

Reports an error identified by $message if $actual is not of type object.

assertIsNotObject() is the inverse of this assertion and takes the same arguments.

Example 1.41 Usage of assertIsObject()
<?php declare(strict_types=1);
use PHPUnit\Framework\TestCase;

final class IsObjectTest extends TestCase
{
    public function testFailure(): void
    {
        $this->assertIsObject(null);
    }
}

Running the test shown above yields the output shown below:

./tools/phpunit tests/IsObjectTest.php
PHPUnit 11.4.3 by Sebastian Bergmann and contributors.

Runtime:       PHP 8.4.1

F                                                                   1 / 1 (100%)

Time: 00:00, Memory: 25.14 MB

There was 1 failure:

1) IsObjectTest::testFailure
Failed asserting that null is of type object.

/path/to/tests/IsObjectTest.php:8

FAILURES!
Tests: 1, Assertions: 1, Failures: 1.

assertIsResource()

assertIsResource(mixed $actual[, string $message])

Reports an error identified by $message if $actual is not of type resource.

assertIsNotResource() is the inverse of this assertion and takes the same arguments.

assertIsClosedResource() (and assertIsNotClosedResource()) are provided to explicitly check for closed resources.

Example 1.42 Usage of assertIsResource()
<?php declare(strict_types=1);
use PHPUnit\Framework\TestCase;

final class IsResourceTest extends TestCase
{
    public function testFailure(): void
    {
        $this->assertIsResource(null);
    }
}

Running the test shown above yields the output shown below:

./tools/phpunit tests/IsResourceTest.php
PHPUnit 11.4.3 by Sebastian Bergmann and contributors.

Runtime:       PHP 8.4.1

F                                                                   1 / 1 (100%)

Time: 00:00, Memory: 25.14 MB

There was 1 failure:

1) IsResourceTest::testFailure
Failed asserting that null is of type resource.

/path/to/tests/IsResourceTest.php:8

FAILURES!
Tests: 1, Assertions: 1, Failures: 1.

assertIsScalar()

assertIsScalar(mixed $actual[, string $message])

Reports an error identified by $message if $actual is not of type scalar.

assertIsNotScalar() is the inverse of this assertion and takes the same arguments.

Example 1.43 Usage of assertIsScalar()
<?php declare(strict_types=1);
use PHPUnit\Framework\TestCase;

final class IsScalarTest extends TestCase
{
    public function testFailure(): void
    {
        $this->assertIsScalar(null);
    }
}

Running the test shown above yields the output shown below:

./tools/phpunit tests/IsScalarTest.php
PHPUnit 11.4.3 by Sebastian Bergmann and contributors.

Runtime:       PHP 8.4.1

F                                                                   1 / 1 (100%)

Time: 00:00, Memory: 25.14 MB

There was 1 failure:

1) IsScalarTest::testFailure
Failed asserting that null is of type scalar.

/path/to/tests/IsScalarTest.php:8

FAILURES!
Tests: 1, Assertions: 1, Failures: 1.

assertIsString()

assertIsString(mixed $actual[, string $message])

Reports an error identified by $message if $actual is not of type string.

assertIsNotString() is the inverse of this assertion and takes the same arguments.

Example 1.44 Usage of assertIsString()
<?php declare(strict_types=1);
use PHPUnit\Framework\TestCase;

final class IsStringTest extends TestCase
{
    public function testFailure(): void
    {
        $this->assertIsString(null);
    }
}

Running the test shown above yields the output shown below:

./tools/phpunit tests/IsStringTest.php
PHPUnit 11.4.3 by Sebastian Bergmann and contributors.

Runtime:       PHP 8.4.1

F                                                                   1 / 1 (100%)

Time: 00:00, Memory: 25.14 MB

There was 1 failure:

1) IsStringTest::testFailure
Failed asserting that null is of type string.

/path/to/tests/IsStringTest.php:8

FAILURES!
Tests: 1, Assertions: 1, Failures: 1.

assertNull()

assertNull(mixed $actual[, string $message])

Reports an error identified by $message if $actual is not null.

assertNotNull() is the inverse of this assertion and takes the same arguments.

Example 1.45 Usage of assertNull()
<?php declare(strict_types=1);
use PHPUnit\Framework\TestCase;

final class NullTest extends TestCase
{
    public function testFailure(): void
    {
        $this->assertNull('foo');
    }
}

Running the test shown above yields the output shown below:

./tools/phpunit tests/NullTest.php
PHPUnit 11.4.3 by Sebastian Bergmann and contributors.

Runtime:       PHP 8.4.1

F                                                                   1 / 1 (100%)

Time: 00:00, Memory: 25.14 MB

There was 1 failure:

1) NullTest::testFailure
Failed asserting that 'foo' is null.

/path/to/tests/NullTest.php:8

FAILURES!
Tests: 1, Assertions: 1, Failures: 1.

Strings

assertStringStartsWith()

assertStringStartsWith(string $prefix, string $string[, string $message])

Reports an error identified by $message if the $string does not start with $prefix.

assertStringStartsNotWith() is the inverse of this assertion and takes the same arguments.

Example 1.46 Usage of assertStringStartsWith()
<?php declare(strict_types=1);
use PHPUnit\Framework\TestCase;

final class StringStartsWithTest extends TestCase
{
    public function testFailure(): void
    {
        $this->assertStringStartsWith('prefix', 'foo');
    }
}

Running the test shown above yields the output shown below:

./tools/phpunit tests/StringStartsWithTest.php
PHPUnit 11.4.3 by Sebastian Bergmann and contributors.

Runtime:       PHP 8.4.1

F                                                                   1 / 1 (100%)

Time: 00:00, Memory: 25.14 MB

There was 1 failure:

1) StringStartsWithTest::testFailure
Failed asserting that 'foo' starts with "prefix".

/path/to/tests/StringStartsWithTest.php:8

FAILURES!
Tests: 1, Assertions: 1, Failures: 1.

assertStringEndsWith()

assertStringEndsWith(string $suffix, string $string[, string $message])

Reports an error identified by $message if the $string does not end with $suffix.

assertStringEndsNotWith() is the inverse of this assertion and takes the same arguments.

Example 1.47 Usage of assertStringEndsWith()
<?php declare(strict_types=1);
use PHPUnit\Framework\TestCase;

final class StringEndsWithTest extends TestCase
{
    public function testFailure(): void
    {
        $this->assertStringEndsWith('suffix', 'foo');
    }
}

Running the test shown above yields the output shown below:

./tools/phpunit tests/StringEndsWithTest.php
PHPUnit 11.4.3 by Sebastian Bergmann and contributors.

Runtime:       PHP 8.4.1

F                                                                   1 / 1 (100%)

Time: 00:00, Memory: 25.14 MB

There was 1 failure:

1) StringEndsWithTest::testFailure
Failed asserting that 'foo' ends with "suffix".

/path/to/tests/StringEndsWithTest.php:8

FAILURES!
Tests: 1, Assertions: 1, Failures: 1.

assertStringContainsString()

assertStringContainsString(string $needle, string $haystack[, string $message])

Reports an error identified by $message if $needle is not a substring of $haystack.

assertStringNotContainsString() is the inverse of this assertion and takes the same arguments.

assertStringContainsStringIgnoringLineEndings() takes the same arguments and can be used if line endings should be ignored.

Example 1.48 Usage of assertStringContainsString()
<?php declare(strict_types=1);
use PHPUnit\Framework\TestCase;

final class StringContainsStringTest extends TestCase
{
    public function testFailure(): void
    {
        $this->assertStringContainsString('foo', 'bar');
    }
}

Running the test shown above yields the output shown below:

./tools/phpunit tests/StringContainsStringTest.php
PHPUnit 11.4.3 by Sebastian Bergmann and contributors.

Runtime:       PHP 8.4.1

F                                                                   1 / 1 (100%)

Time: 00:00, Memory: 25.14 MB

There was 1 failure:

1) StringContainsStringTest::testFailure
Failed asserting that 'bar' [ASCII](length: 3) contains "foo" [ASCII](length: 3).

/path/to/tests/StringContainsStringTest.php:8

FAILURES!
Tests: 1, Assertions: 1, Failures: 1.

assertStringContainsStringIgnoringCase()

assertStringContainsStringIgnoringCase(string $needle, string $haystack[, string $message])

Reports an error identified by $message if $needle is not a substring of $haystack.

Differences in casing are ignored when $needle is searched for in $haystack. This also works for Unicode characters with diacritics (accents, umlauts, circumflex, etc.) as long as both strings have the same Normalization Form.

assertStringNotContainsStringIgnoringCase() is the inverse of this assertion and takes the same arguments.

Example 1.49 Usage of assertStringContainsStringIgnoringCase()
<?php declare(strict_types=1);
use PHPUnit\Framework\TestCase;

final class StringContainsStringIgnoringCaseTest extends TestCase
{
    public function testFailure(): void
    {
        $this->assertStringContainsStringIgnoringCase('foo', 'bar');
    }
}

Running the test shown above yields the output shown below:

./tools/phpunit tests/StringContainsStringIgnoringCaseTest.php
PHPUnit 11.4.3 by Sebastian Bergmann and contributors.

Runtime:       PHP 8.4.1

F                                                                   1 / 1 (100%)

Time: 00:00, Memory: 25.14 MB

There was 1 failure:

1) StringContainsStringIgnoringCaseTest::testFailure
Failed asserting that 'bar' [Encoding ignored](length: 3) contains "foo" [Encoding ignored](length: 3).

/path/to/tests/StringContainsStringIgnoringCaseTest.php:8

FAILURES!
Tests: 1, Assertions: 1, Failures: 1.

assertStringEqualsStringIgnoringLineEndings()

assertStringEqualsStringIgnoringLineEndings(string $expected, string $actual[, string $message])

Reports an error identified by $message if the two strings $expected and $actual are not equal while ignoring line endings.

assertMatchesRegularExpression()

assertMatchesRegularExpression(string $pattern, string $string[, string $message])

Reports an error identified by $message if $string does not match the regular expression $pattern.

assertDoesNotMatchRegularExpression() is the inverse of this assertion and takes the same arguments.

Example 1.50 Usage of assertMatchesRegularExpression()
<?php declare(strict_types=1);
use PHPUnit\Framework\TestCase;

final class MatchesRegularExpressionTest extends TestCase
{
    public function testFailure(): void
    {
        $this->assertMatchesRegularExpression('/foo/', 'bar');
    }
}

Running the test shown above yields the output shown below:

./tools/phpunit tests/MatchesRegularExpressionTest.php
PHPUnit 11.4.3 by Sebastian Bergmann and contributors.

Runtime:       PHP 8.4.1

F                                                                   1 / 1 (100%)

Time: 00:00, Memory: 25.14 MB

There was 1 failure:

1) MatchesRegularExpressionTest::testFailure
Failed asserting that 'bar' matches PCRE pattern "/foo/".

/path/to/tests/MatchesRegularExpressionTest.php:8

FAILURES!
Tests: 1, Assertions: 1, Failures: 1.

assertStringMatchesFormat()

assertStringMatchesFormat(string $format, string $string[, string $message])

Reports an error identified by $message if the $string does not match the $format string.

assertStringNotMatchesFormat() is the inverse of this assertion and takes the same arguments.

Example 1.51 Usage of assertStringMatchesFormat()
<?php declare(strict_types=1);
use PHPUnit\Framework\TestCase;

final class StringMatchesFormatTest extends TestCase
{
    public function testFailure(): void
    {
        $this->assertStringMatchesFormat('%i', 'foo');
    }
}

Running the test shown above yields the output shown below:

./tools/phpunit tests/StringMatchesFormatTest.php
PHPUnit 11.4.3 by Sebastian Bergmann and contributors.

Runtime:       PHP 8.4.1

F                                                                   1 / 1 (100%)

Time: 00:00, Memory: 25.14 MB

There was 1 failure:

1) StringMatchesFormatTest::testFailure
Failed asserting that string matches format description.
--- Expected
+++ Actual
@@ @@
-%i
+foo

/path/to/tests/StringMatchesFormatTest.php:8

FAILURES!
Tests: 1, Assertions: 1, Failures: 1.

The format string may contain the following placeholders:

  • %e: Represents a directory separator, for example / on Linux.

  • %s: One or more of anything (character or white space) except the end of line character.

  • %S: Zero or more of anything (character or white space) except the end of line character.

  • %a: One or more of anything (character or white space) including the end of line character.

  • %A: Zero or more of anything (character or white space) including the end of line character.

  • %w: Zero or more white space characters.

  • %i: A signed integer value, for example +3142, -3142.

  • %d: An unsigned integer value, for example 123456.

  • %x: One or more hexadecimal character. That is, characters in the range 0-9, a-f, A-F.

  • %f: A floating point number, for example: 3.142, -3.142, 3.142E-10, 3.142e+10.

  • %c: A single character of any sort.

  • %%: A literal percent character: %.

Deprecation: assertStringNotMatchesFormat() is deprecated

As of PHPUnit 10.4, the assertStringNotMatchesFormat() method is soft-deprecated, meaning its declaration is annotated with @deprecated so that IDEs and static analysis tools can warn about its usage.

Starting with PHPUnit 11, using the assertStringNotMatchesFormat() method will trigger a deprecation warning. The method will be removed in PHPUnit 12.

assertStringMatchesFormatFile()

assertStringMatchesFormatFile(string $formatFile, string $string[, string $message])

Reports an error identified by $message if the $string does not match the contents of the $formatFile.

assertStringNotMatchesFormatFile() is the inverse of this assertion and takes the same arguments.

Example 1.52 Usage of assertStringMatchesFormatFile()
<?php declare(strict_types=1);
use PHPUnit\Framework\TestCase;

final class StringMatchesFormatFileTest extends TestCase
{
    public function testFailure(): void
    {
        $this->assertStringMatchesFormatFile(
            __DIR__ . '/expected-format.txt',
            'foo',
        );
    }
}

Running the test shown above yields the output shown below:

./tools/phpunit tests/StringMatchesFormatFileTest.php
PHPUnit 11.4.3 by Sebastian Bergmann and contributors.

Runtime:       PHP 8.4.1

F                                                                   1 / 1 (100%)

Time: 00:00, Memory: 25.14 MB

There was 1 failure:

1) StringMatchesFormatFileTest::testFailure
Failed asserting that string matches format description.
--- Expected
+++ Actual
@@ @@
-%i
+foo

/path/to/tests/StringMatchesFormatFileTest.php:8

FAILURES!
Tests: 1, Assertions: 3, Failures: 1.

Deprecation: assertStringNotMatchesFormatFile() is deprecated

As of PHPUnit 10.4, the assertStringNotMatchesFormatFile() method is soft-deprecated, meaning its declaration is annotated with @deprecated so that IDEs and static analysis tools can warn about its usage.

Starting with PHPUnit 11, using the assertStringNotMatchesFormatFile() method will trigger a deprecation warning. The method will be removed in PHPUnit 12.

assertFileMatchesFormat()

assertFileMatchesFormat(string $format, string $actualFile[, string $message])

Reports an error identified by $message if the contents of $actualFile does not match the $format string.

assertFileMatchesFormatFile()

assertFileMatchesFormat(string $formatFile, string $actualFile[, string $message])

Reports an error identified by $message if the contents of $actualFile does not match the contents of the $formatFile.

assertStringEqualsFile()

assertStringEqualsFile(string $expectedFile, string $actualString[, string $message])

Reports an error identified by $message if the file specified by $expectedFile does not have $actualString as its contents.

assertStringNotEqualsFile() is the inverse of this assertion and takes the same arguments.

assertStringEqualsFileCanonicalizing() (and assertStringNotEqualsFileCanonicalizing()) as well as assertStringEqualsFileIgnoringCase() (and assertStringNotEqualsFileIgnoringCase()) do for files what assertEqualsCanonicalizing() (and assertNotEqualsCanonicalizing()) as well as assertEqualsIgnoringCase() (and assertNotEqualsIgnoringCase()) do for strings.

Example 1.53 Usage of assertStringEqualsFile()
<?php declare(strict_types=1);
use PHPUnit\Framework\TestCase;

final class StringEqualsFileTest extends TestCase
{
    public function testFailure(): void
    {
        $this->assertStringEqualsFile(
            __DIR__ . '/expected.txt',
            'actual',
        );
    }
}

Running the test shown above yields the output shown below:

./tools/phpunit tests/StringEqualsFileTest.php
PHPUnit 11.4.3 by Sebastian Bergmann and contributors.

Runtime:       PHP 8.4.1

F                                                                   1 / 1 (100%)

Time: 00:00, Memory: 25.14 MB

There was 1 failure:

1) StringEqualsFileTest::testFailure
Failed asserting that two strings are equal.
--- Expected
+++ Actual
@@ @@
-'expected\n
-'
+'actual'

/path/to/tests/StringEqualsFileTest.php:8

FAILURES!
Tests: 1, Assertions: 2, Failures: 1.

JSON

assertJson()

assertJson(string $actual[, string $message])

Reports an error identified by $message if the value of $actual is not valid JSON.

Example 1.54 Usage of assertJson()
<?php declare(strict_types=1);
use PHPUnit\Framework\TestCase;

final class JsonTest extends TestCase
{
    public function testFailure(): void
    {
        $this->assertJson('not-a-json-string');
    }
}

Running the test shown above yields the output shown below:

./tools/phpunit tests/JsonTest.php
PHPUnit 11.4.3 by Sebastian Bergmann and contributors.

Runtime:       PHP 8.4.1

F                                                                   1 / 1 (100%)

Time: 00:00, Memory: 25.14 MB

There was 1 failure:

1) JsonTest::testFailure
Failed asserting that a string is valid JSON (Syntax error, malformed JSON).

/path/to/tests/JsonTest.php:8

FAILURES!
Tests: 1, Assertions: 1, Failures: 1.

assertJsonFileEqualsJsonFile()

assertJsonFileEqualsJsonFile(string $expectedFile, string $actualFile[, string $message])

Reports an error identified by $message if the value of $actualFile does not match the value of $expectedFile.

assertJsonFileNotEqualsJsonFile() is the inverse of this assertion and takes the same arguments.

Example 1.55 Usage of assertJsonFileEqualsJsonFile()
<?php declare(strict_types=1);
use PHPUnit\Framework\TestCase;

final class JsonFileEqualsJsonFileTest extends TestCase
{
    public function testFailure(): void
    {
        $this->assertJsonFileEqualsJsonFile(
            __DIR__ . '/expected.json',
            __DIR__ . '/actual.json',
        );
    }
}

Running the test shown above yields the output shown below:

./tools/phpunit tests/JsonFileEqualsJsonFileTest.php
PHPUnit 11.4.3 by Sebastian Bergmann and contributors.

Runtime:       PHP 8.4.1

F                                                                   1 / 1 (100%)

Time: 00:00.002, Memory: 25.14 MB

There was 1 failure:

1) JsonFileEqualsJsonFileTest::testFailure
Failed asserting that '{"mascot":"elePHPant"}\n
' matches JSON string "{"mascot":"elephant"}
".
--- Expected
+++ Actual
@@ @@
 {
-    "mascot": "elephant"
+    "mascot": "elePHPant"
 }

/path/to/tests/JsonFileEqualsJsonFileTest.php:8

FAILURES!
Tests: 1, Assertions: 7, Failures: 1.

assertJsonStringEqualsJsonFile()

assertJsonStringEqualsJsonFile(string $expectedFile, string $actualJson[, string $message])

Reports an error identified by $message if the value of $actualJson does not match the value of $expectedFile.

assertJsonStringNotEqualsJsonFile() is the inverse of this assertion and takes the same arguments.

Example 1.56 Usage of assertJsonStringEqualsJsonFile()
<?php declare(strict_types=1);
use PHPUnit\Framework\TestCase;

final class JsonStringEqualsJsonFileTest extends TestCase
{
    public function testFailure(): void
    {
        $this->assertJsonStringEqualsJsonFile(
            __DIR__ . '/expected.json',
            json_encode(['mascot' => 'elephant']),
        );
    }
}

Running the test shown above yields the output shown below:

./tools/phpunit tests/JsonStringEqualsJsonFileTest.php
PHPUnit 11.4.3 by Sebastian Bergmann and contributors.

Runtime:       PHP 8.4.1

F                                                                   1 / 1 (100%)

Time: 00:00, Memory: 25.14 MB

There was 1 failure:

1) JsonStringEqualsJsonFileTest::testFailure
Failed asserting that '{"mascot":"elephant"}' matches JSON string "{"mascot":"elePHPant"}
".
--- Expected
+++ Actual
@@ @@
 {
-    "mascot": "elePHPant"
+    "mascot": "elephant"
 }

/path/to/tests/JsonStringEqualsJsonFileTest.php:8

FAILURES!
Tests: 1, Assertions: 5, Failures: 1.

assertJsonStringEqualsJsonString()

assertJsonStringEqualsJsonString(string $expectedJson, string $actualJson[, string $message])

Reports an error identified by $message if the value of $actualJson does not match the value of $expectedJson.

assertJsonStringNotEqualsJsonString() is the inverse of this assertion and takes the same arguments.

Example 1.57 Usage of assertJsonStringEqualsJsonString()
<?php declare(strict_types=1);
use PHPUnit\Framework\TestCase;

final class JsonStringEqualsJsonStringTest extends TestCase
{
    public function testFailure(): void
    {
        $this->assertJsonStringEqualsJsonString(
            json_encode(['mascot' => 'elePHPant']),
            json_encode(['mascot' => 'elephant']),
        );
    }
}

Running the test shown above yields the output shown below:

./tools/phpunit tests/JsonStringEqualsJsonStringTest.php
PHPUnit 11.4.3 by Sebastian Bergmann and contributors.

Runtime:       PHP 8.4.1

F                                                                   1 / 1 (100%)

Time: 00:00, Memory: 25.14 MB

There was 1 failure:

1) JsonStringEqualsJsonStringTest::testFailure
Failed asserting that '{"mascot":"elephant"}' matches JSON string "{"mascot":"elePHPant"}".
--- Expected
+++ Actual
@@ @@
 {
-    "mascot": "elePHPant"
+    "mascot": "elephant"
 }

/path/to/tests/JsonStringEqualsJsonStringTest.php:8

FAILURES!
Tests: 1, Assertions: 3, Failures: 1.

XML

assertXmlFileEqualsXmlFile()

assertXmlFileEqualsXmlFile(string $expectedFile, string $actualFile[, string $message])

Reports an error identified by $message if the XML document in $actualFile is not equal to the XML document in $expectedFile.

assertXmlFileNotEqualsXmlFile() is the inverse of this assertion and takes the same arguments.

Example 1.58 Usage of assertXmlFileEqualsXmlFile()
<?php declare(strict_types=1);
use PHPUnit\Framework\TestCase;

final class XmlFileEqualsXmlFileTest extends TestCase
{
    public function testFailure(): void
    {
        $this->assertXmlFileEqualsXmlFile(
            __DIR__ . '/expected.xml',
            __DIR__ . '/actual.xml',
        );
    }
}

Running the test shown above yields the output shown below:

./tools/phpunit tests/XmlFileEqualsXmlFileTest.php
PHPUnit 11.4.3 by Sebastian Bergmann and contributors.

Runtime:       PHP 8.4.1

F                                                                   1 / 1 (100%)

Time: 00:00, Memory: 25.14 MB

There was 1 failure:

1) XmlFileEqualsXmlFileTest::testFailure
Failed asserting that two DOM documents are equal.
--- Expected
+++ Actual
@@ @@
 <?xml version="1.0"?>
 <foo>
-  <bar/>
+  <baz/>
 </foo>

/path/to/tests/XmlFileEqualsXmlFileTest.php:8

FAILURES!
Tests: 1, Assertions: 1, Failures: 1.

assertXmlStringEqualsXmlFile()

assertXmlStringEqualsXmlFile(string $expectedFile, string $actualXml[, string $message])

Reports an error identified by $message if the XML document in $actualXml is not equal to the XML document in $expectedFile.

assertXmlStringNotEqualsXmlFile() is the inverse of this assertion and takes the same arguments.

Example 1.59 Usage of assertXmlStringEqualsXmlFile()
<?php declare(strict_types=1);
use PHPUnit\Framework\TestCase;

final class XmlStringEqualsXmlFileTest extends TestCase
{
    public function testFailure(): void
    {
        $this->assertXmlStringEqualsXmlFile(
            __DIR__ . '/expected.xml',
            '<foo><baz/></foo>',
        );
    }
}

Running the test shown above yields the output shown below:

./tools/phpunit tests/XmlStringEqualsXmlFileTest.php
PHPUnit 11.4.3 by Sebastian Bergmann and contributors.

Runtime:       PHP 8.4.1

F                                                                   1 / 1 (100%)

Time: 00:00, Memory: 25.14 MB

There was 1 failure:

1) XmlStringEqualsXmlFileTest::testFailure
Failed asserting that two DOM documents are equal.
--- Expected
+++ Actual
@@ @@
 <?xml version="1.0"?>
 <foo>
-  <bar/>
+  <baz/>
 </foo>

/path/to/tests/XmlStringEqualsXmlFileTest.php:8

FAILURES!
Tests: 1, Assertions: 1, Failures: 1.

assertXmlStringEqualsXmlString()

assertXmlStringEqualsXmlString(string $expectedXml, string $actualXml[, string $message])

Reports an error identified by $message if the XML document in $actualXml is not equal to the XML document in $expectedXml.

assertXmlStringNotEqualsXmlString() is the inverse of this assertion and takes the same arguments.

Example 1.60 Usage of assertXmlStringEqualsXmlString()
<?php declare(strict_types=1);
use PHPUnit\Framework\TestCase;

final class XmlStringEqualsXmlStringTest extends TestCase
{
    public function testFailure(): void
    {
        $this->assertXmlStringEqualsXmlString(
            '<foo><bar/></foo>',
            '<foo><baz/></foo>',
        );
    }
}

Running the test shown above yields the output shown below:

./tools/phpunit tests/XmlStringEqualsXmlStringTest.php
PHPUnit 11.4.3 by Sebastian Bergmann and contributors.

Runtime:       PHP 8.4.1

F                                                                   1 / 1 (100%)

Time: 00:00, Memory: 25.14 MB

There was 1 failure:

1) XmlStringEqualsXmlStringTest::testFailure
Failed asserting that two DOM documents are equal.
--- Expected
+++ Actual
@@ @@
 <?xml version="1.0"?>
 <foo>
-  <bar/>
+  <baz/>
 </foo>

/path/to/tests/XmlStringEqualsXmlStringTest.php:8

FAILURES!
Tests: 1, Assertions: 1, Failures: 1.

Filesystem

assertDirectoryExists()

assertDirectoryExists(string $directory[, string $message])

Reports an error identified by $message if the directory specified by $directory does not exist.

assertDirectoryDoesNotExist() is the inverse of this assertion and takes the same arguments.

Example 1.61 Usage of assertDirectoryExists()
<?php declare(strict_types=1);
use PHPUnit\Framework\TestCase;

final class DirectoryExistsTest extends TestCase
{
    public function testFailure(): void
    {
        $this->assertDirectoryExists('/path/to/directory');
    }
}

Running the test shown above yields the output shown below:

./tools/phpunit tests/DirectoryExistsTest.php
PHPUnit 11.4.3 by Sebastian Bergmann and contributors.

Runtime:       PHP 8.4.1

F                                                                   1 / 1 (100%)

Time: 00:00, Memory: 25.14 MB

There was 1 failure:

1) DirectoryExistsTest::testFailure
Failed asserting that directory "/path/to/directory" exists.

/path/to/tests/DirectoryExistsTest.php:8

FAILURES!
Tests: 1, Assertions: 1, Failures: 1.

assertDirectoryIsReadable()

assertDirectoryIsReadable(string $directory[, string $message])

Reports an error identified by $message if the directory specified by $directory is not a directory or is not readable.

assertDirectoryIsNotReadable() is the inverse of this assertion and takes the same arguments.

Example 1.62 Usage of assertDirectoryIsReadable()
<?php declare(strict_types=1);
use PHPUnit\Framework\TestCase;

final class DirectoryIsReadableTest extends TestCase
{
    public function testFailure(): void
    {
        $this->assertDirectoryIsReadable('/path/to/directory');
    }
}

Running the test shown above yields the output shown below:

./tools/phpunit tests/DirectoryIsReadableTest.php
PHPUnit 10.0.11 by Sebastian Bergmann and contributors.

Runtime:       PHP 8.2.3

F

Time: 00:00, Memory: 14.29 MB

There was 1 failure:

1) DirectoryIsReadableTest::testFailure
Failed asserting that "/path/to/directory" is readable.

/path/to/DirectoryIsReadableTest.php:6

FAILURES!
Tests: 1, Assertions: 1, Failures: 1.

assertDirectoryIsWritable()

assertDirectoryIsWritable(string $directory[, string $message])

Reports an error identified by $message if the directory specified by $directory is not a directory or is not writable.

assertDirectoryIsNotWritable() is the inverse of this assertion and takes the same arguments.

Example 1.63 Usage of assertDirectoryIsWritable()
<?php declare(strict_types=1);
use PHPUnit\Framework\TestCase;

final class DirectoryIsReadableTest extends TestCase
{
    public function testFailure(): void
    {
        $this->assertDirectoryIsReadable('/path/to/directory');
    }
}

Running the test shown above yields the output shown below:

./tools/phpunit tests/DirectoryIsWritableTest.php
PHPUnit 10.0.11 by Sebastian Bergmann and contributors.

Runtime:       PHP 8.2.3

F

Time: 00:00, Memory: 14.29 MB

There was 1 failure:

1) DirectoryIsWritableTest::testFailure
Failed asserting that "/path/to/directory" is writable.

/path/to/DirectoryIsWritableTest.php:6

FAILURES!
Tests: 1, Assertions: 1, Failures: 1.

assertFileExists()

assertFileExists(string $filename[, string $message])

Reports an error identified by $message if the file specified by $filename does not exist.

assertFileDoesNotExist() is the inverse of this assertion and takes the same arguments.

Example 1.64 Usage of assertFileExists()
<?php declare(strict_types=1);
use PHPUnit\Framework\TestCase;

final class FileExistsTest extends TestCase
{
    public function testFailure(): void
    {
        $this->assertFileExists('/path/to/file');
    }
}

Running the test shown above yields the output shown below:

./tools/phpunit tests/FileExistsTest.php
PHPUnit 11.4.3 by Sebastian Bergmann and contributors.

Runtime:       PHP 8.4.1

F                                                                   1 / 1 (100%)

Time: 00:00, Memory: 25.14 MB

There was 1 failure:

1) FileExistsTest::testFailure
Failed asserting that file "/path/to/file" exists.

/path/to/tests/FileExistsTest.php:8

FAILURES!
Tests: 1, Assertions: 1, Failures: 1.

assertFileIsReadable()

assertFileIsReadable(string $filename[, string $message])

Reports an error identified by $message if the file specified by $filename is not a file or is not readable.

assertFileIsNotReadable() is the inverse of this assertion and takes the same arguments.

Example 1.65 Usage of assertFileIsReadable()
<?php declare(strict_types=1);
use PHPUnit\Framework\TestCase;

final class FileIsReadableTest extends TestCase
{
    public function testFailure(): void
    {
        $this->assertFileIsReadable('/path/to/file');
    }
}

Running the test shown above yields the output shown below:

./tools/phpunit tests/FileIsReadableTest.php
PHPUnit 10.0.11 by Sebastian Bergmann and contributors.

Runtime:       PHP 8.2.3

F

Time: 00:00, Memory: 14.29 MB

There was 1 failure:

1) FileIsReadableTest::testFailure
Failed asserting that "/path/to/file" is readable.

/path/to/FileIsReadableTest.php:6

FAILURES!
Tests: 1, Assertions: 1, Failures: 1.

assertFileIsWritable()

assertFileIsWritable(string $filename[, string $message])

Reports an error identified by $message if the file specified by $filename is not a file or is not writable.

assertFileIsNotWritable() is the inverse of this assertion and takes the same arguments.

Example 1.66 Usage of assertFileIsWritable()
<?php declare(strict_types=1);
use PHPUnit\Framework\TestCase;

final class FileIsWritableTest extends TestCase
{
    public function testFailure(): void
    {
        $this->assertFileIsWritable('/path/to/file');
    }
}

Running the test shown above yields the output shown below:

./tools/phpunit tests/FileIsWritableTest.php
PHPUnit 10.0.11 by Sebastian Bergmann and contributors.

Runtime:       PHP 8.2.3

F

Time: 00:00, Memory: 14.29 MB

There was 1 failure:

1) FileIsWritableTest::testFailure
Failed asserting that "/path/to/file" is writable.

/path/to/FileIsWritableTest.php:6

FAILURES!
Tests: 1, Assertions: 1, Failures: 1.

assertIsReadable()

assertIsReadable(string $filename[, string $message])

Reports an error identified by $message if the file or directory specified by $filename is not readable.

assertIsNotReadable() is the inverse of this assertion and takes the same arguments.

Example 1.67 Usage of assertIsReadable()
<?php declare(strict_types=1);
use PHPUnit\Framework\TestCase;

final class IsReadableTest extends TestCase
{
    public function testFailure(): void
    {
        $this->assertIsReadable('/path/to/unreadable');
    }
}

Running the test shown above yields the output shown below:

./tools/phpunit tests/IsReadableTest.php
PHPUnit 10.0.11 by Sebastian Bergmann and contributors.

Runtime:       PHP 8.2.3

F

Time: 00:00, Memory: 14.29 MB

There was 1 failure:

1) IsReadableTest::testFailure
Failed asserting that "/path/to/unreadable" is readable.

/path/to/IsReadableTest.php:6

FAILURES!
Tests: 1, Assertions: 1, Failures: 1.

assertIsWritable()

assertIsWritable(string $filename[, string $message])

Reports an error identified by $message if the file or directory specified by $filename is not writable.

assertIsNotWritable() is the inverse of this assertion and takes the same arguments.

Example 1.68 Usage of assertIsWritable()
<?php declare(strict_types=1);
use PHPUnit\Framework\TestCase;

final class IsWritableTest extends TestCase
{
    public function testFailure(): void
    {
        $this->assertIsWritable('/path/to/unwritable');
    }
}

Running the test shown above yields the output shown below:

./tools/phpunit tests/IsWritableTest.php
PHPUnit 10.0.11 by Sebastian Bergmann and contributors.

Runtime:       PHP 8.2.3

F

Time: 00:00, Memory: 14.29 MB

There was 1 failure:

1) IsWritableTest::testFailure
Failed asserting that "/path/to/unwritable" is writable.

/path/to/IsWritableTest.php:6

FAILURES!
Tests: 1, Assertions: 1, Failures: 1.

Math

assertInfinite()

assertInfinite(mixed $actual[, string $message])

Reports an error identified by $message if $actual is not INF.

assertFinite() is the inverse of this assertion and takes the same arguments.

Example 1.69 Usage of assertInfinite()
<?php declare(strict_types=1);
use PHPUnit\Framework\TestCase;

final class InfiniteTest extends TestCase
{
    public function testFailure(): void
    {
        $this->assertInfinite(1);
    }
}

Running the test shown above yields the output shown below:

./tools/phpunit tests/InfiniteTest.php
PHPUnit 11.4.3 by Sebastian Bergmann and contributors.

Runtime:       PHP 8.4.1

F                                                                   1 / 1 (100%)

Time: 00:00, Memory: 25.14 MB

There was 1 failure:

1) InfiniteTest::testFailure
Failed asserting that 1 is infinite.

/path/to/tests/InfiniteTest.php:8

FAILURES!
Tests: 1, Assertions: 1, Failures: 1.

assertNan()

assertNan(mixed $actual[, string $message])

Reports an error identified by $message if $actual is not NAN.

Example 1.70 Usage of assertNan()
<?php declare(strict_types=1);
use PHPUnit\Framework\TestCase;

final class NanTest extends TestCase
{
    public function testFailure(): void
    {
        $this->assertNan(1);
    }
}

Running the test shown above yields the output shown below:

./tools/phpunit tests/NanTest.php
PHPUnit 11.4.3 by Sebastian Bergmann and contributors.

Runtime:       PHP 8.4.1

F                                                                   1 / 1 (100%)

Time: 00:00, Memory: 25.14 MB

There was 1 failure:

1) NanTest::testFailure
Failed asserting that 1 is nan.

/path/to/tests/NanTest.php:8

FAILURES!
Tests: 1, Assertions: 1, Failures: 1.

Constraints

assertThat()

assertThat(mixed $value, PHPUnit\Framework\Constraint $constraint[, string $message])

Reports an error identified by $message if the $value does not match the $constraint.

More complex assertions can be formulated using the PHPUnit\Framework\Constraint classes. They can be evaluated using the assertThat() method.

This example shows how the logicalNot() and equalTo() constraints can be used, for instance, to express the same assertion as assertNotEquals():

Example 1.71 Usage of assertThat()
<?php declare(strict_types=1);
use PHPUnit\Framework\TestCase;

final class BiscuitTest extends TestCase
{
    public function testEquals(): void
    {
        $theBiscuit = new Biscuit('Ginger');
        $myBiscuit  = new Biscuit('Ginger');

        $this->assertThat(
            $theBiscuit,
            $this->logicalNot(
                $this->equalTo($myBiscuit),
            ),
        );
    }
}

Running the test shown above yields the output shown below:

./tools/phpunit tests/BiscuitTest.php
PHPUnit 11.4.3 by Sebastian Bergmann and contributors.

Runtime:       PHP 8.4.1

F                                                                   1 / 1 (100%)

Time: 00:00, Memory: 25.14 MB

There was 1 failure:

1) BiscuitTest::testEquals
Failed asserting that Biscuit Object #302 (
    'name' => 'Ginger',
) is equal to Biscuit Object #320 (
    'name' => 'Ginger',
).

/path/to/tests/BiscuitTest.php:11

FAILURES!
Tests: 1, Assertions: 1, Failures: 1.

Table 1.1 shows the available PHPUnit\Framework\Constraint classes.

Table 1.1 Constraints

Constraint

Meaning

PHPUnit\Framework\Constraint\IsAnything anything()

Constraint that accepts any input value.

PHPUnit\Framework\Constraint\ArrayHasKey arrayHasKey(mixed $key)

Constraint that asserts that the array has a given key.

PHPUnit\Framework\Constraint\TraversableContains contains(mixed $value)

Constraint that asserts that the array or object that implements the Iterator interface contains a given value.

PHPUnit\Framework\Constraint\TraversableContainsOnly containsOnly(string $type)

Constraint that asserts that the array or object that implements the Iterator interface contains only values of a given type.

PHPUnit\Framework\Constraint\TraversableContainsOnly containsOnlyInstancesOf(string $classname)

Constraint that asserts that the array or object that implements the Iterator interface contains only instances of a given classname.

PHPUnit\Framework\Constraint\IsEqual equalTo($value, $delta = 0, $maxDepth = 10)

Constraint that checks if one value is equal to another.

PHPUnit\Framework\Constraint\DirectoryExists directoryExists()

Constraint that checks if the directory exists.

PHPUnit\Framework\Constraint\FileExists fileExists()

Constraint that checks if the file(name) exists.

PHPUnit\Framework\Constraint\IsReadable isReadable()

Constraint that checks if the file(name) is readable.

PHPUnit\Framework\Constraint\IsWritable isWritable()

Constraint that checks if the file(name) is writable.

PHPUnit\Framework\Constraint\GreaterThan greaterThan(mixed $value)

Constraint that asserts that the value is greater than a given value.

PHPUnit\Framework\Constraint\LogicalOr greaterThanOrEqual(mixed $value)

Constraint that asserts that the value is greater than or equal to a given value.

PHPUnit\Framework\Constraint\IsIdentical identicalTo(mixed $value)

Constraint that asserts that one value is identical to another.

PHPUnit\Framework\Constraint\IsFalse isFalse()

Constraint that asserts that the value is false.

PHPUnit\Framework\Constraint\IsInstanceOf isInstanceOf(string $className)

Constraint that asserts that the object is an instance of a given class.

PHPUnit\Framework\Constraint\IsNull isNull()

Constraint that asserts that the value is null.

PHPUnit\Framework\Constraint\IsTrue isTrue()

Constraint that asserts that the value is true.

PHPUnit\Framework\Constraint\IsType isType(string $type)

Constraint that asserts that the value is of a specified type.

PHPUnit\Framework\Constraint\LessThan lessThan(mixed $value)

Constraint that asserts that the value is smaller than a given value.

PHPUnit\Framework\Constraint\LogicalOr lessThanOrEqual(mixed $value)

Constraint that asserts that the value is smaller than or equal to a given value.

logicalAnd()

Logical AND.

logicalNot(PHPUnit\Framework\Constraint $constraint)

Logical NOT.

logicalOr()

Logical OR.

logicalXor()

Logical XOR.

PHPUnit\Framework\Constraint\PCREMatch matchesRegularExpression(string $pattern)

Constraint that asserts that the string matches a regular expression.

PHPUnit\Framework\Constraint\StringContains stringContains(string $string, bool $case)

Constraint that asserts that the string contains a given string.

PHPUnit\Framework\Constraint\StringEndsWith stringEndsWith(string $suffix)

Constraint that asserts that the string ends with a given suffix.

PHPUnit\Framework\Constraint\StringStartsWith stringStartsWith(string $prefix)

Constraint that asserts that the string starts with a given prefix.