Chapter 7. 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 7.1 shows a cut-down version of Tests/AllTests.php, Example 7.2 a cut-down version of Tests/Framework/AllTests.php.

Example 7.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 7.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.

Suite-Level Setup

The PHPUnit_Framework_TestSuite class offers two template methods, setUp() and tearDown(), that are called before the first test of the test suite and after the last test of the test suite, respectively.

Example 7.3: The MySuite class

<?php
require_once 'MyTest.php';
 
class MySuite extends PHPUnit_Framework_TestSuite
{
    public static function suite()
    {
        return new MySuite('MyTest');
    }
 
    protected function setUp()
    {
        print "\nMySuite::setUp()";
    }
 
    protected function tearDown()
    {
        print "\nMySuite::tearDown()";
    }
}
?>

The MyTest test case class that is added to the test suite MySuite in Example 7.3 has two test methods, testOne() and testTwo() as well as the setUp() and tearDown() methods. The output shows in which order these eight methods are called:

MySuite::setUp()
MyTest::setUp()
MyTest::testOne()
MyTest::tearDown()
MyTest::setUp()
MyTest::testTwo()
MyTest::tearDown()
MySuite::tearDown()

Variables stored in $this->sharedFixture by the setUp() method of the PHPUnit_Framework_TestSuite class are available as $this->sharedFixture in all the test that are aggregated by the test suite object (see the section called “Sharing Fixture”).

Please note that a TestSuite's setUp() and tearDown() methods will be called even if no test of the test suite is run because it is, for instance, filtered.