Chapter 8. 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 uselessyou 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 because 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 not currently implemented. PHPUnit2_Framework_IncompleteTestError is the standard implementation of this interface.

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