1. Assertions

    PHPUnit’s assertions are implemented in . 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()).

    assertArrayHasKey()

    assertArrayHasKey(mixed $key, array $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.1 Usage of assertArrayHasKey()

    1. $ phpunit ArrayHasKeyTest
    2. PHPUnit 9.6.0 by Sebastian Bergmann and contributors.
    4. F
    6. Time: 0 seconds, Memory: 5.00Mb
    8. There was 1 failure:
    10. 1) ArrayHasKeyTest::testFailure
    11. Failed asserting that an array has the key 'foo'.
    13. /home/sb/ArrayHasKeyTest.php:6
    15. FAILURES!
    16. Tests: 1, Assertions: 1, Failures: 1.

    assertClassHasAttribute()

    assertClassHasAttribute(string $attributeName, string $className[, string $message = ''])

    Reports an error identified by $message if $className::attributeName does not exist.

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

    Example 1.2 Usage of assertClassHasAttribute()

    1. <?php declare(strict_types=1);
    2. use PHPUnit\Framework\TestCase;
    4. final class ClassHasAttributeTest extends TestCase
    5. {
    6.     public function testFailure(): void
    7.     {
    8.         $this->assertClassHasAttribute('foo', stdClass::class);
    9.     }
    10. }
    1. $ phpunit ClassHasAttributeTest
    2. PHPUnit 9.6.0 by Sebastian Bergmann and contributors.
    4. F
    6. Time: 0 seconds, Memory: 4.75Mb
    8. There was 1 failure:
    10. 1) ClassHasAttributeTest::testFailure
    11. Failed asserting that class "stdClass" has attribute "foo".
    13. /home/sb/ClassHasAttributeTest.php:6
    15. FAILURES!
    16. Tests: 1, Assertions: 1, Failures: 1.

    assertClassHasStaticAttribute()

    assertClassHasStaticAttribute(string $attributeName, string $className[, string $message = ''])

    Reports an error identified by $message if $className::attributeName does not exist.

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

    Example 1.3 Usage of assertClassHasStaticAttribute()

    1. <?php declare(strict_types=1);
    2. use PHPUnit\Framework\TestCase;
    4. final class ClassHasStaticAttributeTest extends TestCase
    5. {
    6.     public function testFailure(): void
    7.     {
    8.         $this->assertClassHasStaticAttribute('foo', stdClass::class);
    9.     }
    10. }
    1. $ phpunit ClassHasStaticAttributeTest
    2. PHPUnit 9.6.0 by Sebastian Bergmann and contributors.
    4. F
    6. Time: 0 seconds, Memory: 4.75Mb
    8. There was 1 failure:
    10. 1) ClassHasStaticAttributeTest::testFailure
    11. Failed asserting that class "stdClass" has static attribute "foo".
    13. /home/sb/ClassHasStaticAttributeTest.php:6
    15. FAILURES!
    16. 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.4 Usage of assertContains()

    1. <?php declare(strict_types=1);
    2. use PHPUnit\Framework\TestCase;
    4. final class ContainsTest extends TestCase
    5. {
    6.     public function testFailure(): void
    7.     {
    8.         $this->assertContains(4, [1, 2, 3]);
    9.     }
    10. }
    1. $ phpunit ContainsTest
    2. PHPUnit 9.6.0 by Sebastian Bergmann and contributors.
    4. F
    6. Time: 0 seconds, Memory: 5.00Mb
    8. There was 1 failure:
    10. 1) ContainsTest::testFailure
    11. Failed asserting that an array contains 4.
    13. /home/sb/ContainsTest.php:6
    15. FAILURES!
    16. 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.

    Example 1.5 Usage of assertStringContainsString()

    1. <?php declare(strict_types=1);
    2. use PHPUnit\Framework\TestCase;
    4. final class StringContainsStringTest extends TestCase
    5. {
    6.     public function testFailure(): void
    7.     {
    8.         $this->assertStringContainsString('foo', 'bar');
    9.     }
    10. }
    1. $ phpunit StringContainsStringTest
    2. PHPUnit 9.6.0 by Sebastian Bergmann and contributors.
    4. F                                                                   1 / 1 (100%)
    6. Time: 37 ms, Memory: 6.00 MB
    8. There was 1 failure:
    10. 1) StringContainsStringTest::testFailure
    11. Failed asserting that 'bar' contains "foo".
    13. /home/sb/StringContainsStringTest.php:8
    15. FAILURES!
    16. 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 .

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

    Example 1.6 Usage of assertStringContainsStringIgnoringCase()

    1. <?php declare(strict_types=1);
    2. use PHPUnit\Framework\TestCase;
    4. final class StringContainsStringIgnoringCaseTest extends TestCase
    5. {
    6.     public function testFailure(): void
    7.     {
    8.         $this->assertStringContainsStringIgnoringCase('foo', 'bar');
    9.     }
    10. }
    1. $ phpunit StringContainsStringIgnoringCaseTest
    2. PHPUnit 9.6.0 by Sebastian Bergmann and contributors.
    4. F                                                                   1 / 1 (100%)
    6. Time: 40 ms, Memory: 6.00 MB
    8. There was 1 failure:
    10. 1) StringContainsStringTest::testFailure
    11. Failed asserting that 'bar' contains "foo".
    13. /home/sb/StringContainsStringIgnoringCaseTest.php:8
    15. FAILURES!
    16. Tests: 1, Assertions: 1, Failures: 1.

    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.

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

    Example 1.7 Usage of assertContainsOnly()

    1. <?php declare(strict_types=1);
    2. use PHPUnit\Framework\TestCase;
    4. final class ContainsOnlyTest extends TestCase
    5. {
    6.     public function testFailure(): void
    7.     {
    8.         $this->assertContainsOnly('string', ['1', '2', 3]);
    9.     }
    10. }
    1. $ phpunit ContainsOnlyTest
    2. PHPUnit 9.6.0 by Sebastian Bergmann and contributors.
    4. F
    6. Time: 0 seconds, Memory: 5.00Mb
    8. There was 1 failure:
    10. 1) ContainsOnlyTest::testFailure
    11. Failed asserting that Array (
    12.     0 => '1'
    13.     1 => '2'
    14.     2 => 3
    15. ) contains only values of type "string".
    17. /home/sb/ContainsOnlyTest.php:6
    19. FAILURES!
    20. Tests: 1, Assertions: 1, Failures: 1.

    assertContainsOnlyInstancesOf()

    assertContainsOnlyInstancesOf(string $classname, Traversable|array $haystack[, string $message = ''])

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

    Example 1.8 Usage of assertContainsOnlyInstancesOf()

    1. <?php declare(strict_types=1);
    2. use PHPUnit\Framework\TestCase;
    4. final class ContainsOnlyInstancesOfTest extends TestCase
    5. {
    6.     public function testFailure(): void
    7.     {
    8.         $this->assertContainsOnlyInstancesOf(
    9.             Foo::class,
    10.             [new Foo, new Bar, new Foo]
    11.         );
    12.     }
    13. }
    1. $ phpunit ContainsOnlyInstancesOfTest
    2. PHPUnit 9.6.0 by Sebastian Bergmann and contributors.
    4. F
    6. Time: 0 seconds, Memory: 5.00Mb
    8. There was 1 failure:
    10. 1) ContainsOnlyInstancesOfTest::testFailure
    11. Failed asserting that Array ([0]=> Bar Object(...)) is an instance of class "Foo".
    13. /home/sb/ContainsOnlyInstancesOfTest.php:6
    15. FAILURES!
    16. Tests: 1, Assertions: 1, Failures: 1.

    assertCount()

    assertCount($expectedCount, $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.9 Usage of assertCount()

    1. <?php declare(strict_types=1);
    2. use PHPUnit\Framework\TestCase;
    4. final class CountTest extends TestCase
    5. {
    6.     public function testFailure(): void
    7.     {
    8.         $this->assertCount(0, ['foo']);
    9.     }
    10. }
    1. $ phpunit CountTest
    2. PHPUnit 9.6.0 by Sebastian Bergmann and contributors.
    4. F
    6. Time: 0 seconds, Memory: 4.75Mb
    8. There was 1 failure:
    10. 1) CountTest::testFailure
    11. Failed asserting that actual size 1 matches expected size 0.
    13. /home/sb/CountTest.php:6
    15. FAILURES!
    16. Tests: 1, Assertions: 1, Failures: 1.

    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.10 Usage of assertDirectoryExists()

    1. <?php declare(strict_types=1);
    2. use PHPUnit\Framework\TestCase;
    4. final class DirectoryExistsTest extends TestCase
    5. {
    6.     public function testFailure(): void
    7.     {
    8.         $this->assertDirectoryExists('/path/to/directory');
    9.     }
    10. }
    1. $ phpunit DirectoryExistsTest
    2. PHPUnit 9.6.0 by Sebastian Bergmann and contributors.
    4. F
    6. Time: 0 seconds, Memory: 4.75Mb
    8. There was 1 failure:
    10. 1) DirectoryExistsTest::testFailure
    11. Failed asserting that directory "/path/to/directory" exists.
    13. /home/sb/DirectoryExistsTest.php:6
    15. FAILURES!
    16. 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.11 Usage of assertDirectoryIsReadable()

    1. <?php declare(strict_types=1);
    2. use PHPUnit\Framework\TestCase;
    4. final class DirectoryIsReadableTest extends TestCase
    5. {
    6.     public function testFailure(): void
    7.     {
    8.         $this->assertDirectoryIsReadable('/path/to/directory');
    9.     }
    10. }
    1. $ phpunit DirectoryIsReadableTest
    2. PHPUnit 9.6.0 by Sebastian Bergmann and contributors.
    4. F
    6. Time: 0 seconds, Memory: 4.75Mb
    8. There was 1 failure:
    10. 1) DirectoryIsReadableTest::testFailure
    11. Failed asserting that "/path/to/directory" is readable.
    13. /home/sb/DirectoryIsReadableTest.php:6
    15. FAILURES!
    16. 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.12 Usage of assertDirectoryIsWritable()

    1. <?php declare(strict_types=1);
    2. use PHPUnit\Framework\TestCase;
    4. final class DirectoryIsWritableTest extends TestCase
    5. {
    6.     public function testFailure(): void
    7.     {
    8.         $this->assertDirectoryIsWritable('/path/to/directory');
    9.     }
    10. }
    1. $ phpunit DirectoryIsWritableTest
    2. PHPUnit 9.6.0 by Sebastian Bergmann and contributors.
    4. F
    6. Time: 0 seconds, Memory: 4.75Mb
    8. There was 1 failure:
    10. 1) DirectoryIsWritableTest::testFailure
    11. Failed asserting that "/path/to/directory" is writable.
    13. /home/sb/DirectoryIsWritableTest.php:6
    15. FAILURES!
    16. Tests: 1, Assertions: 1, Failures: 1.

    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.13 Usage of assertEmpty()

    1. <?php declare(strict_types=1);
    2. use PHPUnit\Framework\TestCase;
    4. final class EmptyTest extends TestCase
    5. {
    6.     public function testFailure(): void
    7.     {
    8.         $this->assertEmpty(['foo']);
    9.     }
    10. }
    1. $ phpunit EmptyTest
    2. PHPUnit 9.6.0 by Sebastian Bergmann and contributors.
    4. F
    6. Time: 0 seconds, Memory: 4.75Mb
    8. There was 1 failure:
    10. 1) EmptyTest::testFailure
    11. Failed asserting that an array is empty.
    13. /home/sb/EmptyTest.php:6
    15. FAILURES!
    16. Tests: 1, Assertions: 1, Failures: 1.

    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.14 Usage of assertEquals()

    1. <?php declare(strict_types=1);
    2. use PHPUnit\Framework\TestCase;
    4. final class EqualsTest extends TestCase
    5. {
    6.     public function testFailure(): void
    7.     {
    8.         $this->assertEquals(1, 0);
    9.     }
    11.     public function testFailure2(): void
    12.     {
    13.         $this->assertEquals('bar', 'baz');
    14.     }
    16.     public function testFailure3(): void
    17.     {
    18.         $this->assertEquals("foo\nbar\nbaz\n", "foo\nbah\nbaz\n");
    19.     }
    20. }
    1. $ phpunit EqualsTest
    2. PHPUnit 9.6.0 by Sebastian Bergmann and contributors.
    4. FFF
    6. Time: 0 seconds, Memory: 5.25Mb
    8. There were 3 failures:
    10. 1) EqualsTest::testFailure
    11. Failed asserting that 0 matches expected 1.
    13. /home/sb/EqualsTest.php:6
    15. 2) EqualsTest::testFailure2
    16. Failed asserting that two strings are equal.
    17. --- Expected
    18. +++ Actual
    19. @@ @@
    20. -'bar'
    21. +'baz'
    23. /home/sb/EqualsTest.php:11
    25. 3) EqualsTest::testFailure3
    26. Failed asserting that two strings are equal.
    27. --- Expected
    28. +++ Actual
    29. @@ @@
    30.  'foo
    31. -bar
    32. +bah
    33.  baz
    34.  '
    36. /home/sb/EqualsTest.php:16
    38. FAILURES!
    39. Tests: 3, Assertions: 3, Failures: 3.

    More specialized comparisons are used for specific argument types for $expected and $actual, see below.

    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.15 Usage of assertEquals() with DOMDocument objects

    1. <?php declare(strict_types=1);
    2. use PHPUnit\Framework\TestCase;
    4. final class EqualsTest extends TestCase
    5. {
    6.     public function testFailure(): void
    7.     {
    8.         $expected = new DOMDocument;
    9.         $expected->loadXML('<foo><bar/></foo>');
    11.         $actual = new DOMDocument;
    12.         $actual->loadXML('<bar><foo/></bar>');
    14.         $this->assertEquals($expected, $actual);
    15.     }
    16. }
    1. $ phpunit EqualsTest
    2. PHPUnit 9.6.0 by Sebastian Bergmann and contributors.
    4. F
    6. Time: 0 seconds, Memory: 5.00Mb
    8. There was 1 failure:
    10. 1) EqualsTest::testFailure
    11. Failed asserting that two DOM documents are equal.
    12. --- Expected
    13. +++ Actual
    14. @@ @@
    15.  <?xml version="1.0"?>
    16. -<foo>
    17. -  <bar/>
    18. -</foo>
    19. +<bar>
    20. +  <foo/>
    21. +</bar>
    23. /home/sb/EqualsTest.php:12
    25. FAILURES!
    26. 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 attribute values.

    Example 1.16 Usage of assertEquals() with objects

    1. <?php declare(strict_types=1);
    2. use PHPUnit\Framework\TestCase;
    4. final class EqualsTest extends TestCase
    5. {
    6.     public function testFailure(): void
    7.     {
    8.         $expected = new stdClass;
    9.         $expected->foo = 'foo';
    10.         $expected->bar = 'bar';
    12.         $actual = new stdClass;
    13.         $actual->foo = 'bar';
    14.         $actual->baz = 'bar';
    16.         $this->assertEquals($expected, $actual);
    17.     }
    18. }
    1. $ phpunit EqualsTest
    2. PHPUnit 9.6.0 by Sebastian Bergmann and contributors.
    4. F
    6. Time: 0 seconds, Memory: 5.25Mb
    8. There was 1 failure:
    10. 1) EqualsTest::testFailure
    11. Failed asserting that two objects are equal.
    12. --- Expected
    13. +++ Actual
    14. @@ @@
    15.  stdClass Object (
    16. -    'foo' => 'foo'
    17. -    'bar' => 'bar'
    18. +    'foo' => 'bar'
    19. +    'baz' => 'bar'
    20.  )
    22. /home/sb/EqualsTest.php:14
    24. FAILURES!
    25. 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.17 Usage of assertEquals() with arrays

    1. <?php declare(strict_types=1);
    2. use PHPUnit\Framework\TestCase;
    4. final class EqualsTest extends TestCase
    5. {
    6.     public function testFailure(): void
    7.     {
    8.         $this->assertEquals(['a', 'b', 'c'], ['a', 'c', 'd']);
    9.     }
    10. }
    1. $ phpunit EqualsTest
    2. PHPUnit 9.6.0 by Sebastian Bergmann and contributors.
    4. F
    6. Time: 0 seconds, Memory: 5.25Mb
    8. There was 1 failure:
    10. 1) EqualsTest::testFailure
    11. Failed asserting that two arrays are equal.
    12. --- Expected
    13. +++ Actual
    14. @@ @@
    15.  Array (
    16.      0 => 'a'
    17. -    1 => 'b'
    18. -    2 => 'c'
    19. +    1 => 'c'
    20. +    2 => 'd'
    21.  )
    23. /home/sb/EqualsTest.php:6
    25. FAILURES!
    26. 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 attributes.

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

    Example 1.18 Usage of assertEqualsCanonicalizing()

    1. <?php declare(strict_types=1);
    2. use PHPUnit\Framework\TestCase;
    4. final class EqualsCanonicalizingTest extends TestCase
    5. {
    6.     public function testFailure()
    7.     {
    8.         $this->assertEqualsCanonicalizing([3, 2, 1], [2, 3, 0, 1]);
    9.     }
    10. }
    1. $ phpunit EqualsCanonicalizingTest
    2. PHPUnit 9.6.0 by Sebastian Bergmann and contributors.
    4. F                                                                   1 / 1 (100%)
    6. Time: 42 ms, Memory: 6.00 MB
    8. There was 1 failure:
    10. 1) EqualsCanonicalizingTest::testFailure
    11. Failed asserting that two arrays are equal.
    12. --- Expected
    13. +++ Actual
    14. @@ @@
    15.  Array (
    16. -    0 => 1
    17. -    1 => 2
    18. -    2 => 3
    19. +    0 => 0
    20. +    1 => 1
    21. +    2 => 2
    22. +    3 => 3
    23.  )
    25. /home/sb/EqualsCanonicalizingTest.php:8
    27. FAILURES!
    28. 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.19 Usage of assertEqualsIgnoringCase()

    1. <?php declare(strict_types=1);
    2. use PHPUnit\Framework\TestCase;
    4. final class EqualsIgnoringCaseTest extends TestCase
    5. {
    6.     public function testFailure()
    7.     {
    8.         $this->assertEqualsIgnoringCase('foo', 'BAR');
    9.     }
    10. }
    1. $ phpunit EqualsIgnoringCaseTest
    2. PHPUnit 9.6.0 by Sebastian Bergmann and contributors.
    4. F                                                                   1 / 1 (100%)
    5. Time: 51 ms, Memory: 6.00 MB
    7. There was 1 failure:
    9. 1) EqualsIgnoringCaseTest::testFailure
    10. Failed asserting that two strings are equal.
    11. --- Expected
    12. +++ Actual
    13. @@ @@
    14. -'foo'
    15. +'BAR'
    17. /home/sb/EqualsIgnoringCaseTest.php:8
    19. FAILURES!
    20. 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 “” to understand why $delta is necessary.

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

    Example 1.20 Usage of assertEqualsWithDelta()

    1. <?php declare(strict_types=1);
    2. use PHPUnit\Framework\TestCase;
    4. final class EqualsWithDeltaTest extends TestCase
    5. {
    6.     public function testFailure()
    7.     {
    8.         $this->assertEqualsWithDelta(1.0, 1.5, 0.1);
    9.     }
    10. }
    1. $ phpunit EqualsWithDeltaTest
    2. PHPUnit 9.6.0 by Sebastian Bergmann and contributors.
    4. F                                                                   1 / 1 (100%)
    6. Time: 41 ms, Memory: 6.00 MB
    8. There was 1 failure:
    10. 1) EqualsWithDeltaTest::testFailure
    11. Failed asserting that 1.5 matches expected 1.0.
    13. /home/sb/EqualsWithDeltaTest.php:8
    15. FAILURES!
    16. 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:

    Example 1.21 Usage of assertObjectEquals()

    1. <?php declare(strict_types=1);
    4. final class SomethingThatUsesEmailTest extends TestCase
    5. {
    6.     public function testSomething(): void
    7.     {
    8.         $a = new Email('user@example.org');
    9.         $b = new Email('user@example.org');
    10.         $c = new Email('user@example.com');
    12.         // This passes
    13.         $this->assertObjectEquals($a, $b);
    15.         // This fails
    16.         $this->assertObjectEquals($a, $c);
    17.     }
    18. }

    Example 1.22 Email value object with equals() method

    1. <?php declare(strict_types=1);
    2. final class Email
    3. {
    4.     private string $email;
    6.     public function __construct(string $email)
    7.     {
    8.         $this->ensureIsValidEmail($email);
    10.         $this->email = $email;
    11.     }
    13.     public function asString(): string
    14.     {
    15.         return $this->email;
    16.     }
    18.     public function equals(self $other): bool
    19.     {
    20.         return $this->asString() === $other->asString();
    21.     }
    23.     private function ensureIsValidEmail(string $email): void
    24.     {
    25.         // ...
    26.     }
    27. }
    1. $ phpunit EqualsTest
    2. PHPUnit 9.6.0 by Sebastian Bergmann and contributors.
    4. F                                                                   1 / 1 (100%)
    6. Time: 00:00.017, Memory: 4.00 MB
    8. There was 1 failure:
    10. 1) SomethingThatUsesEmailTest::testSomething
    11. Failed asserting that two objects are equal.
    12. The objects are not equal according to Email::equals().
    14. /home/sb/SomethingThatUsesEmailTest.php:16
    16. FAILURES!
    17. Tests: 1, Assertions: 2, Failures: 1.

    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.

    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.23 Usage of assertFalse()

    1. $ phpunit FalseTest
    2. PHPUnit 9.6.0 by Sebastian Bergmann and contributors.
    4. F
    6. Time: 0 seconds, Memory: 5.00Mb
    8. There was 1 failure:
    10. 1) FalseTest::testFailure
    11. Failed asserting that true is false.
    13. /home/sb/FalseTest.php:6
    15. FAILURES!
    16. Tests: 1, Assertions: 1, Failures: 1.

    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.

    Example 1.24 Usage of assertFileEquals()

    1. <?php declare(strict_types=1);
    2. use PHPUnit\Framework\TestCase;
    4. final class FileEqualsTest extends TestCase
    5. {
    6.     public function testFailure(): void
    7.     {
    8.         $this->assertFileEquals('/home/sb/expected', '/home/sb/actual');
    9.     }
    10. }
    1. $ phpunit FileEqualsTest
    2. PHPUnit 9.6.0 by Sebastian Bergmann and contributors.
    4. F
    6. Time: 0 seconds, Memory: 5.25Mb
    8. There was 1 failure:
    10. 1) FileEqualsTest::testFailure
    11. Failed asserting that two strings are equal.
    12. --- Expected
    13. +++ Actual
    14. @@ @@
    15. -'expected
    16. +'actual
    17.  '
    19. /home/sb/FileEqualsTest.php:6
    21. FAILURES!
    22. Tests: 1, Assertions: 3, 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.25 Usage of assertFileExists()

    1. <?php declare(strict_types=1);
    2. use PHPUnit\Framework\TestCase;
    4. final class FileExistsTest extends TestCase
    5. {
    6.     public function testFailure(): void
    7.     {
    8.         $this->assertFileExists('/path/to/file');
    9.     }
    10. }
    1. $ phpunit FileExistsTest
    2. PHPUnit 9.6.0 by Sebastian Bergmann and contributors.
    4. F
    6. Time: 0 seconds, Memory: 4.75Mb
    8. There was 1 failure:
    10. 1) FileExistsTest::testFailure
    11. Failed asserting that file "/path/to/file" exists.
    13. /home/sb/FileExistsTest.php:6
    15. FAILURES!
    16. 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.

    1. <?php declare(strict_types=1);
    2. use PHPUnit\Framework\TestCase;
    4. final class FileIsReadableTest extends TestCase
    5. {
    6.     public function testFailure(): void
    7.     {
    8.         $this->assertFileIsReadable('/path/to/file');
    9.     }
    10. }
    1. $ phpunit FileIsReadableTest
    2. PHPUnit 9.6.0 by Sebastian Bergmann and contributors.
    4. F
    6. Time: 0 seconds, Memory: 4.75Mb
    8. There was 1 failure:
    10. 1) FileIsReadableTest::testFailure
    11. Failed asserting that "/path/to/file" is readable.
    13. /home/sb/FileIsReadableTest.php:6
    15. FAILURES!
    16. 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.27 Usage of assertFileIsWritable()

    1. <?php declare(strict_types=1);
    2. use PHPUnit\Framework\TestCase;
    4. final class FileIsWritableTest extends TestCase
    5. {
    6.     public function testFailure(): void
    7.     {
    8.         $this->assertFileIsWritable('/path/to/file');
    9.     }
    10. }
    1. $ phpunit FileIsWritableTest
    2. PHPUnit 9.6.0 by Sebastian Bergmann and contributors.
    4. F
    6. Time: 0 seconds, Memory: 4.75Mb
    8. There was 1 failure:
    10. 1) FileIsWritableTest::testFailure
    11. Failed asserting that "/path/to/file" is writable.
    13. /home/sb/FileIsWritableTest.php:6
    15. FAILURES!
    16. Tests: 1, Assertions: 1, Failures: 1.

    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()

    1. <?php declare(strict_types=1);
    2. use PHPUnit\Framework\TestCase;
    4. final class GreaterThanTest extends TestCase
    5. {
    6.     public function testFailure(): void
    7.     {
    8.         $this->assertGreaterThan(2, 1);
    9.     }
    10. }
    1. $ phpunit GreaterThanTest
    2. PHPUnit 9.6.0 by Sebastian Bergmann and contributors.
    4. F
    6. Time: 0 seconds, Memory: 5.00Mb
    8. There was 1 failure:
    10. 1) GreaterThanTest::testFailure
    11. Failed asserting that 1 is greater than 2.
    13. /home/sb/GreaterThanTest.php:6
    15. FAILURES!
    16. 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()

    1. <?php declare(strict_types=1);
    2. use PHPUnit\Framework\TestCase;
    4. final class GreatThanOrEqualTest extends TestCase
    5. {
    6.     public function testFailure(): void
    7.     {
    8.         $this->assertGreaterThanOrEqual(2, 1);
    9.     }
    10. }
    1. $ phpunit GreaterThanOrEqualTest
    2. PHPUnit 9.6.0 by Sebastian Bergmann and contributors.
    4. F
    6. Time: 0 seconds, Memory: 5.25Mb
    8. There was 1 failure:
    10. 1) GreatThanOrEqualTest::testFailure
    11. Failed asserting that 1 is equal to 2 or is greater than 2.
    13. /home/sb/GreaterThanOrEqualTest.php:6
    15. FAILURES!
    16. Tests: 1, Assertions: 2, Failures: 1.

    assertInfinite()

    assertInfinite(mixed $variable[, string $message = ''])

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

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

    Example 1.30 Usage of assertInfinite()

    1. <?php declare(strict_types=1);
    2. use PHPUnit\Framework\TestCase;
    4. final class InfiniteTest extends TestCase
    5. {
    6.     public function testFailure(): void
    7.     {
    8.         $this->assertInfinite(1);
    9.     }
    10. }
    1. $ phpunit InfiniteTest
    2. PHPUnit 9.6.0 by Sebastian Bergmann and contributors.
    4. F
    6. Time: 0 seconds, Memory: 5.00Mb
    8. There was 1 failure:
    10. 1) InfiniteTest::testFailure
    11. Failed asserting that 1 is infinite.
    13. /home/sb/InfiniteTest.php:6
    15. FAILURES!
    16. Tests: 1, Assertions: 1, Failures: 1.

    assertInstanceOf()

    assertInstanceOf($expected, $actual[, $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.31 Usage of assertInstanceOf()

    1. <?php declare(strict_types=1);
    2. use PHPUnit\Framework\TestCase;
    4. final class InstanceOfTest extends TestCase
    5. {
    6.     public function testFailure(): void
    7.     {
    8.         $this->assertInstanceOf(RuntimeException::class, new Exception);
    9.     }
    10. }
    1. $ phpunit InstanceOfTest
    2. PHPUnit 9.6.0 by Sebastian Bergmann and contributors.
    4. F
    6. Time: 0 seconds, Memory: 5.00Mb
    8. There was 1 failure:
    10. 1) InstanceOfTest::testFailure
    11. Failed asserting that Exception Object (...) is an instance of class "RuntimeException".
    13. /home/sb/InstanceOfTest.php:6
    15. FAILURES!
    16. Tests: 1, Assertions: 1, Failures: 1.

    assertIsArray()

    assertIsArray($actual[, $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.32 Usage of assertIsArray()

    1. <?php
    2. use PHPUnit\Framework\TestCase;
    4. class ArrayTest extends TestCase
    5. {
    6.     public function testFailure()
    7.     {
    8.         $this->assertIsArray(null);
    9.     }
    10. }
    1. $ phpunit ArrayTest
    2. PHPUnit |version|.0 by Sebastian Bergmann and contributors.
    4. F
    6. Time: 0 seconds, Memory: 5.00Mb
    8. There was 1 failure:
    10. 1) ArrayTest::testFailure
    11. Failed asserting that null is of type "array".
    13. /home/sb/ArrayTest.php:8
    15. FAILURES!
    16. Tests: 1, Assertions: 1, Failures: 1.

    assertIsBool()

    assertIsBool($actual[, $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.33 Usage of assertIsBool()

    1. <?php declare(strict_types=1);
    2. use PHPUnit\Framework\TestCase;
    4. final class BoolTest extends TestCase
    5. {
    6.     public function testFailure(): void
    7.     {
    8.         $this->assertIsBool(null);
    9.     }
    10. }
    1. $ phpunit BoolTest
    2. PHPUnit |version|.0 by Sebastian Bergmann and contributors.
    4. F
    6. Time: 0 seconds, Memory: 5.00Mb
    8. There was 1 failure:
    10. 1) BoolTest::testFailure
    11. Failed asserting that null is of type "bool".
    13. /home/sb/BoolTest.php:8
    15. FAILURES!
    16. Tests: 1, Assertions: 1, Failures: 1.

    assertIsCallable()

    assertIsCallable($actual[, $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.34 Usage of assertIsCallable()

    1. <?php
    2. use PHPUnit\Framework\TestCase;
    4. class CallableTest extends TestCase
    5. {
    6.     public function testFailure()
    7.     {
    8.         $this->assertIsCallable(null);
    9.     }
    10. }
    1. $ phpunit CallableTest
    2. PHPUnit |version|.0 by Sebastian Bergmann and contributors.
    4. F
    6. Time: 0 seconds, Memory: 5.00Mb
    8. There was 1 failure:
    10. 1) CallableTest::testFailure
    11. Failed asserting that null is of type "callable".
    13. /home/sb/CallableTest.php:8
    15. FAILURES!
    16. Tests: 1, Assertions: 1, Failures: 1.

    assertIsFloat()

    assertIsFloat($actual[, $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.35 Usage of assertIsFloat()

    1. <?php
    2. use PHPUnit\Framework\TestCase;
    4. class FloatTest extends TestCase
    5. {
    6.     public function testFailure()
    7.     {
    8.         $this->assertIsFloat(null);
    9.     }
    10. }
    1. $ phpunit FloatTest
    2. PHPUnit |version|.0 by Sebastian Bergmann and contributors.
    4. F
    6. Time: 0 seconds, Memory: 5.00Mb
    8. There was 1 failure:
    10. 1) FloatTest::testFailure
    11. Failed asserting that null is of type "float".
    13. /home/sb/FloatTest.php:8
    15. FAILURES!
    16. Tests: 1, Assertions: 1, Failures: 1.

    assertIsInt()

    assertIsInt($actual[, $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.36 Usage of assertIsInt()

    1. <?php
    2. use PHPUnit\Framework\TestCase;
    4. class IntTest extends TestCase
    5. {
    6.     public function testFailure()
    7.     {
    8.         $this->assertIsInt(null);
    9.     }
    10. }
    1. $ phpunit IntTest
    2. PHPUnit |version|.0 by Sebastian Bergmann and contributors.
    4. F
    6. Time: 0 seconds, Memory: 5.00Mb
    8. There was 1 failure:
    10. 1) IntTest::testFailure
    11. Failed asserting that null is of type "int".
    13. /home/sb/IntTest.php:8
    15. FAILURES!
    16. Tests: 1, Assertions: 1, Failures: 1.

    assertIsIterable()

    assertIsIterable($actual[, $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.37 Usage of assertIsIterable()

    1. <?php
    2. use PHPUnit\Framework\TestCase;
    4. class IterableTest extends TestCase
    5. {
    6.     public function testFailure()
    7.     {
    8.         $this->assertIsIterable(null);
    9.     }
    10. }
    1. $ phpunit IterableTest
    2. PHPUnit |version|.0 by Sebastian Bergmann and contributors.
    4. F
    6. Time: 0 seconds, Memory: 5.00Mb
    8. There was 1 failure:
    10. 1) IterableTest::testFailure
    11. Failed asserting that null is of type "iterable".
    13. /home/sb/IterableTest.php:8
    15. FAILURES!
    16. Tests: 1, Assertions: 1, Failures: 1.

    assertIsNumeric()

    assertIsNumeric($actual[, $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.38 Usage of assertIsNumeric()

    1. <?php
    2. use PHPUnit\Framework\TestCase;
    4. class NumericTest extends TestCase
    5. {
    6.     public function testFailure()
    7.     {
    8.         $this->assertIsNumeric(null);
    9.     }
    10. }
    1. $ phpunit NumericTest
    2. PHPUnit |version|.0 by Sebastian Bergmann and contributors.
    4. F
    6. Time: 0 seconds, Memory: 5.00Mb
    8. There was 1 failure:
    10. 1) NumericTest::testFailure
    11. Failed asserting that null is of type "numeric".
    13. /home/sb/NumericTest.php:8
    15. FAILURES!
    16. Tests: 1, Assertions: 1, Failures: 1.

    assertIsObject()

    assertIsObject($actual[, $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.39 Usage of assertIsObject()

    1. <?php
    2. use PHPUnit\Framework\TestCase;
    4. class ObjectTest extends TestCase
    5. {
    6.     public function testFailure()
    7.     {
    8.         $this->assertIsObject(null);
    9.     }
    10. }
    1. $ phpunit ObjectTest
    2. PHPUnit |version|.0 by Sebastian Bergmann and contributors.
    4. F
    6. Time: 0 seconds, Memory: 5.00Mb
    8. There was 1 failure:
    10. 1) ObjectTest::testFailure
    11. Failed asserting that null is of type "object".
    13. /home/sb/ObjectTest.php:8
    15. FAILURES!
    16. Tests: 1, Assertions: 1, Failures: 1.

    assertIsResource()

    assertIsResource($actual[, $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.

    Example 1.40 Usage of assertIsResource()

    1. <?php
    2. use PHPUnit\Framework\TestCase;
    4. class ResourceTest extends TestCase
    5. {
    6.     public function testFailure()
    7.     {
    8.         $this->assertIsResource(null);
    9.     }
    10. }
    1. $ phpunit ResourceTest
    2. PHPUnit |version|.0 by Sebastian Bergmann and contributors.
    4. F
    6. Time: 0 seconds, Memory: 5.00Mb
    8. There was 1 failure:
    10. 1) ResourceTest::testFailure
    11. Failed asserting that null is of type "resource".
    13. /home/sb/ResourceTest.php:8
    15. FAILURES!
    16. Tests: 1, Assertions: 1, Failures: 1.

    assertIsScalar()

    assertIsScalar($actual[, $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.41 Usage of assertIsScalar()

    1. <?php
    2. use PHPUnit\Framework\TestCase;
    4. class ScalarTest extends TestCase
    5. {
    6.     public function testFailure()
    7.     {
    8.         $this->assertIsScalar(null);
    9.     }
    10. }
    1. $ phpunit ScalarTest
    2. PHPUnit |version|.0 by Sebastian Bergmann and contributors.
    4. F
    6. Time: 0 seconds, Memory: 5.00Mb
    8. There was 1 failure:
    10. 1) ScalarTest::testFailure
    11. Failed asserting that null is of type "scalar".
    13. /home/sb/ScalarTest.php:8
    15. FAILURES!
    16. Tests: 1, Assertions: 1, Failures: 1.

    assertIsString()

    assertIsString($actual[, $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.42 Usage of assertIsString()

    1. <?php
    2. use PHPUnit\Framework\TestCase;
    4. class StringTest extends TestCase
    5. {
    6.     public function testFailure()
    7.     {
    8.         $this->assertIsString(null);
    9.     }
    10. }
    1. $ phpunit StringTest
    2. PHPUnit 9.6.0 by Sebastian Bergmann and contributors.
    4. F
    6. Time: 0 seconds, Memory: 5.00Mb
    8. There was 1 failure:
    10. 1) StringTest::testFailure
    11. Failed asserting that null is of type "string".
    13. /home/sb/StringTest.php:8
    15. FAILURES!
    16. 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.43 Usage of assertIsReadable()

    1. <?php declare(strict_types=1);
    2. use PHPUnit\Framework\TestCase;
    4. final class IsReadableTest extends TestCase
    5.     public function testFailure(): void
    6.     {
    7.         $this->assertIsReadable('/path/to/unreadable');
    8.     }
    9. }
    1. $ phpunit IsReadableTest
    2. PHPUnit 9.6.0 by Sebastian Bergmann and contributors.
    4. F
    6. Time: 0 seconds, Memory: 4.75Mb
    8. There was 1 failure:
    10. 1) IsReadableTest::testFailure
    11. Failed asserting that "/path/to/unreadable" is readable.
    13. /home/sb/IsReadableTest.php:6
    15. FAILURES!
    16. Tests: 1, Assertions: 1, Failures: 1.

    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.44 Usage of assertIsWritable()

    1. <?php declare(strict_types=1);
    2. use PHPUnit\Framework\TestCase;
    4. final class IsWritableTest extends TestCase
    5. {
    6.     public function testFailure(): void
    7.     {
    8.         $this->assertIsWritable('/path/to/unwritable');
    9.     }
    10. }

    assertJsonFileEqualsJsonFile()

    assertJsonFileEqualsJsonFile(mixed $expectedFile, mixed $actualFile[, string $message = ''])

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

    Example 1.45 Usage of assertJsonFileEqualsJsonFile()

    1. <?php declare(strict_types=1);
    2. use PHPUnit\Framework\TestCase;
    4. final class JsonFileEqualsJsonFileTest extends TestCase
    5. {
    6.     public function testFailure(): void
    7.     {
    8.         $this->assertJsonFileEqualsJsonFile(
    9.           'path/to/fixture/file', 'path/to/actual/file');
    10.     }
    11. }
    1. $ phpunit JsonFileEqualsJsonFileTest
    2. PHPUnit 9.6.0 by Sebastian Bergmann and contributors.
    6. Time: 0 seconds, Memory: 5.00Mb
    8. There was 1 failure:
    10. 1) JsonFileEqualsJsonFile::testFailure
    11. Failed asserting that '{"Mascot":"Tux"}' matches JSON string "["Mascott", "Tux", "OS", "Linux"]".
    13. /home/sb/JsonFileEqualsJsonFileTest.php:5
    15. FAILURES!
    16. Tests: 1, Assertions: 3, Failures: 1.

    assertJsonStringEqualsJsonFile()

    assertJsonStringEqualsJsonFile(mixed $expectedFile, mixed $actualJson[, string $message = ''])

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

    Example 1.46 Usage of assertJsonStringEqualsJsonFile()

    1. <?php declare(strict_types=1);
    2. use PHPUnit\Framework\TestCase;
    4. final class JsonStringEqualsJsonFileTest extends TestCase
    5. {
    6.     public function testFailure(): void
    7.     {
    8.         $this->assertJsonStringEqualsJsonFile(
    9.             'path/to/fixture/file', json_encode(['Mascot' => 'ux'])
    10.         );
    11.     }
    12. }
    1. $ phpunit JsonStringEqualsJsonFileTest
    2. PHPUnit 9.6.0 by Sebastian Bergmann and contributors.
    4. F
    6. Time: 0 seconds, Memory: 5.00Mb
    8. There was 1 failure:
    10. 1) JsonStringEqualsJsonFile::testFailure
    11. Failed asserting that '{"Mascot":"ux"}' matches JSON string "{"Mascott":"Tux"}".
    13. /home/sb/JsonStringEqualsJsonFileTest.php:5
    15. FAILURES!
    16. Tests: 1, Assertions: 3, Failures: 1.

    assertJsonStringEqualsJsonString()

    assertJsonStringEqualsJsonString(mixed $expectedJson, mixed $actualJson[, string $message = ''])

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

    Example 1.47 Usage of assertJsonStringEqualsJsonString()

    1. <?php declare(strict_types=1);
    2. use PHPUnit\Framework\TestCase;
    4. final class JsonStringEqualsJsonStringTest extends TestCase
    5. {
    6.     public function testFailure(): void
    7.     {
    8.         $this->assertJsonStringEqualsJsonString(
    9.             json_encode(['Mascot' => 'Tux']),
    10.             json_encode(['Mascot' => 'ux'])
    11.         );
    12.     }
    13. }
    1. $ phpunit JsonStringEqualsJsonStringTest
    2. PHPUnit 9.6.0 by Sebastian Bergmann and contributors.
    4. F
    6. Time: 0 seconds, Memory: 5.00Mb
    8. There was 1 failure:
    10. 1) JsonStringEqualsJsonStringTest::testFailure
    11. Failed asserting that two objects are equal.
    12. --- Expected
    13. +++ Actual
    14. @@ @@
    15.  stdClass Object (
    16.  -    'Mascot' => 'Tux'
    17.  +    'Mascot' => 'ux'
    18. )
    20. /home/sb/JsonStringEqualsJsonStringTest.php:5
    22. FAILURES!
    23. Tests: 1, Assertions: 3, 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.48 Usage of assertLessThan()

    1. <?php declare(strict_types=1);
    2. use PHPUnit\Framework\TestCase;
    4. final class LessThanTest extends TestCase
    5. {
    6.     public function testFailure(): void
    7.     {
    8.         $this->assertLessThan(1, 2);
    9.     }
    10. }
    1. $ phpunit LessThanTest
    2. PHPUnit 9.6.0 by Sebastian Bergmann and contributors.
    4. F
    6. Time: 0 seconds, Memory: 5.00Mb
    8. There was 1 failure:
    10. 1) LessThanTest::testFailure
    11. Failed asserting that 2 is less than 1.
    13. /home/sb/LessThanTest.php:6
    15. FAILURES!
    16. 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.49 Usage of assertLessThanOrEqual()

    1. <?php declare(strict_types=1);
    2. use PHPUnit\Framework\TestCase;
    4. final class LessThanOrEqualTest extends TestCase
    5. {
    6.     public function testFailure(): void
    7.     {
    8.         $this->assertLessThanOrEqual(1, 2);
    9.     }
    10. }
    1. $ phpunit LessThanOrEqualTest
    2. PHPUnit 9.6.0 by Sebastian Bergmann and contributors.
    4. F
    6. Time: 0 seconds, Memory: 5.25Mb
    8. There was 1 failure:
    10. 1) LessThanOrEqualTest::testFailure
    11. Failed asserting that 2 is equal to 1 or is less than 1.
    13. /home/sb/LessThanOrEqualTest.php:6
    15. FAILURES!
    16. Tests: 1, Assertions: 2, Failures: 1.

    assertNan()

    assertNan(mixed $variable[, string $message = ''])

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

    Example 1.50 Usage of assertNan()

    1. <?php declare(strict_types=1);
    2. use PHPUnit\Framework\TestCase;
    4. final class NanTest extends TestCase
    5. {
    6.     public function testFailure(): void
    7.     {
    8.         $this->assertNan(1);
    9.     }
    10. }
    1. $ phpunit NanTest
    2. PHPUnit 9.6.0 by Sebastian Bergmann and contributors.
    4. F
    6. Time: 0 seconds, Memory: 5.00Mb
    8. There was 1 failure:
    10. 1) NanTest::testFailure
    11. Failed asserting that 1 is nan.
    13. /home/sb/NanTest.php:6
    15. FAILURES!
    16. Tests: 1, Assertions: 1, Failures: 1.

    assertNull()

    assertNull(mixed $variable[, string $message = ''])

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

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

    Example 1.51 Usage of assertNull()

    1. <?php declare(strict_types=1);
    2. use PHPUnit\Framework\TestCase;
    4. final class NullTest extends TestCase
    5. {
    6.     public function testFailure(): void
    7.     {
    8.         $this->assertNull('foo');
    9.     }
    10. }
    1. $ phpunit NotNullTest
    2. PHPUnit 9.6.0 by Sebastian Bergmann and contributors.
    4. F
    6. Time: 0 seconds, Memory: 5.00Mb
    8. There was 1 failure:
    10. 1) NullTest::testFailure
    11. Failed asserting that 'foo' is null.
    13. /home/sb/NotNullTest.php:6
    15. FAILURES!
    16. Tests: 1, Assertions: 1, Failures: 1.

    assertObjectHasAttribute()

    assertObjectHasAttribute(string $attributeName, object $object[, string $message = ''])

    Reports an error identified by $message if $object->attributeName does not exist.

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

    Example 1.52 Usage of assertObjectHasAttribute()

    1. <?php declare(strict_types=1);
    2. use PHPUnit\Framework\TestCase;
    4. final class ObjectHasAttributeTest extends TestCase
    5. {
    6.     public function testFailure(): void
    7.     {
    8.         $this->assertObjectHasAttribute('foo', new stdClass);
    9.     }
    10. }
    1. $ phpunit ObjectHasAttributeTest
    2. PHPUnit 9.6.0 by Sebastian Bergmann and contributors.
    4. F
    6. Time: 0 seconds, Memory: 4.75Mb
    8. There was 1 failure:
    10. 1) ObjectHasAttributeTest::testFailure
    11. Failed asserting that object of class "stdClass" has attribute "foo".
    13. /home/sb/ObjectHasAttributeTest.php:6
    15. FAILURES!
    16. Tests: 1, Assertions: 1, Failures: 1.

    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.53 Usage of assertMatchesRegularExpression()

    1. <?php declare(strict_types=1);
    2. use PHPUnit\Framework\TestCase;
    4. final class RegExpTest extends TestCase
    5. {
    6.     public function testFailure(): void
    7.     {
    8.         $this->assertMatchesRegularExpression('/foo/', 'bar');
    9.     }
    10. }
    1. $ phpunit RegExpTest
    2. PHPUnit 9.6.0 by Sebastian Bergmann and contributors.
    4. F
    6. Time: 0 seconds, Memory: 5.00Mb
    8. There was 1 failure:
    10. 1) RegExpTest::testFailure
    11. Failed asserting that 'bar' matches PCRE pattern "/foo/".
    13. /home/sb/RegExpTest.php:6
    15. FAILURES!
    16. 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.54 Usage of assertStringMatchesFormat()

    1. <?php declare(strict_types=1);
    2. use PHPUnit\Framework\TestCase;
    4. final class StringMatchesFormatTest extends TestCase
    5. {
    6.     public function testFailure(): void
    7.     {
    8.         $this->assertStringMatchesFormat('%i', 'foo');
    9.     }
    10. }
    1. $ phpunit StringMatchesFormatTest
    2. PHPUnit 9.6.0 by Sebastian Bergmann and contributors.
    4. F
    6. Time: 0 seconds, Memory: 5.00Mb
    8. There was 1 failure:
    10. 1) StringMatchesFormatTest::testFailure
    11. Failed asserting that 'foo' matches PCRE pattern "/^[+-]?d+$/s".
    13. /home/sb/StringMatchesFormatTest.php:6
    15. FAILURES!
    16. 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.

    • %c: A single character of any sort.

    • %%: A literal percent character: %.

    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.55 Usage of assertStringMatchesFormatFile()

    1. <?php declare(strict_types=1);
    2. use PHPUnit\Framework\TestCase;
    4. final class StringMatchesFormatFileTest extends TestCase
    5. {
    6.     public function testFailure(): void
    7.     {
    8.         $this->assertStringMatchesFormatFile('/path/to/expected.txt', 'foo');
    9.     }
    10. }
    1. $ phpunit StringMatchesFormatFileTest
    2. PHPUnit 9.6.0 by Sebastian Bergmann and contributors.
    4. F
    6. Time: 0 seconds, Memory: 5.00Mb
    8. There was 1 failure:
    10. 1) StringMatchesFormatFileTest::testFailure
    11. Failed asserting that 'foo' matches PCRE pattern "/^[+-]?d+
    12. $/s".
    14. /home/sb/StringMatchesFormatFileTest.php:6
    16. FAILURES!
    17. Tests: 1, Assertions: 2, Failures: 1.

    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.56 Usage of assertSame()

    1. <?php declare(strict_types=1);
    2. use PHPUnit\Framework\TestCase;
    4. final class SameTest extends TestCase
    5. {
    6.     public function testFailure(): void
    7.     {
    8.         $this->assertSame('2204', 2204);
    9.     }
    10. }
    1. $ phpunit SameTest
    2. PHPUnit 9.6.0 by Sebastian Bergmann and contributors.
    4. F
    6. Time: 0 seconds, Memory: 5.00Mb
    8. There was 1 failure:
    10. 1) SameTest::testFailure
    11. Failed asserting that 2204 is identical to '2204'.
    13. /home/sb/SameTest.php:6
    15. FAILURES!
    16. 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.57 Usage of assertSame() with objects

    1. <?php declare(strict_types=1);
    2. use PHPUnit\Framework\TestCase;
    4. final class SameTest extends TestCase
    5. {
    6.     public function testFailure(): void
    7.     {
    8.         $this->assertSame(new stdClass, new stdClass);
    9.     }
    10. }
    1. $ phpunit SameTest
    2. PHPUnit 9.6.0 by Sebastian Bergmann and contributors.
    4. F
    6. Time: 0 seconds, Memory: 4.75Mb
    8. There was 1 failure:
    10. 1) SameTest::testFailure
    11. Failed asserting that two variables reference the same object.
    13. /home/sb/SameTest.php:6
    15. FAILURES!
    16. Tests: 1, Assertions: 1, Failures: 1.

    assertSameSize()

    assertSameSize($expected, $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.58 Usage of assertSameSize()

    1. <?php declare(strict_types=1);
    2. use PHPUnit\Framework\TestCase;
    4. final class SameSizeTest extends TestCase
    5. {
    6.     public function testFailure(): void
    7.     {
    8.         $this->assertSameSize([1, 2], [1]);
    9.     }
    10. }
    1. $ phpunit StringEndsWithTest
    2. PHPUnit 9.6.0 by Sebastian Bergmann and contributors.
    4. F
    6. Time: 0 second, Memory: 4.00Mb
    8. There was 1 failure:
    10. 1) SameSizeTest::testFailure
    11. Failed asserting that actual size 1 matches expected size 2.
    13. /home/sb/SameSizeTest.php:8
    15. FAILURES!
    16. 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.59 Usage of assertStringEndsWith()

    1. <?php declare(strict_types=1);
    2. use PHPUnit\Framework\TestCase;
    4. final class StringEndsWithTest extends TestCase
    5. {
    6.     public function testFailure(): void
    7.     {
    8.         $this->assertStringEndsWith('suffix', 'foo');
    9.     }
    10. }
    1. $ phpunit StringEndsWithTest
    2. PHPUnit 9.6.0 by Sebastian Bergmann and contributors.
    4. F
    6. Time: 1 second, Memory: 5.00Mb
    8. There was 1 failure:
    10. 1) StringEndsWithTest::testFailure
    11. Failed asserting that 'foo' ends with "suffix".
    13. /home/sb/StringEndsWithTest.php:6
    15. FAILURES!
    16. Tests: 1, Assertions: 1, Failures: 1.

    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.

    Example 1.60 Usage of assertStringEqualsFile()

    1. <?php declare(strict_types=1);
    2. use PHPUnit\Framework\TestCase;
    4. final class StringEqualsFileTest extends TestCase
    5. {
    6.     public function testFailure(): void
    7.     {
    8.         $this->assertStringEqualsFile('/home/sb/expected', 'actual');
    9.     }
    10. }
    1. $ phpunit StringEqualsFileTest
    2. PHPUnit 9.6.0 by Sebastian Bergmann and contributors.
    4. F
    6. Time: 0 seconds, Memory: 5.25Mb
    8. There was 1 failure:
    10. 1) StringEqualsFileTest::testFailure
    11. Failed asserting that two strings are equal.
    12. --- Expected
    13. +++ Actual
    14. @@ @@
    15. -'expected
    16. -'
    17. +'actual'
    19. /home/sb/StringEqualsFileTest.php:6
    21. FAILURES!
    22. Tests: 1, Assertions: 2, Failures: 1.

    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.61 Usage of assertStringStartsWith()

    1. <?php declare(strict_types=1);
    2. use PHPUnit\Framework\TestCase;
    4. final class StringStartsWithTest extends TestCase
    5. {
    6.     public function testFailure(): void
    7.     {
    8.         $this->assertStringStartsWith('prefix', 'foo');
    9.     }
    10. }
    1. $ phpunit StringStartsWithTest
    2. PHPUnit 9.6.0 by Sebastian Bergmann and contributors.
    4. F
    6. Time: 0 seconds, Memory: 5.00Mb
    8. There was 1 failure:
    10. 1) StringStartsWithTest::testFailure
    11. Failed asserting that 'foo' starts with "prefix".
    13. /home/sb/StringStartsWithTest.php:6
    15. FAILURES!
    16. Tests: 1, Assertions: 1, Failures: 1.

    assertThat()

    More complex assertions can be formulated using the PHPUnit\Framework\Constraint classes. They can be evaluated using the assertThat() method. Example 1.62 shows how the logicalNot() and equalTo() constraints can be used to express the same assertion as assertNotEquals().

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

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

    Example 1.62 Usage of assertThat()

    1. <?php declare(strict_types=1);
    2. use PHPUnit\Framework\TestCase;
    4. final class BiscuitTest extends TestCase
    5. {
    6.     public function testEquals(): void
    7.     {
    8.         $theBiscuit = new Biscuit('Ginger');
    9.         $myBiscuit  = new Biscuit('Ginger');
    11.         $this->assertThat(
    12.           $theBiscuit,
    13.           $this->logicalNot(
    14.             $this->equalTo($myBiscuit)
    15.           )
    16.         );
    17.     }
    18. }

    shows the available PHPUnit\Framework\Constraint classes.

    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.63 Usage of assertTrue()

    1. <?php declare(strict_types=1);
    2. use PHPUnit\Framework\TestCase;
    4. final class TrueTest extends TestCase
    5. {
    6.     public function testFailure(): void
    7.     {
    8.         $this->assertTrue(false);
    9.     }
    10. }
    1. $ phpunit TrueTest
    2. PHPUnit 9.6.0 by Sebastian Bergmann and contributors.
    4. F
    6. Time: 0 seconds, Memory: 5.00Mb
    8. There was 1 failure:
    10. 1) TrueTest::testFailure
    11. Failed asserting that false is true.
    13. /home/sb/TrueTest.php:6
    15. FAILURES!
    16. Tests: 1, Assertions: 1, Failures: 1.

    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.64 Usage of assertXmlFileEqualsXmlFile()

    1. <?php declare(strict_types=1);
    2. use PHPUnit\Framework\TestCase;
    4. final class XmlFileEqualsXmlFileTest extends TestCase
    5. {
    6.     public function testFailure(): void
    7.     {
    8.         $this->assertXmlFileEqualsXmlFile(
    9.           '/home/sb/expected.xml', '/home/sb/actual.xml');
    10.     }
    11. }
    1. $ phpunit XmlFileEqualsXmlFileTest
    2. PHPUnit 9.6.0 by Sebastian Bergmann and contributors.
    4. F
    6. Time: 0 seconds, Memory: 5.25Mb
    8. There was 1 failure:
    10. 1) XmlFileEqualsXmlFileTest::testFailure
    11. Failed asserting that two DOM documents are equal.
    12. --- Expected
    13. +++ Actual
    14. @@ @@
    15.  <?xml version="1.0"?>
    16.  <foo>
    17. -  <bar/>
    18. +  <baz/>
    19.  </foo>
    21. /home/sb/XmlFileEqualsXmlFileTest.php:7
    23. FAILURES!
    24. Tests: 1, Assertions: 3, Failures: 1.

    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.65 Usage of assertXmlStringEqualsXmlFile()

    1. <?php declare(strict_types=1);
    2. use PHPUnit\Framework\TestCase;
    4. final class XmlStringEqualsXmlFileTest extends TestCase
    5. {
    6.     public function testFailure(): void
    7.     {
    8.         $this->assertXmlStringEqualsXmlFile(
    9.           '/home/sb/expected.xml', '<foo><baz/></foo>');
    10.     }
    11. }
    1. $ phpunit XmlStringEqualsXmlFileTest
    2. PHPUnit 9.6.0 by Sebastian Bergmann and contributors.
    4. F
    6. Time: 0 seconds, Memory: 5.25Mb
    8. There was 1 failure:
    10. 1) XmlStringEqualsXmlFileTest::testFailure
    11. Failed asserting that two DOM documents are equal.
    12. --- Expected
    13. +++ Actual
    14. @@ @@
    15.  <?xml version="1.0"?>
    16.  <foo>
    17. -  <bar/>
    18. +  <baz/>
    19.  </foo>
    21. /home/sb/XmlStringEqualsXmlFileTest.php:7
    23. FAILURES!
    24. Tests: 1, Assertions: 2, 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.66 Usage of assertXmlStringEqualsXmlString()

    1. <?php declare(strict_types=1);
    2. use PHPUnit\Framework\TestCase;
    4. final class XmlStringEqualsXmlStringTest extends TestCase
    5. {
    6.     public function testFailure(): void
    7.     {
    8.         $this->assertXmlStringEqualsXmlString(
    9.           '<foo><bar/></foo>', '<foo><baz/></foo>');
    10.     }