Chapter8.TestCase Extensions

PHPUnit provides extensions to the standard base-class for test classes, PHPUnit_Framework_TestCase, that aid in the writing of tests for exceptions, output, and performance regressions.

Testing Exceptions

You can extend your test class from PHPUnit_Extensions_ExceptionTestCase to test whether an exception is thrown inside the tested code. Example 8.1 shows how to subclass PHPUnit_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.

Example 8.1: Using PHPUnit_Extensions_ExceptionTestCase

<?php
require_once 'PHPUnit/Extensions/ExceptionTestCase.php';
 
class ExceptionTest extends PHPUnit_Extensions_ExceptionTestCase
{
    public function testException()
    {
        $this->setExpectedException('Exception');
    }
}
?>
phpunit ExceptionTest
PHPUnit 3.1.0 by Sebastian Bergmann.

F

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

FAILURES!
Tests: 1, Failures: 1.


Table 8.1 shows the methods provided by PHPUnit_Extensions_ExceptionTestCase.

Table8.1.ExceptionTestCase

MethodMeaning
void setExpectedException(string $exceptionName)Set the name of the expected exception to $exceptionName.
String getExpectedException()Return the name of the expected exception.


Alternatively, you can use the approach shown in Example 8.2 to test exceptions.

Example 8.2: Alternative approach to testing exceptions

<?php
require_once 'PHPUnit/Framework.php';
 
class ExceptionTest extends PHPUnit_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 in Example 8.2 does not raise the expected exception, the subsequent call to fail() (see Table 21.3) 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.

Testing Output

Sometimes you want to assert that the executation of a method, for instance, generates an expected output (via echo or print, for example). The PHPUnit_Extensions_OutputTestCase class uses PHP's Output Buffering feature to provide the functionality that is necessary for this.

Example 8.3 shows how to subclass PHPUnit_Extensions_OutputTestCase and use its expectOutputString() method to set the expected output. If this expected output is not generated, the test will be counted as a failure.

Example 8.3: Using PHPUnit_Extensions_OutputTestCase

<?php
require_once 'PHPUnit/Extensions/OutputTestCase.php';
 
class OutputTest extends PHPUnit_Extensions_OutputTestCase
{
    public function testExpectFooActualFoo()
    {
        $this->expectOutputString('foo');
        print 'foo';
    }
 
    public function testExpectFooActualBar()
    {
        $this->expectOutputString('foo');
        print 'bar';
    }
}
?>
phpunit OutputTest
PHPUnit 3.1.0 by Sebastian Bergmann.

.F

Time: 00:00

There was 1 failure:

1) testExpectFooActualBar(OutputTest)
Failed asserting that <string:bar> is equal to <string:foo>.

FAILURES!
Tests: 2, Failures: 1.


Table 8.2 shows the methods provided by PHPUnit_Extensions_OutputTestCase.

Table8.2.OutputTestCase

MethodMeaning
void expectOutputRegex(string $regularExpression)Set up the expectation that the output matches a $regularExpression.
void expectOutputString(string $expectedString)Set up the expectation that the output is equal to an $expectedString.


Testing Performance

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

Example 8.4 shows how to subclass PHPUnit_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.

Example 8.4: Using PHPUnit_Extensions_PerformanceTestCase

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


Table 8.3 shows the methods provided by PHPUnit_Extensions_PerformanceTestCase.

Table8.3.PerformanceTestCase

MethodMeaning
void setMaxRunningTime(int $maxRunningTime)Set the maximum running time for the test to $maxRunningTime (in seconds).
integer getMaxRunningTime()Return the maximum running time allowed for the test.