Chapter 7. Incomplete Tests

When you are working on a new test-case class, you might want to begin by writing empty test methods such as:

public function testSomething() {
}

to keep track of the tests that you have to write. The problem with empty test methods is that they are interpreted as a success by the PHPUnit framework. This misinterpretation leads to the test reports being useless -- you cannot see whether a test is actually successful or just not yet implemented. Calling $this->fail() in the unimplemented test method does not help either, since then the test will be interpreted as a failure. This would be just as wrong as interpreting an unimplemented test as a success.

If we think of a successful test as a green light and a test failure as a red light, we need an additional yellow light to mark a test as being incomplete or not yet implemented. PHPUnit2_Framework_IncompleteTest is a marker interface for marking an exception that is raised by a test method as the result of the test being incomplete or currently not implemented. PHPUnit2_Framework_IncompleteTestError is the standard implementation of this interface.

Example 7.1 shows a test-case class, SampleTest, that contains one test method, testSomething(). By raising the PHPUnit2_Framework_IncompleteTestError exception in the test method, we mark the test as being incomplete.

Example 7.1: Marking a test as incomplete

<?php
require_once 'PHPUnit2/Framework/TestCase.php';
require_once 'PHPUnit2/Framework/IncompleteTestError.php';
 
class SampleTest extends PHPUnit2_Framework_TestCase {
    public function testSomething() {
        // Optional: Test anything here, if you want.
        $this->assertTrue(TRUE, 'This should already work.');
 
        // Stop here and mark this test as incomplete.
        // You could use any Exception which implements the
        // PHPUnit2_Framework_IncompleteTest interface.
        throw new PHPUnit2_Framework_IncompleteTestError(
          'This test has not been implemented yet.'
        );
    }
}
?>

An incomplete test is denoted by an I in the output of the PHPUnit command-line test runner, as shown in the following example:

phpunit SampleTest
PHPUnit 2.3.0 by Sebastian Bergmann.

I

Time: 0.006657
There was 1 incomplete test case:
1) testSomething(SampleTest)
This test has not been implemented yet.

OK, but incomplete test cases!!!
Tests run: 1, incomplete test cases: 1.