1. Installing PHPUnit
PHP Archive (PHAR)
Verifying PHPUnit PHAR Releases
Optional packages
2. Writing Tests for PHPUnit
Test Dependencies
Data Providers
Testing Exceptions
Testing PHP Errors
Testing Output
Error output
Edge cases
3. The Command-Line Test Runner
Command-Line Options
4. Fixtures
More setUp() than tearDown()
Sharing Fixture
Global State
5. Organizing Tests
Composing a Test Suite Using the Filesystem
Composing a Test Suite Using XML Configuration
6. Risky Tests
Useless Tests
Unintentionally Covered Code
Output During Test Execution
Test Execution Timeout
Global State Manipulation
7. Incomplete and Skipped Tests
Incomplete Tests
Skipping Tests
Skipping Tests using @requires
8. Database Testing
Supported Vendors for Database Testing
Difficulties in Database Testing
The four stages of a database test
1. Clean-Up Database
2. Set up fixture
3–5. Run Test, Verify outcome and Teardown
Configuration of a PHPUnit Database TestCase
Implementing getConnection()
Implementing getDataSet()
What about the Database Schema (DDL)?
Tip: Use your own Abstract Database TestCase
Understanding DataSets and DataTables
Available Implementations
Beware of Foreign Keys
Implementing your own DataSets/DataTables
The Connection API
Database Assertions API
Asserting the Row-Count of a Table
Asserting the State of a Table
Asserting the Result of a Query
Asserting the State of Multiple Tables
Frequently Asked Questions
Will PHPUnit (re-)create the database schema for each test?
Am I required to use PDO in my application for the Database Extension to work?
What can I do, when I get a Too much Connections Error?
How to handle NULL with Flat XML / CSV Datasets?
9. Test Doubles
Mock Objects
Mocking Traits and Abstract Classes
Stubbing and Mocking Web Services
Mocking the Filesystem
10. Testing Practices
During Development
During Debugging
11. Code Coverage Analysis
Software Metrics for Code Coverage
Whitelisting Files
Ignoring Code Blocks
Specifying Covered Methods
Edge Cases
12. Other Uses for Tests
Agile Documentation
Cross-Team Tests
13. Logging
Test Results (XML)
Test Results (TAP)
Test Results (JSON)
Code Coverage (XML)
Code Coverage (TEXT)
14. Extending PHPUnit
Subclass PHPUnit_Framework_TestCase
Write custom assertions
Implement PHPUnit_Framework_TestListener
Subclass PHPUnit_Extensions_TestDecorator
Implement PHPUnit_Framework_Test
A. Assertions
B. Annotations
C. The XML Configuration File
Test Suites
Whitelisting Files for Code Coverage
Test Listeners
Setting PHP INI settings, Constants and Global Variables
Configuring Browsers for Selenium RC
D. Index
E. Bibliography
F. Copyright

Chapter 14. Extending PHPUnit

PHPUnit can be extended in various ways to make the writing of tests easier and customize the feedback you get from running tests. Here are common starting points to extend PHPUnit.

Subclass PHPUnit_Framework_TestCase

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

Write custom assertions

When writing custom assertions it is the best practice to follow how PHPUnit's own assertions are implemented. As you can see in Example 14.1, the assertTrue() method is just a wrapper around the isTrue() and assertThat() methods: isTrue() creates a matcher object that is passed on to assertThat() for evaluation.

Example 14.1: The assertTrue() and isTrue() methods of the PHPUnit_Framework_Assert class

abstract class PHPUnit_Framework_Assert
    // ...

     * Asserts that a condition is true.
     * @param  boolean $condition
     * @param  string  $message
     * @throws PHPUnit_Framework_AssertionFailedError
    public static function assertTrue($condition, $message = '')
        self::assertThat($condition, self::isTrue(), $message);

    // ...

     * Returns a PHPUnit_Framework_Constraint_IsTrue matcher object.
     * @return PHPUnit_Framework_Constraint_IsTrue
     * @since  Method available since Release 3.3.0
    public static function isTrue()
        return new PHPUnit_Framework_Constraint_IsTrue;

    // ...

Example 14.2 shows how PHPUnit_Framework_Constraint_IsTrue extends the abstract base class for matcher objects (or constraints), PHPUnit_Framework_Constraint.

Example 14.2: The PHPUnit_Framework_Constraint_IsTrue class

class PHPUnit_Framework_Constraint_IsTrue extends PHPUnit_Framework_Constraint
     * Evaluates the constraint for parameter $other. Returns TRUE if the
     * constraint is met, FALSE otherwise.
     * @param mixed $other Value or object to evaluate.
     * @return bool
    public function matches($other)
        return $other === TRUE;

     * Returns a string representation of the constraint.
     * @return string
    public function toString()
        return 'is true';

The effort of implementing the assertTrue() and isTrue() methods as well as the PHPUnit_Framework_Constraint_IsTrue class yields the benefit that assertThat() automatically takes care of evaluating the assertion and bookkeeping tasks such as counting it for statistics. Furthermore, the isTrue() method can be used as a matcher when configuring mock objects.

Implement PHPUnit_Framework_TestListener

Example 14.3 shows a simple implementation of the PHPUnit_Framework_TestListener interface.

Example 14.3: A simple test listener

class SimpleTestListener implements PHPUnit_Framework_TestListener
    public function addError(PHPUnit_Framework_Test $test, Exception $e, $time)
        printf("Error while running test '%s'.\n", $test->getName());

    public function addFailure(PHPUnit_Framework_Test $test, PHPUnit_Framework_AssertionFailedError $e, $time)
        printf("Test '%s' failed.\n", $test->getName());

    public function addIncompleteTest(PHPUnit_Framework_Test $test, Exception $e, $time)
        printf("Test '%s' is incomplete.\n", $test->getName());

    public function addRiskyTest(PHPUnit_Framework_Test $test, Exception $e, $time)
        printf("Test '%s' is deemed risky.\n", $test->getName());

    public function addSkippedTest(PHPUnit_Framework_Test $test, Exception $e, $time)
        printf("Test '%s' has been skipped.\n", $test->getName());

    public function startTest(PHPUnit_Framework_Test $test)
        printf("Test '%s' started.\n", $test->getName());

    public function endTest(PHPUnit_Framework_Test $test, $time)
        printf("Test '%s' ended.\n", $test->getName());

    public function startTestSuite(PHPUnit_Framework_TestSuite $suite)
        printf("TestSuite '%s' started.\n", $suite->getName());

    public function endTestSuite(PHPUnit_Framework_TestSuite $suite)
        printf("TestSuite '%s' ended.\n", $suite->getName());

Example 14.4 shows how to subclass the PHPUnit_Framework_BaseTestListener abstract class, which lets you specify only the interface methods that are interesting for your use case, while providing empty implementations for all the others.

Example 14.4: Using base test listener

class ShortTestListener extends PHPUnit_Framework_BaseTestListener
    public function endTest(PHPUnit_Framework_Test $test, $time)
        printf("Test '%s' ended.\n", $test->getName());

In the section called “Test Listeners” you can see how to configure PHPUnit to attach your test listener to the test execution.

Subclass PHPUnit_Extensions_TestDecorator

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

PHPUnit ships with one concrete test decorator: PHPUnit_Extensions_RepeatedTest. It is used to run a test repeatedly and only count it as a success if all iterations are successful.

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

Example 14.5: The RepeatedTest Decorator

require_once 'PHPUnit/Extensions/TestDecorator.php';

class PHPUnit_Extensions_RepeatedTest extends PHPUnit_Extensions_TestDecorator
    private $timesRepeat = 1;

    public function __construct(PHPUnit_Framework_Test $test, $timesRepeat = 1)

        if (is_integer($timesRepeat) &&
            $timesRepeat >= 0) {
            $this->timesRepeat = $timesRepeat;

    public function count()
        return $this->timesRepeat * $this->test->count();

    public function run(PHPUnit_Framework_TestResult $result = NULL)
        if ($result === NULL) {
            $result = $this->createResult();

        for ($i = 0; $i < $this->timesRepeat && !$result->shouldStop(); $i++) {

        return $result;

Implement PHPUnit_Framework_Test

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

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

Example 14.6: A data-driven test

class DataDrivenTest implements PHPUnit_Framework_Test
    private $lines;

    public function __construct($dataFile)
        $this->lines = file($dataFile);

    public function count()
        return 1;

    public function run(PHPUnit_Framework_TestResult $result = NULL)
        if ($result === NULL) {
            $result = new PHPUnit_Framework_TestResult;

        foreach ($this->lines as $line) {
            $stopTime = NULL;

            list($expected, $actual) = explode(';', $line);

            try {
                  trim($expected), trim($actual)

            catch (PHPUnit_Framework_AssertionFailedError $e) {
                $stopTime = PHP_Timer::stop();
                $result->addFailure($this, $e, $stopTime);

            catch (Exception $e) {
                $stopTime = PHP_Timer::stop();
                $result->addError($this, $e, $stopTime);

            if ($stopTime === NULL) {
                $stopTime = PHP_Timer::stop();

            $result->endTest($this, $stopTime);

        return $result;

$test = new DataDrivenTest('data_file.csv');
$result = PHPUnit_TextUI_TestRunner::run($test);
PHPUnit 5.2.0 by Sebastian Bergmann and contributors.


Time: 0 seconds

There was 1 failure:

1) DataDrivenTest
Failed asserting that two strings are equal.
expected string <bar>
difference      <  x>
got string      <baz>

Tests: 2, Failures: 1.