4. Organizing Tests

    PHPUnit supports different ways of organizing tests and composing them into a test suite. This chapter shows the most commonly used approaches.

    Probably the easiest way to compose a test suite is to keep all test case source files in a test directory. PHPUnit can automatically discover and run the tests by recursively traversing the test directory.

    Lets take a look at the test suite of the project.

    Looking at this project’s directory structure, we see that the test case classes in the directory mirror the package and class structure of the System Under Test (SUT) in the src directory:

    To run all tests for this project can need to point the PHPUnit command-line test runner to the test directory:

    1. $ ./tools/phpunit --bootstrap tests/bootstrap.php tests
    2. PHPUnit 10.0.0 by Sebastian Bergmann and contributors.
    4. Runtime:       PHP 8.2.2
    6. ...............................................................  63 / 177 ( 35%)
    7. ............................................................... 126 / 177 ( 71%)
    8. ...................................................             177 / 177 (100%)
    10. Time: 00:17.100, Memory: 28.27 MB
    12. OK (177 tests, 657 assertions)

    Note

    If you point the PHPUnit command-line test runner to a directory it will look for *Test.php files.

    To run only the tests that are declared in the WorldTest test case class in tests/unit/WorldTest.php we can use the following command:

    1. $ ./tools/phpunit --bootstrap src/autoload.php tests/unit --filter test_creating_a_world
    3. Runtime:       PHP 8.2.2
    5. .                                                                   1 / 1 (100%)
    7. Time: 00:00.077, Memory: 10.00 MB
    9. OK (1 test, 2 assertions)

    Composing a Test Suite Using XML Configuration

    PHPUnit’s XML configuration file () can also be used to compose a test suite. Example 4.1 shows a minimal phpunit.xml file that will add all *Test classes that are found in *Test.php files when the tests directory is recursively traversed.

    Example 4.1 Composing a Test Suite Using XML Configuration

    Now that we have an XML configuration file, we can invoke the PHPUnit test runner without arguments (tests, for instance) or options (--bootstrap, for instance) to run our tests:

    1. $ ./tools/phpunit
    2. PHPUnit 10.0.0 by Sebastian Bergmann and contributors.
    4. Runtime:       PHP 8.2.2
    5. Configuration: /path/to/raytracer/phpunit.xml
    8. ............................................................... 126 / 177 ( 71%)
    9. ...................................................             177 / 177 (100%)
    10. Time: 00:17.100, Memory: 28.27 MB
    12. OK (177 tests, 657 assertions)

    The PHPUnit test runner’s --list-suites option can be used to print a list of all test suites defined in PHPUnit’s XML configuration file:

    1. $ ./tools/phpunit --testsuite unit
    2. PHPUnit 10.0.0 by Sebastian Bergmann and contributors.
    4. Runtime:       PHP 8.2.2
    5. Configuration: /path/to/raytracer/phpunit.xml
    7. ...............................................................  63 / 172 ( 36%)
    8. ............................................................... 126 / 172 ( 73%)
    9. ..............................................                  172 / 172 (100%)
    11. Time: 00:00.213, Memory: 24.27 MB