Chapter 6. Organizing Test Suites

One of the goals of PHPUnit (see Chapter 2) 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.

The PHPUnit_Framework_TestSuite class of the PHPUnit framework allows us to organize tests into a hierarchy of test suites. Let us look at PHPUnit's own test suite as an example.

Example 6.1 shows a cut-down version of Tests/AllTests.php, Example 6.2 a cut-down version of Tests/Framework/AllTests.php.

Example 6.1: The AllTests class

<?php
require_once 'PHPUnit/Framework.php';
 
require_once 'Framework/AllTests.php';
// ...
 
class AllTests
{
    public static function suite()
    {
        $suite = new PHPUnit_Framework_TestSuite('PHPUnit');
 
        $suite->addTest(Framework_AllTests::suite());
        // ...
 
        return $suite;
    }
}
?>

Example 6.2: The Framework_AllTests class

<?php
require_once 'PHPUnit/Framework.php';
 
require_once 'Framework/AssertTest.php';
// ...
 
class Framework_AllTests
{
    public static function suite()
    {
        $suite = new PHPUnit_Framework_TestSuite('PHPUnit Framework');
 
        $suite->addTestSuite('Framework_AssertTest');
        // ...
 
        return $suite;
    }
}
?>

The Framework_AssertTest class is a normal test case class that extends the PHPUnit_Framework_TestCase base class.

Executing phpunit AllTests in the Tests directory will run all tests.
Executing phpunit Framework_AllTests AllTests.php in the Tests/Framework directory will run only the tests for the PHPUnit_Framework_* classes.
Executing phpunit Framework_AssertTest AssertTest.php in the Tests/Framework directory will run only the tests for the PHPUnit_Framework_Assert class.
Executing phpunit --filter testFail Framework_AssertTest AssertTest.php in the Tests/Framework directory will run only the test named testFail from the Framework_AssertTest class.