PHPUnit Pocket Guide

setUp() and tearDown() are nicely symmetrical in theory but not in practice. In practice, you only need to implement tearDown() if you have allocated external resources like files or sockets in setUp(). If your setUp() just creates plain PHP objects, you can generally ignore tearDown(). However, if you create many objects in your setUp(), you might want to unset() the variables pointing to those objects in your tearDown() so they can be garbage collected. The garbage collection of test case objects is not predictable.

What happens when you have two tests with slightly different setups? There are two possibilities:

PHPUnit does not provide convenient support for suite-level setup. There are few good reasons to share fixtures between tests, but in most cases the need to share a fixture between tests stems from an unresolved design problem.

A good example of a fixture that makes sense to share across several tests is a database connection: you log into the database once and reuse the database connection instead of creating a new connection for each test. This makes your tests run faster. To do this, write your database tests in a test-case class named DatabaseTests and wrap the test suite in a TestSetup decorator object that overrides setUp() to open the database connection and tearDown() to close the connection, as shown in Example 5.2. You can run the tests from DatabaseTests through the DatabaseTestSetup decorator by invoking, for instance, PHPUnit's command-line test runner with phpunit DatabaseTestSetup.

<?php
require_once 'PHPUnit2/Framework/TestSuite.php';
require_once 'PHPUnit2/Extensions/TestSetup.php';
 
class DatabaseTestSetup extends PHPUnit2_Extensions_TestSetup {
    protected $connection = NULL;
 
    protected function setUp() {
        $this->connection = new PDO(
          'mysql:host=wopr;dbname=test',
          'root',
          ''
        );
    }
 
    protected function tearDown() {
        $this->connection = NULL;
    }
 
    public static function suite() {
        return new DatabaseTestSetup(
          new PHPUnit2_Framework_TestSuite('DatabaseTests')
        );
    }
}
?>

It cannot be emphasized enough that sharing fixtures between tests reduces the value of the tests. The underlying design problem is that objects are too closely bound together. You will achieve better results solving the underlying design problem and then writing tests using stubs (see Chapter 10), than by creating dependencies between tests at runtime and ignoring the opportunity to improve your design.

How do you test exceptions? You cannot directly assert that they are raised. Instead you have to use PHP's exception handling facilities to write the test. The following example demonstrates testing exceptions:

<?php
require_once 'PHPUnit2/Framework/TestCase.php';
 
class ExceptionTest extends PHPUnit2_Framework_TestCase {
    public function testException() {
        try {
            // ... Code that is expected to raise an Exception ...
        }
 
        catch (Exception $expected) {
            return;
        }
 
        $this->fail('An expected Exception has not been raised.');
    }
}
?>

If the code that is expected to raise an exception does not raise an exception, the subsequent call to fail() (see Table 14.2) will halt the test and signal a problem with the test. If the expected exception is raised, the catch block will be executed, and the test will end successfully.

Alternatively, you can extend your test class from PHPUnit2_Extensions_ExceptionTestCase to test whether an exception is thrown inside the tested code. Example 6.1 shows how to subclass PHPUnit2_Extensions_ExceptionTestCase and use its setExpectedException() method to set the expected exception. If this expected exception is not thrown, the test will be counted as a failure.

<?php
require_once 'PHPUnit2/Extensions/ExceptionTestCase.php';
 
class ExceptionTest extends PHPUnit2_Extensions_ExceptionTestCase {
    public function testException() {
        $this->setExpectedException('Exception');
    }
}
?>

phpunit ExceptionTest
PHPUnit 2.3.0 by Sebastian Bergmann.

F

Time: 0.006798
There was 1 failure:
1) testException(ExceptionTest)
Expected exception Exception

FAILURES!!!
Tests run: 1, Failures: 1, Errors: 0, Incomplete Tests: 0.

Table 6.1 shows the external protocol implemented by PHPUnit2_Extensions_ExceptionTestCase.

You can extend your test class from PHPUnit2_Extensions_PerformanceTestCase to test whether the execution of a function or method call, for instance, exceeds a specified time limit.

Example 6.2 shows how to subclass PHPUnit2_Extensions_PerformanceTestCase and use its setMaxRunningTime() method to set the maximum running time for the test. If the test is not executed within this time limit, it will be counted as a failure.

<?php
require_once 'PHPUnit2/Extensions/PerformanceTestCase.php';
 
class PerformanceTest extends PHPUnit2_Extensions_PerformanceTestCase {
    public function testPerformance() {
        $this->setMaxRunningTime(2);
        sleep(1);
    }
}
?>

Table 6.2 shows the external protocol implemented by PHPUnit2_Extensions_PerformanceTestCase.

In this chapter, we will look at the example of a class that represents a bank account. The contract for the BankAccount class not only requires methods to get and set the bank account's balance, as well as methods to deposit and withdraw money. It also specifies the following two conditions that must be ensured:

Following the Test-First Programming approach, we write the tests for the BankAccount class before we write the code for the class itself. We use the contract conditions as the basis for the tests and name the test methods accordingly, as shown in Example 8.1.

<?php
require_once 'PHPUnit2/Framework/TestCase.php';
require_once 'BankAccount.php';
 
class BankAccountTest extends PHPUnit2_Framework_TestCase {
    private $ba;
 
    protected function setUp() {
        $this->ba = new BankAccount;
    }
 
    public function testBalanceIsInitiallyZero() {
        $this->assertEquals(0, $this->ba->getBalance());
    }
 
    public function testBalanceCannotBecomeNegative() {
        try {
            $this->ba->withdrawMoney(1);
        }
 
        catch (Exception $e) {
            return;
        }
 
        $this->fail();
    }
 
    public function testBalanceCannotBecomeNegative2() {
        try {
            $this->ba->depositMoney(-1);
        }
 
        catch (Exception $e) {
            return;
        }
 
        $this->fail();
    }
 
    public function testBalanceCannotBecomeNegative3() {
        try {
            $this->ba->setBalance(-1);
        }
 
        catch (Exception $e) {
            return;
        }
 
        $this->fail();
    }
}
?>

We now write the minimal amount of code needed for the first test, testBalanceIsInitiallyZero(), to pass. In our example this amounts to implementing the getBalance() method of the BankAccount class, as shown in Example 8.2.

<?php
class BankAccount {
    private $balance = 0;
 
    public function getBalance() {
        return $this->balance;
    }
}
?>

The test for the first contract condition now passes, but the tests for the second contract condition fail because we have yet to implement the methods that these tests call.

phpunit BankAccountTest
PHPUnit 2.3.0 by Sebastian Bergmann.

.
Fatal error: Call to undefined method BankAccount::withdrawMoney()

For the tests that ensure the second contract condition to pass, we now need to implement the withdrawMoney(), depositMoney(), and setBalance() methods, as shown in Example 8.3. These methods are written in a such a way that they raise an InvalidArgumentException when they are called with illegal values that would violate the contract conditions.

<?php
class BankAccount {
    private $balance = 0;
 
    public function getBalance() {
        return $this->balance;
    }
 
    public function setBalance($balance) {
        if ($balance >= 0) {
            $this->balance = $balance;
        } else {
            throw new InvalidArgumentException;
        }
    }
 
    public function depositMoney($amount) {
        if ($amount >= 0) {
            $this->balance += $amount;
        } else {
            throw new InvalidArgumentException;
        }
    }
 
    public function withdrawMoney($amount) {
        if ($amount >= 0 && $this->balance >= $amount) {
            $this->balance -= $amount;
        } else {
            throw new InvalidArgumentException;
        }
    }
}
?>

The tests that ensure the second contract condition now pass, too:

phpunit BankAccountTest
PHPUnit 2.3.0 by Sebastian Bergmann.

....

Time: 0.057038

OK (4 tests)

Alternatively, you can use the static assertion methods provided by the PHPUnit2_Framework_Assert class to write the contract conditions as design-by-contract style assertions into your code, as shown in Example 8.4. When one of these assertions fails, an PHPUnit2_Framework_AssertionFailedError exception will be raised. With this approach, you write less code for the contract condition checks and the tests become more readable. However, you add a runtime dependency on PHPUnit to your project.

<?php
require_once 'PHPUnit2/Framework/Assert.php';
 
class BankAccount {
    private $balance = 0;
 
    public function getBalance() {
        return $this->balance;
    }
 
    public function setBalance($balance) {
        PHPUnit2_Framework_Assert::assertTrue($balance >= 0);
 
        $this->balance = $balance;
    }
 
    public function depositMoney($amount) {
        PHPUnit2_Framework_Assert::assertTrue($amount >= 0);
 
        $this->balance += $amount;
    }
 
    public function withdrawMoney($amount) {
        PHPUnit2_Framework_Assert::assertTrue($amount >= 0);
        PHPUnit2_Framework_Assert::assertTrue($this->balance >= $amount);
 
        $this->balance -= $amount;
    }
}
?>

By writing the contract conditions into the tests, we have used Design-by-Contract to program the BankAccount class. We then wrote, following the Test-First Programming approach, the code needed to make the tests pass. However, we forgot to write tests that call setBalance(), depositMoney(), and withdrawMoney() with legal values that do not violate the contract conditions. We need a means to test our tests or at least to measure their quality. Such a means is the analysis of code-coverage information that we will discuss next.

Sometimes you need to check that an object has been called correctly. You can create a complete stub of the object to be called, but that can make it inconvenient to check for correct results. A simpler solution is to apply the Self Shunt Pattern and use the test-case object itself as a stub. The term self-shunting is taken from the medical practice of installing a tube that takes blood from an artery and returns it to a vein to provide a convenient place for injecting drugs.

Here is an example: suppose we want to test that the correct method is called on an object that observes another object. First, we make our test-case class an implementor of Observer:

class ObserverTest extends PHPUnit2_Framework_TestCase implements Observer {
}

Next, we implement the one Observer method, update(), to check that it is called when the state of the observed Subject object changes:

public $wasCalled = FALSE;

public function update(Subject $subject) {
    $this->wasCalled = TRUE;
}

Now, we can write our test. We create a new Subject object and attach the test object to it as an observer. When the state of the Subject changes -- for instance, by calling its doSomething() method -- the Subject object has to call the update() method on all objects that are registered as observers. We use the $wasCalled instance variable that is set by our implementation of update() to check whether the Subject object does what it is supposed to do:

public function testUpdate() {
    $subject = new Subject;
    $subject->attach($this);
    $subject->doSomething();

    $this->assertTrue($this->wasCalled);
}

Notice that we create a new Subject object instead of relying on a global instance. Stubbing encourages this style of design. It reduces the coupling between objects and improves reuse.

If you are not familiar with the self-shunt pattern, the tests can be hard to read. What is going on here? Why is a test case also an observer? Once you get used to the idiom, the tests are easy to read. Everything you need to understand the test is in one class.

Typically, in a project that is developed using an agile process, such as Extreme Programming, the documentation cannot keep up with the frequent changes to the project's design and code. Extreme Programming demands collective code ownership, so all developers need to know how the entire system works. If you are disciplined enough to consequently use "speaking names" for your tests that describe what a class should do, you can use PHPUnit's TestDox functionality to generate automated documentation for your project based on its tests. This documentation gives developers an overview of what each class of the project is supposed to do.

PHPUnit's TestDox functionality looks at a test class and all the test method names and converts them from camel case PHP names to sentences: testBalanceIsInitiallyZero() becomes "Balance is initially zero". If there are several test methods whose names only differ in a suffix of one or more digits, such as testBalanceCannotBecomeNegative() and testBalanceCannotBecomeNegative2(), the sentence "Balance cannot become negative" will appear only once, assuming that all of these tests succeed.

The following code shows the agile documentation for the BankAccount class (from Example 8.1) generated by running phpunit --testdox-text BankAccountTest.txt BankAccountTest:

BankAccount
 - Balance is initially zero
 - Balance cannot become negative

Alternatively, the agile documentation can be generated in HTML format by using --testdox-html BankAccountTest.htm.

Agile Documentation can be used to document the assumptions you make about the external packages that you use in your project. When you use an external package, you are exposed to the risks that the package will not behave as you expect, and that future versions of the package will change in subtle ways that will break your code, without you knowing it. You can address these risks by writing a test every time you make an assumption. If your test succeeds, your assumption is valid. If you document all your assumptions with tests, future releases of the external package will be no cause for concern: if the tests succeed, your system should continue working.

When you document assumptions with tests, you own the tests. The supplier of the package -- who you make assumptions about -- knows nothing about your tests. If you want to have a closer relationship with the supplier of a package, you can use the tests to communicate and coordinate your activities.

When you agree on coordinating your activities with the supplier of a package, you can write the tests together. Do this in such a way that the tests reveal as many assumptions as possible. Hidden assumptions are the death of cooperation. With the tests, you document exactly what you expect from the supplied package. The supplier will know the package is complete when all the tests run.

By using stubs (see the section "Stubs", earlier in this book), you can further decouple yourself from the supplier: The job of the supplier is to make the tests run with the real implementation of the package. Your job is to make the tests run for your own code. Until such time as you have the real implementation of the supplied package, you use stub objects. Following this approach, the two teams can develop independently.

When you get a defect report, your impulse might be to fix the defect as quickly as possible. Experience shows that this impulse will not serve you well; it is likely that the fix for the defect causes another defect.

You can hold your impulse in check by doing the following:

Finding the smallest reliable reproduction of the defect gives you the opportunity to really examine the cause of the defect. The test you write will improve the chances that when you fix the defect, you really fix it, because the new test reduces the likelihood of undoing the fix with future code changes. All the tests you wrote before reduce the likelihood of inadvertently causing a different problem.

Refactoring, the controlled technique for improving the design of an existing code base, can be applied safely only when you have a test suite. Otherwise, you might not notice the system breaking while you are carrying out the restructuring. Refactoring can be broken down into a series of small behavior-preserving transformations.

The following conditions will help you to improve the code and design of your project, while using unit tests to verify that the refactoring's transformation steps are, indeed, behavior-preserving and do not introduce errors:

Besides the required <batchtest> element, the <phpunit2> element allows for another nested element: <formatter> is used to write test results in different formats. Output will always be sent to a file, unless you set the usefile attribute to false. The name of the file is predetermined by the formatter and can be changed by the outfile attribute. There are three predefined formatters:

Table 12.2 shows the parameters that can be used to configure the <formatter> task.

To generate a test report in HTML format, you can use the <phpunit2report> task, which applies an XSLT stylesheet to the XML logfile created by the <formatter> task. Phing ships with two XSLT stylesheets -- phpunit2-frames.xsl and phpunit2-noframes.xsl -- that generate HTML reports with or without frames, respectively.

Example 12.2 shows a build.xml file for Phing that runs the tests from the BankAccountTest class and generates a test report in HTML format using the phpunit2-frames.xsl XSLT stylesheet. The HTML files generated for the report will be written to the report/ directory that is created by the prepare <target> and deleted by the clean <target>.

<?xml version="1.0"?>

<project name="BankAccount" basedir="." default="report">
  <target name="prepare">
    <mkdir dir="report"/>
  </target>

  <target name="clean"> 
    <delete dir="report"/>
  </target>

  <target name="report" depends="prepare">
    <phpunit2>
      <batchtest>
        <fileset dir=".">
          <include name="*Test.php"/>
        </fileset>
      </batchtest>

      <formatter type="xml" todir="report" outfile="logfile.xml"/>
    </phpunit2>

    <phpunit2report infile="report/logfile.xml"
                    styledir="/usr/lib/php/data/phing/etc"
                    format="frames"
                    todir="report"/>
  </target>
</project>

The following example shows the output of the phing command as it runs:

phing
Buildfile: /home/sb/build.xml

BankAccount > prepare:
    [mkdir] Created dir: /home/sb/report

BankAccount > report:

BUILD FINISHED

Total time: 0.1112 seconds

Figure 12.1 shows the title page of the generated test report.

Figure 12.1. The generated test report

Table 12.3 shows the parameters that can be used to configure the <phpunit2report> task.

In addition to the test report that we just generated, Phing can generate a code-coverage report. For this, we need the <coverage-setup> and <coverage-report> tasks. The former prepares a database in which code-coverage information is stored while the tests are run; the latter formats such a database into a report in HTML format using XSLT stylesheets.

Example 12.3 shows a build.xml file for Phing that runs the tests from the BankAccountTest class and generates a code-coverage report in HTML format.

<?xml version="1.0"?>

<project name="BankAccount" basedir="." default="coverage-report">
  <target name="prepare">
    <mkdir dir="coverage-report"/>
  </target>

  <target name="clean"> 
    <delete dir="coverage-report"/>
  </target>

  <target name="coverage-report" depends="prepare">
    <coverage-setup database="./coverage-report/database">
      <fileset dir=".">
        <include name="*.php"/>
        <exclude name="*Test.php"/>
      </fileset>
    </coverage-setup>

    <phpunit2 codecoverage="true">
      <batchtest>
        <fileset dir=".">
          <include name="*Test.php"/>
        </fileset>
      </batchtest>
    </phpunit2>

    <coverage-report outfile="coverage-report/coverage.xml">
      <report styledir="/usr/lib/php/data/phing/etc"
              todir="coverage-report"/>
    </coverage-report>
  </target>
</project>

Figure 12.2 shows the title page of the generated code-coverage report.

Figure 12.2. The generated code-coverage report

Most of the time, you will encounter five classes or interfaces when you are using PHPUnit:

Figure 14.1 shows the relationship of the five basic classes and interfaces in PHPUnit: PHPUnit2_Framework_Assert, PHPUnit2_Framework_Test, PHPUnit2_Framework_TestCase, PHPUnit2_Framework_TestSuite, and PHPUnit2_Framework_TestResult.

Figure 14.1. The five basic classes and interfaces in PHPUnit

Most test cases written for PHPUnit are derived indirectly from the class PHPUnit2_Framework_Assert, which contains methods for automatically checking values and reporting discrepancies. The methods are declared static, so you can write design-by-contract style assertions in your methods and have them reported through PHPUnit (Example 14.1).

<?php
require_once 'PHPUnit2/Framework/Assert.php';
 
class Sample {
    public function aSampleMethod($object) {
        PHPUnit2_Framework_Assert::assertNotNull($object);
    }
}
 
$sample = new Sample;
$sample->aSampleMethod(NULL);
?>

Fatal error: Uncaught exception 'PHPUnit2_Framework_AssertionFailedError'
with message 'expected: <NOT NULL> but was: <NULL>'

Most of the time, though, you'll be checking the assertions inside of tests.

There are two variants of each of the assertion methods: one takes a message to be displayed with the error as a parameter, and one does not. The optional message is typically displayed when a failure is displayed, which can make debugging easier.

<?php
require_once 'PHPUnit2/Framework/TestCase.php';
 
class MessageTest extends PHPUnit2_Framework_TestCase {
    public function testMessage() {
        $this->assertTrue(FALSE, 'This is a custom message.');
    }
}
?>

The following example shows the output you get when you run the testMessage() test from Example 14.2, using assertions with messages:

phpunit MessageTest.php
PHPUnit 2.3.0 by Sebastian Bergmann.

F

Time: 0.102507
There was 1 failure:
1) testMessage(MessageTest)
This is a custom message.

FAILURES!!!
Tests run: 1, Failures: 1, Errors: 0, Incomplete Tests: 0.

Table 14.1 shows all the varieties of assertions.

You may find that you need other assertions than these to compare objects specific to your project. Create your own Assert class to contain these assertions to simplify your tests.

Failing assertions all call a single bottleneck method, fail(string $message), which throws an PHPUnit2_Framework_AssertionFailedError. There is also a variant which takes no parameters. Call fail() explicitly when your test encounters an error. The test for an expected exception is an example. Table 14.2 lists the bottlenext methods in PHPUnit.

PHPUnit2_Framework_Test is the generic interface used by all objects that can act as tests. Implementors may represent one or more tests. The two methods are shown in Table 14.3.

PHPUnit2_Framework_TestCase and PHPUnit2_Framework_TestSuite are the two most prominent implementors of PHPUnit2_Framework_Test. You can implement PHPUnit2_Framework_Test yourself. The interface is kept small intentionally so it will be easy to implement.

Your test-case classes will inherit from PHPUnit2_Framework_TestCase. Most of the time, you will run tests from automatically created test suites. In this case, each of your tests should be represented by a method named test* (by convention).

PHPUnit2_Framework_TestCase implements PHPUnit2_Framework_Test::countTestCases() so that it always returns 1. The implementation of PHPUnit2_Framework_Test::run(PHPUnit2_Framework_TestResult $result) in this class runs setUp(), runs the test method, and then runs tearDown(), reporting any exceptions to the PHPUnit2_Framework_TestResult.

Table 14.4 shows the external protocol implemented by PHPUnit2_Framework_TestCase.

There are two template methods -- setUp() and tearDown() -- you can override to create and dispose of the objects against which you are going to test. Table 14.5 shows these methods.

A PHPUnit2_Framework_TestSuite is a composite of PHPUnit2_Framework_Tests. At its simplest, it contains a bunch of test cases, all of which are run when the suite is run. Since it is a composite, however, a suite can contain suites which can contain suites and so on, making it easy to combine tests from various sources and run them together.

In addition to the PHPUnit2_Framework_Test protocol -- run(PHPUnit2_Framework_TestResult $result) and countTestCases() -- PHPUnit2_Framework_TestSuite contains protocol to create named or unnamed instances. Table 14.6 shows the instance creation protocol for PHPUnit2_Framework_TestSuite.

PHPUnit2_Framework_TestSuite also contains protocol for adding and retrieving PHPUnit2_Framework_Tests, as shown in Table 14.7.

Example 14.3 shows how to create and run a test suite.

<?php
require_once 'PHPUnit2/Framework/TestSuite.php';
 
require_once 'ArrayTest.php';
 
// Create a test suite that contains the tests
// from the ArrayTest class.
$suite = new PHPUnit2_Framework_TestSuite('ArrayTest');
 
// Run the tests.
$suite->run();
?>

For an example on how to use PHPUnit2_Framework_TestSuite to hierarchically compose test cases let us look at PHPUnit's own test suite.

Example 14.4 shows a cut-down version of Tests/AllTests.php, Example 14.5 a cut-down version of Tests/Framework/AllTests.php.

<?php
if (!defined('PHPUnit2_MAIN_METHOD')) {
    define('PHPUnit2_MAIN_METHOD', 'AllTests::main');
}
 
require_once 'PHPUnit2/Framework/TestSuite.php';
require_once 'PHPUnit2/TextUI/TestRunner.php';
 
require_once 'Framework/AllTests.php';
// ...
 
class AllTests {
    public static function main() {
        PHPUnit2_TextUI_TestRunner::run(self::suite());
    }
 
    public static function suite() {
        $suite = new PHPUnit2_Framework_TestSuite('PHPUnit');
 
        $suite->addTest(Framework_AllTests::suite());
        // ...
 
        return $suite;
    }
}
 
if (PHPUnit2_MAIN_METHOD == 'AllTests::main') {
    AllTests::main();
}
?>

<?php
if (!defined('PHPUnit2_MAIN_METHOD')) {
    define('PHPUnit2_MAIN_METHOD', 'Framework_AllTests::main');
}
 
require_once 'PHPUnit2/Framework/TestSuite.php';
require_once 'PHPUnit2/TextUI/TestRunner.php';
 
require_once 'Framework/AssertTest.php';
// ...
 
class Framework_AllTests {
    public static function main() {
        PHPUnit2_TextUI_TestRunner::run(self::suite());
    }
 
    public static function suite() {
        $suite = new PHPUnit2_Framework_TestSuite('PHPUnit Framework');
 
        $suite->addTestSuite('Framework_AssertTest');
        // ...
 
        return $suite;
    }
}
 
if (PHPUnit2_MAIN_METHOD == 'Framework_AllTests::main') {
    Framework_AllTests::main();
}
?>

The Framework_AssertTest class is a standard test case that extends PHPUnit2_Framework_TestCase.

Running Tests/AllTests.php uses the TextUI test runner to run all tests while running Tests/Framework/AllTests.php runs only the tests for the PHPUnit2_Framework_* classes.

This example shows the PHPUnit test suite running:

php AllTests.php
PHPUnit 2.3.0 by Sebastian Bergmann.

.........................................
.........................................
.......

Time: 4.642600

OK (89 tests)

While you are running all these tests, you need somewhere to store all the results: how many tests ran, which failed, and how long they took. PHPUnit2_Framework_TestResult collects these results. A single PHPUnit2_Framework_TestResult is passed around the whole tree of tests; when a test runs or fails, the fact is noted in the PHPUnit2_Framework_TestResult. At the end of the run, PHPUnit2_Framework_TestResult contains a summary of all the tests.

PHPUnit2_Framework_TestResult is also a subject than can be observed by other objects wanting to report test progress. For example, a graphical test runner might observe the PHPUnit2_Framework_TestResult and update a progress bar every time a test starts.

Table 14.8 summarizes the external protocols of PHPUnit2_Framework_TestResult.

If you want to register as an observer of a PHPUnit2_Framework_TestResult, you need to implement PHPUnit2_Framework_TestListener. To register, call addListener(), as shown in Table 14.9.

Table 14.10 shows the methods that test listeners implement; also see Example 15.3.

Many of the classes mentioned so far in this book come from PHPUnit2/Framework. Here are all the packages in PHPUnit:

Write utility methods in an abstract subclass of PHPUnit2_Framework_TestCase and derive your test case classes from that class. This is one of the easiest ways to extend PHPUnit.

Write your own class with assertions special to your purpose.

You can wrap test cases or test suites in a subclass of PHPUnit2_Extensions_TestDecorator and use the Decorator design pattern to perform some actions before and after the test runs.

PHPUnit ships with two concrete test decorators: PHPUnit2_Extensions_RepeatedTest and PHPUnit2_Extensions_TestSetup. The former is used to run a test repeatedly and only count it as a success if all iterations are successful. The latter was discussed in Chapter 5.

Example 15.1 shows a cut-down version of the PHPUnit2_Extensions_RepeatedTest test decorator that illustrates how to write your own test decorators.

<?php
require_once 'PHPUnit2/Extensions/TestDecorator.php';
 
class PHPUnit2_Extensions_RepeatedTest extends PHPUnit2_Extensions_TestDecorator {
    private $timesRepeat = 1;
 
    public function __construct(PHPUnit2_Framework_Test $test, $timesRepeat = 1) {
        parent::__construct($test);
 
        if (is_integer($timesRepeat) &&
            $timesRepeat >= 0) {
            $this->timesRepeat = $timesRepeat;
        }
    }
 
    public function countTestCases() {
        return $this->timesRepeat * $this->test->countTestCases();
    }
 
    public function run($result = NULL) {
        if ($result === NULL) {
            $result = $this->createResult();
        }
 
        for ($i = 0; $i < $this->timesRepeat && !$result->shouldStop(); $i++) {
            $this->test->run($result);
        }
 
        return $result;
    }
}
?>

The PHPUnit2_Framework_Test interface is narrow and easy to implement. You can write an implementation of PHPUnit2_Framework_Test that is simpler than PHPUnit2_Framework_TestCase and that runs data-driven tests, for instance.

Example 15.2 shows a data-driven test-case class that compares values from a file with Comma-Separated Values (CSV). Each line of such a file looks like foo;bar, where the first value is the one we expect and the second value is the actual one.

<?php
require_once 'PHPUnit2/Framework/Assert.php';
require_once 'PHPUnit2/Framework/Test.php';
require_once 'PHPUnit2/Framework/TestResult.php';
 
class DataDrivenTest implements PHPUnit2_Framework_Test {
    private $lines;
 
    public function __construct($dataFile) {
        $this->lines = file($dataFile);
    }
 
    public function countTestCases() {
        return sizeof($this->lines);
    }
 
    public function run($result = NULL) {
        if ($result === NULL) {
            $result = new PHPUnit2_Framework_TestResult;
        }
 
        $result->startTest($this);
 
        foreach ($this->lines as $line) {
            list($expected, $actual) = explode(';', $line);
 
            try {
                PHPUnit2_Framework_Assert::assertEquals(trim($expected), trim($actual));
            }
 
            catch (PHPUnit2_Framework_ComparisonFailure $e) {
                $result->addFailure($this, $e);
            }
 
            catch (Exception $e) {
                $result->addError($this, $e);
            }
        }
 
        $result->endTest($this);
 
        return $result;
    }
}
 
$test   = new DataDrivenTest('data_file.csv');
$result = $test->run();
 
$failures = $result->failures();
print $failures[0]->thrownException()->toString();
?>

expected: <foo> but was: <bar>

By passing a special-purpose PHPUnit2_Framework_TestResult object to the run() method, you can change the way tests are run and what result data gets collected.

You do not necessarily need to write a whole subclass of PHPUnit2_Framework_TestResult in order to customize it. Most of the time, it will suffice to implement a new PHPUnit2_Framework_TestListener (see Table 14.10) and attach it to the PHPUnit2_Framework_TestResult object, before running the tests.

Example 15.3 shows a simple implementation of the PHPUnit2_Framework_TestListener interface.

<?php
require_once 'PHPUnit2/Framework/TestListener.php';
 
class SimpleTestListener
implements PHPUnit2_Framework_TestListener {
  public function
  addError(PHPUnit2_Framework_Test $test, Exception $e) {
    printf(
      "Error while running test '%s'.\n",
      $test->getName()
    );
  }
 
  public function
  addFailure(PHPUnit2_Framework_Test $test,
             PHPUnit2_Framework_AssertionFailedError $e) {
    printf(
      "Test '%s' failed.\n",
      $test->getName()
    );
  }
 
  public function
  addIncompleteTest(PHPUnit2_Framework_Test $test,
                    Exception $e) {
    printf(
      "Test '%s' is incomplete.\n",
      $test->getName()
    );
  }
 
  public function startTest(PHPUnit2_Framework_Test $test) {
    printf(
      "Test '%s' started.\n",
      $test->getName()
    );
  }
 
  public function endTest(PHPUnit2_Framework_Test $test) {
    printf(
      "Test '%s' ended.\n",
      $test->getName()
    );
  }
 
  public function
  startTestSuite(PHPUnit2_Framework_TestSuite $suite) {
    printf(
      "TestSuite '%s' started.\n",
      $suite->getName()
    );
  }
 
  public function
  endTestSuite(PHPUnit2_Framework_TestSuite $suite) {
    printf(
      "TestSuite '%s' ended.\n",
      $suite->getName()
    );
  }
}
?>

Example 15.4 shows how to run and observe a test suite.

<?php
require_once 'PHPUnit2/Framework/TestResult.php';
require_once 'PHPUnit2/Framework/TestSuite.php';
 
require_once 'ArrayTest.php';
require_once 'SimpleTestListener.php';
 
// Create a test suite that contains the tests
// from the ArrayTest class.
$suite = new PHPUnit2_Framework_TestSuite('ArrayTest');
 
// Create a test result and attach a SimpleTestListener
// object as an observer to it.
$result = new PHPUnit2_Framework_TestResult;
$result->addListener(new SimpleTestListener);
 
// Run the tests.
$suite->run($result);
?>

TestSuite 'ArrayTest' started.
Test 'testNewArrayIsEmpty' started.
Test 'testNewArrayIsEmpty' ended.
Test 'testArrayContainsAnElement' started.
Test 'testArrayContainsAnElement' ended.
TestSuite 'ArrayTest' ended.

If you need different feedback from the test execution, write your own test runner, interactive or not. The abstract PHPUnit2_Runner_BaseTestRunner class, which the PHPUnit2_TextUI_TestRunner class (the PHPUnit command-line test runner) inherits from, can be a starting point for this.