Taking control of testing

In order to test a code module you need very tight control of its environment. If anything can vary behind the scenes, for example a configuration file, then this could cause the tests to fail unexpectedly. This would not be a fair test of the code and could cause you to spend fruitless hours examining code that is actually working, rather than dealing with the configuration issue that actually failed the test. At the very least your test cases get more complicated in taking account the possible variations.

Controlling time

There are often a lot of obvious variables that could affect a unit test case, especially in the web development environment in which PHP usually operates. These include database set up, file permissions, network resources and configuration amongst others. The failure or misinstall of one of these components will break the test suite.

Do we add tests to confirm these components are installed? This is a good idea, but if you place them into code module tests you will start to clutter you test code with detail that is irrelavent to the immediate task. They should be placed in their own test suite.

Another problem, though, is that our development machines must have every system component installed to be able to run the test suite. Your tests run slower too.

When faced with this while coding we will often create wrapper versions of classes that deal with these resources. Ugly details of these resources are then coded once only. I like to call these classes "gateway classes", as they exist at the edges of the application, the interface of your application with the rest of the system. These gateway classes are best simulated during testing by fake versions. These run faster and are often called "Server Stubs", or in more generic form "Mock Objects". It is a great time saver to wrap and stub out such resources.

One often neglected external resource is time.

For example, to test a session time-out coders will often temporarily set the session time limit to a small value, say two seconds, and then do a sleep(3) and assert that the session is now invalid. That adds three seconds to your test suite and is usually a lot of extra code making your session classes that maleable. Far simpler is to have a way to suddenly advance the clock. To control time.

A clock class

We will again design our clock wrapper by first writing tests. We add a clock test case to our tests/all_tests.php test suite...

<?php
require_once(dirname(__FILE__) . '/simpletest/autorun.php');
require_once(dirname(__FILE__) . '/log_test.php');
require_once(dirname(__FILE__) . '/clock_test.php');

class AllTests extends TestSuite {
    function __construct() {
        parent::__construct();
        $this->addTestCase(new TestOfLogging());
        $this->addTestCase(new TestOfClock());
    }
}
?>

Then we create the test case in the new file tests/clock_test.php...

<?php
require_once(dirname(__FILE__) . '/../classes/clock.php');

class TestOfClock extends UnitTestCase {
    function testClockTellsTime() {
        $clock = new Clock();
        $this->assertEqual($clock->now(), time());
    }
}
?>

Our only test at the moment is that our new Clock class acts as a simple PHP time() function substitute. We will write the time shift functionality once we are green. At the moment we are obviously not green...

If you don't see this kind of error, it means your error settings need some adjustments. You may want to add these lines at the top of your test :

ini_set('display_errors', 1);
error_reporting(E_ALL);

The PHP documentation will come handy if you're stuck withouth the Fatal error.

Assuming the error was indeed shown, we can carry on and create a classes/clock.php file...

<?php
class Clock {
    function now() {
    }
}
?>

This regains our flow ready for coding.

This is now easy to fix...

class Clock {
    function now() {
        return time();
    }
}

And we are green...

There is still a problem.

The clock could roll over during the assertion causing the result to be out by one second. The chances are small, but if there were a lot of timing tests you would end up with a test suite that is erratic, severely limiting its usefulness. We will tackle this shortly and for now just jot it onto our "to do" list.

The advancement test looks like this...

class TestOfClock extends UnitTestCase {

    function testClockTellsTime() {
        $clock = new Clock();
        $this->assertEqual($clock->now(), time());
    }
    
    function testClockAdvance() {
        $clock = new Clock();
        $clock->advance(10);
        $this->assertEqual($clock->now(), time() + 10);
    }
}

The code to get to green is straight forward and just involves adding a time offset.

class Clock {
    private $offset = 0;
    
    function now() {
        return time() + $this->offset;
    }
    
    function advance($offset) {
        $this->offset += $offset;
    }
}

Test suite tidy up

Our all_tests.php file has some repetition we could do without. We have to manually add our test cases from each included file. It is possible to remove it, but use of the following requires care. The TestSuite class has a convenience method called addFile() that takes a PHP file as a parameter. This mechanism makes a note of all the classes, requires in the file and then has a look at any newly created classes. If they are descendents of SimpleTestCase they are added as a new TestSuite.

Here is our refactored test suite using this method...

<?php
require_once(dirname(__FILE__) . '/simpletest/autorun.php');
    
class AllTests extends TestSuite {
    function AllTests() {
        parent::__construct();
        $this->addFile('log_test.php');
        $this->addFile('clock_test.php');
    }
}
?>

The pitfalls of this are...

1. If the test file has already been included, no new classes will be added to this group
2. If the test file has other classes that are related to SimpleTestCase then these will be added to the group test as well.

In practice neither of these turn out to be problems. Test suites are usually a tree structure. It's rare to need a test case in two places. As for extra classes being included, they have to be descendents of SimpleTestCase. These are likely to be superclasses of helper code for several other tests. Simply marking them as abstract is enough to stop them being run.

We should really fix the glitch with the possible clock rollover so we'll do this next.