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.
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 12.5.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 12.5.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 12.5.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)
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"?>
<phpunitxmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="https://schema.phpunit.de/11.4/phpunit.xsd"
bootstrap="tests/bootstrap.php">
<testsuites>
<testsuitename="unit">
<directory>tests/unit</directory>
</testsuite>
<testsuitename="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 12.5 can always be found at https://schema.phpunit.de/12.5/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 12.5.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 12.5.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 12.5.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)
© 2005–2025 Sebastian Bergmann
Licensed under the Creative Commons Attribution 3.0 Unported License.
https://docs.phpunit.de/en/12.5/organizing-tests.html