2. Writing Tests for PHPUnit

    1. The tests for a class go into a class ClassTest.

    2. ClassTest inherits (most of the time) from PHPUnit\Framework\TestCase.

    3. The tests are public methods that are named test*.

      Alternatively, you can use the @test annotation in a method’s docblock to mark it as a test method.

    4. Inside the test methods, assertion methods such as assertSame() (see Assertions) are used to assert that an actual value matches an expected value.

    Example 2.1 Testing array operations with PHPUnit

    Martin Fowler:

    Adrian Kuhn et. al.:

    Unit Tests are primarily written as a good practice to help developers identify and fix bugs, to refactor code and to serve as documentation for a unit of software under test. To achieve these benefits, unit tests ideally should cover all the possible paths in a program. One unit test usually covers one specific path in one function or method. However a test method is not necessarily an encapsulated, independent entity. Often there are implicit dependencies between test methods, hidden in the implementation scenario of a test.

    PHPUnit supports the declaration of explicit dependencies between test methods. Such dependencies do not define the order in which the test methods are to be executed but they allow the returning of an instance of the test fixture by a producer and passing it to the dependent consumers.

    • A producer is a test method that yields its unit under test as return value.

    • A consumer is a test method that depends on one or more producers and their return values.

    Example 2.2 shows how to use the @depends annotation to express dependencies between test methods.

    Example 2.2 Using the @depends annotation to express dependencies

    1. <?php declare(strict_types=1);
    2. use PHPUnit\Framework\TestCase;
    4. final class StackTest extends TestCase
    5. {
    6.     public function testEmpty(): array
    7.     {
    8.         $stack = [];
    9.         $this->assertEmpty($stack);
    11.         return $stack;
    12.     }
    14.     /**
    15.      * @depends testEmpty
    16.      */
    17.     public function testPush(array $stack): array
    18.     {
    19.         array_push($stack, 'foo');
    20.         $this->assertSame('foo', $stack[count($stack)-1]);
    21.         $this->assertNotEmpty($stack);
    23.         return $stack;
    24.     }
    26.     /**
    27.      * @depends testPush
    28.      */
    29.     public function testPop(array $stack): void
    30.     {
    31.         $this->assertSame('foo', array_pop($stack));
    32.         $this->assertEmpty($stack);
    33.     }
    34. }

    In the example above, the first test, testEmpty(), creates a new array and asserts that it is empty. The test then returns the fixture as its result. The second test, testPush(), depends on testEmpty() and is passed the result of that depended-upon test as its argument. Finally, testPop() depends upon testPush().

    Note

    The return value yielded by a producer is passed “as-is” to its consumers by default. This means that when a producer returns an object, a reference to that object is passed to the consumers. Instead of a reference either (a) a (deep) copy via @depends clone, or (b) a (normal shallow) clone (based on PHP keyword clone) via @depends shallowClone are possible too.

    To localize defects, we want our attention to be focussed on relevant failing tests. This is why PHPUnit skips the execution of a test when a depended-upon test has failed. This improves defect localization by exploiting the dependencies between tests as shown in .

    Example 2.3 Exploiting the dependencies between tests

    1. <?php declare(strict_types=1);
    2. use PHPUnit\Framework\TestCase;
    4. final class DependencyFailureTest extends TestCase
    5. {
    6.     public function testOne(): void
    7.     {
    8.         $this->assertTrue(false);
    9.     }
    11.     /**
    12.      * @depends testOne
    13.      */
    14.     public function testTwo(): void
    15.     {
    16.     }
    17. }
    1. $ phpunit --verbose DependencyFailureTest
    2. PHPUnit 9.6.0 by Sebastian Bergmann and contributors.
    4. FS
    6. Time: 0 seconds, Memory: 5.00Mb
    8. There was 1 failure:
    10. 1) DependencyFailureTest::testOne
    11. Failed asserting that false is true.
    13. /home/sb/DependencyFailureTest.php:6
    15. There was 1 skipped test:
    17. 1) DependencyFailureTest::testTwo
    18. This test depends on "DependencyFailureTest::testOne" to pass.
    20. FAILURES!
    21. Tests: 1, Assertions: 1, Failures: 1, Skipped: 1.

    A test may have more than one @depends annotation. PHPUnit does not change the order in which tests are executed, you have to ensure that the dependencies of a test can actually be met before the test is run.

    A test that has more than one @depends annotation will get a fixture from the first producer as the first argument, a fixture from the second producer as the second argument, and so on. See Example 2.4

    Example 2.4 Test with multiple dependencies

    1. <?php declare(strict_types=1);
    2. use PHPUnit\Framework\TestCase;
    4. final class MultipleDependenciesTest extends TestCase
    5. {
    6.     public function testProducerFirst(): string
    7.     {
    8.         $this->assertTrue(true);
    10.         return 'first';
    11.     }
    13.     public function testProducerSecond(): string
    14.     {
    15.         $this->assertTrue(true);
    17.         return 'second';
    18.     }
    20.     /**
    21.      * @depends testProducerFirst
    22.      * @depends testProducerSecond
    23.      */
    24.     public function testConsumer(string $a, string $b): void
    25.     {
    26.         $this->assertSame('first', $a);
    27.         $this->assertSame('second', $b);
    28.     }
    29. }
    1. $ phpunit --verbose MultipleDependenciesTest
    2. PHPUnit 9.6.0 by Sebastian Bergmann and contributors.
    4. ...
    6. Time: 0 seconds, Memory: 3.25Mb
    8. OK (3 tests, 4 assertions)

    Data Providers

    A test method can accept arbitrary arguments. These arguments are to be provided by one or more data provider methods (additionProvider() in Example 2.5). The data provider method to be used is specified using the @dataProvider annotation.

    Example 2.5 Using a data provider that returns an array of arrays

    1. <?php declare(strict_types=1);
    2. use PHPUnit\Framework\TestCase;
    4. final class DataTest extends TestCase
    5. {
    6.     /**
    7.      * @dataProvider additionProvider
    8.      */
    9.     public function testAdd(int $a, int $b, int $expected): void
    10.     {
    11.         $this->assertSame($expected, $a + $b);
    12.     }
    14.     public function additionProvider(): array
    15.     {
    16.         return [
    17.             [0, 0, 0],
    18.             [0, 1, 1],
    19.             [1, 0, 1],
    20.             [1, 1, 3]
    21.         ];
    22.     }
    23. }
    1. $ phpunit DataTest
    2. PHPUnit 9.6.0 by Sebastian Bergmann and contributors.
    4. ...F
    6. Time: 0 seconds, Memory: 5.75Mb
    8. There was 1 failure:
    10. 1) DataTest::testAdd with data set #3 (1, 1, 3)
    11. Failed asserting that 2 is identical to 3.
    13. /home/sb/DataTest.php:9
    15. FAILURES!
    16. Tests: 4, Assertions: 4, Failures: 1.

    When using a large number of datasets it’s useful to name each one with string key instead of default numeric. Output will be more verbose as it’ll contain that name of a dataset that breaks a test.

    Example 2.6 Using a data provider with named datasets

    1. <?php declare(strict_types=1);
    2. use PHPUnit\Framework\TestCase;
    4. final class DataTest extends TestCase
    5. {
    6.     /**
    7.      * @dataProvider additionProvider
    8.      */
    9.     public function testAdd(int $a, int $b, int $expected): void
    10.     {
    11.         $this->assertSame($expected, $a + $b);
    12.     }
    14.     public function additionProvider(): array
    15.     {
    16.         return [
    17.             'adding zeros'  => [0, 0, 0],
    18.             'zero plus one' => [0, 1, 1],
    19.             'one plus zero' => [1, 0, 1],
    20.             'one plus one'  => [1, 1, 3]
    21.         ];
    22.     }
    23. }
    1. $ phpunit DataTest
    2. PHPUnit 9.6.0 by Sebastian Bergmann and contributors.
    4. ...F
    6. Time: 0 seconds, Memory: 5.75Mb
    8. There was 1 failure:
    10. 1) DataTest::testAdd with data set "one plus one" (1, 1, 3)
    11. Failed asserting that 2 is identical to 3.
    13. /home/sb/DataTest.php:9
    15. FAILURES!
    16. Tests: 4, Assertions: 4, Failures: 1.

    Note

    You can make the test output more verbose by defining a sentence and using the test’s parameter names as placeholders ($a, $b and $expected in the example above) with the annotation. You can also refer to the name of a named data set with $_dataName.

    Example 2.7 Using a data provider that returns an Iterator object

    1. $ phpunit DataTest
    2. PHPUnit 9.6.0 by Sebastian Bergmann and contributors.
    4. ...F
    6. Time: 0 seconds, Memory: 5.75Mb
    8. There was 1 failure:
    10. 1) DataTest::testAdd with data set #3 ('1', '1', '3')
    12. /home/sb/DataTest.php:11
    14. FAILURES!
    15. Tests: 4, Assertions: 4, Failures: 1.

    Example 2.8 The CsvFileIterator class

    1. <?php declare(strict_types=1);
    2. use PHPUnit\Framework\TestCase;
    4. final class CsvFileIterator implements Iterator
    5. {
    6.     private $file;
    7.     private $key = 0;
    8.     private $current;
    10.     public function __construct(string $file)
    11.     {
    12.         $this->file = fopen($file, 'r');
    13.     }
    15.     public function __destruct()
    16.     {
    17.         fclose($this->file);
    18.     }
    20.     public function rewind(): void
    21.     {
    22.         rewind($this->file);
    24.         $this->current = fgetcsv($this->file);
    26.         if (is_array($this->current)) {
    27.             $this->current = array_map('intval', $this->current);
    28.         }
    30.         $this->key = 0;
    31.     }
    33.     public function valid(): bool
    34.     {
    35.         return !feof($this->file);
    36.     }
    38.     public function key(): int
    39.     {
    40.         return $this->key;
    41.     }
    43.     public function current(): array
    44.     {
    45.         return $this->current;
    46.     }
    48.     public function next(): void
    49.     {
    50.         $this->current = fgetcsv($this->file);
    52.         if (is_array($this->current)) {
    53.             $this->current = array_map('intval', $this->current);
    54.         }
    56.         $this->key++;
    57.     }
    58. }

    When a test receives input from both a @dataProvider method and from one or more tests it @depends on, the arguments from the data provider will come before the ones from depended-upon tests. The arguments from depended-upon tests will be the same for each data set. See Example 2.9

    Example 2.9 Combination of @depends and @dataProvider in same test

    1. <?php declare(strict_types=1);
    2. use PHPUnit\Framework\TestCase;
    4. final class DependencyAndDataProviderComboTest extends TestCase
    5. {
    6.     public function provider(): array
    7.     {
    8.         return [['provider1'], ['provider2']];
    9.     }
    11.     public function testProducerFirst(): string
    12.     {
    13.         $this->assertTrue(true);
    15.         return 'first';
    16.     }
    18.     public function testProducerSecond(): string
    19.     {
    20.         $this->assertTrue(true);
    22.         return 'second';
    23.     }
    25.     /**
    26.      * @depends testProducerFirst
    27.      * @depends testProducerSecond
    28.      * @dataProvider provider
    29.      */
    30.     public function testConsumer(): void
    31.     {
    32.         $this->assertSame(
    33.             ['provider1', 'first', 'second'],
    34.             func_get_args()
    35.         );
    36.     }
    37. }
    1. $ phpunit --verbose DependencyAndDataProviderComboTest
    2. PHPUnit 9.6.0 by Sebastian Bergmann and contributors.
    4. ...F
    6. Time: 0 seconds, Memory: 3.50Mb
    8. There was 1 failure:
    10. 1) DependencyAndDataProviderComboTest::testConsumer with data set #1 ('provider2')
    11. Failed asserting that two arrays are identical.
    12. --- Expected
    13. +++ Actual
    14. @@ @@
    15. Array &0 (
    16. -    0 => 'provider1'
    17. +    0 => 'provider2'
    18.      1 => 'first'
    19.      2 => 'second'
    20. )
    21. /home/sb/DependencyAndDataProviderComboTest.php:32
    23. FAILURES!
    24. Tests: 4, Assertions: 4, Failures: 1.

    Example 2.10 Using multiple data providers for a single test

    1. <?php declare(strict_types=1);
    2. use PHPUnit\Framework\TestCase;
    4. final class DataTest extends TestCase
    5. {
    6.     /**
    7.      * @dataProvider additionWithNonNegativeNumbersProvider
    8.      * @dataProvider additionWithNegativeNumbersProvider
    9.      */
    10.     public function testAdd(int $a, int $b, int $expected): void
    11.     {
    12.         $this->assertSame($expected, $a + $b);
    13.     }
    15.     public function additionWithNonNegativeNumbersProvider(): array
    16.     {
    17.         return [
    18.             [0, 1, 1],
    19.             [1, 0, 1],
    20.             [1, 1, 3]
    21.         ];
    22.     }
    24.     public function additionWithNegativeNumbersProvider(): array
    25.     {
    26.         return [
    27.             [-1, 1, 0],
    28.             [-1, -1, -2],
    29.             [1, -1, 0]
    30.         ];
    31.     }
    32.  }
    1. $ phpunit DataTest
    2. PHPUnit 9.6.0 by Sebastian Bergmann and contributors.
    4. ..F...                                                              6 / 6 (100%)
    6. Time: 0 seconds, Memory: 5.75Mb
    8. There was 1 failure:
    10. 1) DataTest::testAdd with data set #3 (1, 1, 3)
    11. Failed asserting that 2 is identical to 3.
    13. /home/sb/DataTest.php:12
    15. FAILURES!
    16. Tests: 6, Assertions: 6, Failures: 1.

    Note

    When a test depends on a test that uses data providers, the depending test will be executed when the test it depends upon is successful for at least one data set. The result of a test that uses data providers cannot be injected into a depending test.

    Note

    All data providers are executed before both the call to the setUpBeforeClass() static method and the first call to the setUp() method. Because of that you can’t access any variables you create there from within a data provider. This is required in order for PHPUnit to be able to compute the total number of tests.

    Example 2.11 shows how to use the expectException() method to test whether an exception is thrown by the code under test.

    Example 2.11 Using the expectException() method

    1. <?php declare(strict_types=1);
    2. use PHPUnit\Framework\TestCase;
    4. final class ExceptionTest extends TestCase
    5. {
    6.     public function testException(): void
    7.     {
    8.         $this->expectException(InvalidArgumentException::class);
    9.     }
    10. }
    1. $ phpunit ExceptionTest
    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) ExceptionTest::testException
    11. Failed asserting that exception of type "InvalidArgumentException" is thrown.
    13. FAILURES!
    14. Tests: 1, Assertions: 1, Failures: 1.

    In addition to the expectException() method the expectExceptionCode(), expectExceptionMessage(), and expectExceptionMessageMatches() methods exist to set up expectations for exceptions raised by the code under test.

    Note

    Note that expectExceptionMessage() asserts that the $actual message contains the $expected message and does not perform an exact string comparison.

    Testing PHP Errors, Warnings, and Notices

    By default, PHPUnit converts PHP errors, warnings, and notices that are triggered during the execution of a test to an exception. Among other benefits, this makes it possible to expect that a PHP error, warning, or notice is triggered in a test as shown in Example 2.12.

    Note

    PHP’s error_reporting runtime configuration can limit which errors PHPUnit will convert to exceptions. If you are having issues with this feature, be sure PHP is not configured to suppress the type of error you are interested in.

    Example 2.12 Expecting PHP errors, warnings, and notices

    1. <?php declare(strict_types=1);
    2. use PHPUnit\Framework\TestCase;
    4. final class ErrorTest extends TestCase
    5. {
    6.     public function testDeprecationCanBeExpected(): void
    7.     {
    8.         $this->expectDeprecation();
    10.         // Optionally test that the message is equal to a string
    11.         $this->expectDeprecationMessage('foo');
    13.         // Or optionally test that the message matches a regular expression
    14.         $this->expectDeprecationMessageMatches('/foo/');
    15.         \trigger_error('foo', \E_USER_DEPRECATED);
    16.     }
    18.     public function testNoticeCanBeExpected(): void
    19.     {
    20.         $this->expectNotice();
    22.         // Optionally test that the message is equal to a string
    23.         $this->expectNoticeMessage('foo');
    25.         // Or optionally test that the message matches a regular expression
    26.         $this->expectNoticeMessageMatches('/foo/');
    28.         \trigger_error('foo', \E_USER_NOTICE);
    29.     }
    31.     public function testWarningCanBeExpected(): void
    32.     {
    33.         $this->expectWarning();
    35.         // Optionally test that the message is equal to a string
    36.         $this->expectWarningMessage('foo');
    38.         // Or optionally test that the message matches a regular expression
    39.         $this->expectWarningMessageMatches('/foo/');
    41.         \trigger_error('foo', \E_USER_WARNING);
    42.     }
    44.     public function testErrorCanBeExpected(): void
    45.     {
    46.         $this->expectError();
    48.         // Optionally test that the message is equal to a string
    49.         $this->expectErrorMessage('foo');
    51.         // Or optionally test that the message matches a regular expression
    52.         $this->expectErrorMessageMatches('/foo/');
    54.         \trigger_error('foo', \E_USER_ERROR);
    55.     }
    56. }

    When testing code that uses PHP built-in functions such as fopen() that may trigger errors it can sometimes be useful to use error suppression while testing. This allows you to check the return values by suppressing notices that would lead to an exception raised by PHPUnit’s error handler.

    1. $ phpunit ErrorSuppressionTest
    2. PHPUnit 9.6.0 by Sebastian Bergmann and contributors.
    4. .
    6. Time: 1 seconds, Memory: 5.25Mb
    8. OK (1 test, 1 assertion)

    Without the error suppression the test would fail reporting fopen(/is-not-writeable/file): failed to open stream: No such file or directory.

    Sometimes you want to assert that the execution of a method, for instance, generates an expected output (via echo or print, for example). The PHPUnit\Framework\TestCase class uses PHP’s Output Buffering feature to provide the functionality that is necessary for this.

    shows how to use the expectOutputString() method to set the expected output. If this expected output is not generated, the test will be counted as a failure.

    Example 2.14 Testing the output of a function or method

    1. <?php declare(strict_types=1);
    2. use PHPUnit\Framework\TestCase;
    4. final class OutputTest extends TestCase
    5. {
    6.     public function testExpectFooActualFoo(): void
    7.     {
    8.         $this->expectOutputString('foo');
    10.         print 'foo';
    11.     }
    13.     public function testExpectBarActualBaz(): void
    14.     {
    15.         $this->expectOutputString('bar');
    17.         print 'baz';
    18.     }
    19. }
    1. $ phpunit OutputTest
    2. PHPUnit 9.6.0 by Sebastian Bergmann and contributors.
    4. .F
    6. Time: 0 seconds, Memory: 5.75Mb
    8. There was 1 failure:
    10. 1) OutputTest::testExpectBarActualBaz
    11. Failed asserting that two strings are equal.
    12. --- Expected
    13. +++ Actual
    14. @@ @@
    15. -'bar'
    16. +'baz'
    18. FAILURES!
    19. Tests: 2, Assertions: 2, Failures: 1.

    Table 2.1 shows the methods provided for testing output

    Note

    A test that emits output will fail in strict mode.

    Error output

    Whenever a test fails PHPUnit tries its best to provide you with as much context as possible that can help to identify the problem.

    Example 2.15 Error output generated when an array comparison fails

    1. <?php declare(strict_types=1);
    2. use PHPUnit\Framework\TestCase;
    4. final class ArrayDiffTest extends TestCase
    5. {
    6.     public function testEquality(): void
    7.     {
    8.         $this->assertSame(
    9.             [1, 2,  3, 4, 5, 6],
    10.             [1, 2, 33, 4, 5, 6]
    11.         );
    12.     }
    13. }
    1. $ phpunit ArrayDiffTest
    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) ArrayDiffTest::testEquality
    11. Failed asserting that two arrays are identical.
    12. --- Expected
    13. +++ Actual
    14. @@ @@
    15.  Array (
    16.      0 => 1
    17.      1 => 2
    18. -    2 => 3
    19. +    2 => 33
    20.      3 => 4
    21.      4 => 5
    22.      5 => 6
    23.  )
    25. /home/sb/ArrayDiffTest.php:7
    27. FAILURES!
    28. Tests: 1, Assertions: 1, Failures: 1.

    In this example only one of the array values differs and the other values are shown to provide context on where the error occurred.

    When the generated output would be long to read PHPUnit will split it up and provide a few lines of context around every difference.

    Example 2.16 Error output when an array comparison of a long array fails

    1. <?php declare(strict_types=1);
    2. use PHPUnit\Framework\TestCase;
    4. final class LongArrayDiffTest extends TestCase
    5. {
    6.     public function testEquality(): void
    7.     {
    8.         $this->assertSame(
    9.             [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 2,  3, 4, 5, 6],
    10.             [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 2, 33, 4, 5, 6]
    11.         );
    12.     }
    13. }
    1. $ phpunit LongArrayDiffTest
    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) LongArrayDiffTest::testEquality
    11. Failed asserting that two arrays are identical.
    12. --- Expected
    13. +++ Actual
    14. @@ @@
    15.      11 => 0
    16.      12 => 1
    17.      13 => 2
    18. -    14 => 3
    19. +    14 => 33
    20.      15 => 4
    21.      16 => 5
    22.      17 => 6
    23.  )
    25. /home/sb/LongArrayDiffTest.php:7
    27. FAILURES!
    28. Tests: 1, Assertions: 1, Failures: 1.

    When a comparison fails PHPUnit creates textual representations of the input values and compares those. Due to that implementation a diff might show more problems than actually exist.

    This only happens when using assertEquals() or other ‘weak’ comparison functions on arrays or objects.

    1. <?php declare(strict_types=1);
    2. use PHPUnit\Framework\TestCase;
    4. final class ArrayWeakComparisonTest extends TestCase
    5. {
    6.     public function testEquality(): void
    7.     {
    8.         $this->assertEquals(
    9.             [1, 2, 3, 4, 5, 6],
    10.             ['1', 2, 33, 4, 5, 6]
    11.         );
    12.     }
    13. }
    1. $ phpunit ArrayWeakComparisonTest
    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) ArrayWeakComparisonTest::testEquality
    11. Failed asserting that two arrays are equal.
    12. --- Expected
    13. +++ Actual
    14. @@ @@
    15.  Array (
    16. -    0 => 1
    17. +    0 => '1'
    18.      1 => 2
    19. -    2 => 3
    20. +    2 => 33
    21.      3 => 4
    22.      4 => 5
    23.      5 => 6
    24.  )
    26. /home/sb/ArrayWeakComparisonTest.php:7
    28. Tests: 1, Assertions: 1, Failures: 1.

    In this example the difference in the first index between 1 and '1' is reported even though assertEquals() considers the values as a match.