4. Organizing Tests
One of the goals of PHPUnit is that tests should be composable: we want to be able to run any number or combination of tests together, for instance all tests for the whole project, or the tests for all classes of a component that is part of the project, or just the tests for a single class.
PHPUnit supports different ways of organizing tests and composing them into a test suite. This chapter shows the most commonly used approaches.
Composing a Test Suite Using the Filesystem
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 sebastianbergmann/raytracer project.
Looking at this project’s directory structure, we see that the
test case classes in the tests/unit
directory mirror the
package and class structure of the System Under Test (SUT) in the
src
directory:
src tests/unit
├── autoload.php ├── CameraTest.php
├── Camera.php ├── canvas
├── canvas │ ├── AnsiMapperTest.php
│ ├── AnsiMapper.php │ ├── CanvasTest.php
│ ├── CanvasIterator.php │ └── PortablePixmapMapperTest.php
│ ├── Canvas.php ├── ColorTest.php
│ ├── PortablePixmapMapper.php ├── intersection
│ └── WebpMapper.php │ ├── IntersectionCollectionTest.php
├── Color.php │ └── IntersectionTest.php
├── exceptions ├── material
│ ├── Exception.php │ ├── CheckersPatternTest.php
│ ├── IntersectionHasNoHitException.php │ ├── GradientPatternTest.php
│ ├── InvalidArgumentException.php │ ├── MaterialTest.php
│ ├── OutOfBoundsException.php │ ├── PatternTest.php
│ ├── RuntimeException.php │ ├── RingPatternTest.php
│ └── WorldHasNoLightException.php │ └── StripePatternTest.php
├── intersection ├── math
│ ├── IntersectionCollectionIterator.php │ ├── MatrixTest.php
│ ├── IntersectionCollection.php │ ├── RayTest.php
│ ├── Intersection.php │ ├── TransformationsTest.php
│ └── PreparedComputation.php │ └── TupleTest.php
├── material ├── PointLightTest.php
│ ├── CheckersPattern.php ├── shapes
│ ├── GradientPattern.php │ ├── PlaneTest.php
│ ├── Material.php │ ├── ShapeCollectionTest.php
│ ├── Pattern.php │ ├── ShapeTest.php
│ ├── RingPattern.php │ └── SphereTest.php
│ └── StripePattern.php └── WorldTest.php
├── math
│ ├── Matrix.php tests/integration
│ ├── Ray.php └── PuttingItTogetherTest.php
│ ├── Transformations.php
│ └── Tuple.php
├── PointLight.php
├── shapes
│ ├── Plane.php
│ ├── ShapeCollectionIterator.php
│ ├── ShapeCollection.php
│ ├── Shape.php
│ └── Sphere.php
└── World.php
The tests/integration
directory contains integration test cases that are
kept separate from the tests/unit
directory’s unit tests.
To run all tests for this project we need to point the PHPUnit command-line test runner to the test directory:
$ ./tools/phpunit --bootstrap tests/bootstrap.php tests PHPUnit 11.4.0 by Sebastian Bergmann and contributors. Runtime: PHP 8.2.2 ............................................................... 63 / 177 ( 35%) ............................................................... 126 / 177 ( 71%) ................................................... 177 / 177 (100%) Time: 00:17.100, Memory: 28.27 MB 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:
$ ./tools/phpunit --bootstrap src/autoload.php tests/unit/WorldTest.php PHPUnit 11.4.0 by Sebastian Bergmann and contributors. Runtime: PHP 8.2.2 ............. 13 / 13 (100%) Time: 00:00.095, Memory: 8.00 MB OK (13 tests, 30 assertions)
For more fine-grained control of which tests to run we can use the
--filter
option:
$ ./tools/phpunit --bootstrap src/autoload.php tests/unit --filter test_creating_a_world PHPUnit 11.4.0 by Sebastian Bergmann and contributors. Runtime: PHP 8.2.2 . 1 / 1 (100%) Time: 00:00.077, Memory: 10.00 MB OK (1 test, 2 assertions)
Composing a Test Suite Using XML Configuration
PHPUnit’s XML configuration file (The 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.
<?xml version="1.0" encoding="UTF-8"?>
<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="https://schema.phpunit.de/11.4/phpunit.xsd"
bootstrap="tests/bootstrap.php">
<testsuites>
<testsuite name="unit">
<directory>tests/unit</directory>
</testsuite>
<testsuite name="integration">
<directory>tests/integration</directory>
</testsuite>
</testsuites>
</phpunit>
Note
You should reference the schema definition that is appropriate for the PHPUnit version you are using in your XML configuration file. The schema definition for PHPUnit 11.4 can always be found at https://schema.phpunit.de/11.4/phpunit.xsd, for instance.
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:
$ ./tools/phpunit PHPUnit 11.4.0 by Sebastian Bergmann and contributors. Runtime: PHP 8.2.2 Configuration: /path/to/raytracer/phpunit.xml ............................................................... 63 / 177 ( 35%) ............................................................... 126 / 177 ( 71%) ................................................... 177 / 177 (100%) Time: 00:17.100, Memory: 28.27 MB 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:
$ ./tools/phpunit --list-suites PHPUnit 11.4.0 by Sebastian Bergmann and contributors. Available test suite(s): - unit - integration
We can use the PHPUnit test runner’s --testsuite
option to limit the tests that are run
to the tests of a specific test suite that is declared in the XML configuration file:
$ ./tools/phpunit --testsuite unit PHPUnit 11.4.0 by Sebastian Bergmann and contributors. Runtime: PHP 8.2.2 Configuration: /path/to/raytracer/phpunit.xml ............................................................... 63 / 172 ( 36%) ............................................................... 126 / 172 ( 73%) .............................................. 172 / 172 (100%) Time: 00:00.213, Memory: 24.27 MB OK (172 tests, 637 assertions)