PHP Unit Test documentation

Unit test cases

The core system is a regression testing framework built around test cases. A sample test case looks like this...

class FileTestCase extends UnitTestCase {
}

For example...

require_once('simpletest/autorun.php');
require_once('../classes/writer.php');

class FileTestCase extends UnitTestCase {
    function FileTestCase() {
        $this->UnitTestCase('File test');
    }
    
    function setUp() {
        @unlink('../temp/test.txt');
    }
    
    function tearDown() {
        @unlink('../temp/test.txt');
    }
    
    function testCreation() {
        $writer = &new FileWriter('../temp/test.txt');
        $writer->write('Hello');
        $this->assertTrue(file_exists('../temp/test.txt'), 'File created');
    }
}

Our only test method at the moment is testCreation() where we check that a file has been created by our Writer object. We could have put the unlink() code into this method as well, but by placing it in setUp() and tearDown() we can use it with other test methods that we add.

The setUp() method is run just before each and every test method. tearDown() is run just after each and every test method.

You can place some test case set up into the constructor to be run once for all the methods in the test case, but you risk test inteference that way. This way is slightly slower, but it is safer. Note that if you come from a JUnit background this will not be the behaviour you are used to. JUnit surprisingly reinstantiates the test case for each test method to prevent such interference. SimpleTest requires the end user to use setUp(), but supplies additional hooks for library writers.

The means of reporting test results (see below) are by a visiting display class that is notified by various assert...() methods. Here is the full list for the UnitTestCase class, the default for SimpleTest...

Some examples...

$variable = null;
$this->assertNull($variable, 'Should be cleared');

Extending test cases

Of course additional test methods can be added to create specific types of test case, so as to extend framework...

require_once('simpletest/autorun.php');

class FileTester extends UnitTestCase {
    function FileTester($name = false) {
        $this->UnitTestCase($name);
    }
    
    function assertFileExists($filename, $message = '%s') {
        $this->assertTrue(
                file_exists($filename),
                sprintf($message, 'File [$filename] existence check'));
    }
}

To prevent this test case being run accidently, it is advisable to mark it as abstract.

Alternatively you could add a SimpleTestOptions::ignore('FileTester'); directive in your code.

This new case can be now be inherited just like a normal test case...

class FileTestCase extends FileTester {
    
    function setUp() {
        @unlink('../temp/test.txt');
    }
    
    function tearDown() {
        @unlink('../temp/test.txt');
    }
    
    function testCreation() {
        $writer = &new FileWriter('../temp/test.txt');
        $writer->write('Hello');
        $this->assertFileExists('../temp/test.txt');
    }
}

Running a single test case

You won't often run single test cases except when bashing away at a module that is having difficulty, and you don't want to upset the main test suite. With autorun no particular scaffolding is needed, just launch your particular test file and you're ready to go.

You can even decide which reporter (for example, TextReporter or HtmlReporter) you prefer for a specific file when launched on its own...

<?php
require_once('simpletest/autorun.php');
SimpleTest :: prefer(new TextReporter());
require_once('../classes/writer.php');

class FileTestCase extends UnitTestCase {
    ...
}
?>