Mock objects documentation

class DatabaseConnection {
    function DatabaseConnection() {
    }
    
    function query() {
    }
    
    function selectQuery() {
    }
}

require_once('simpletest/unit_tester.php');
require_once('simpletest/mock_objects.php');
require_once('database_connection.php');

Mock::generate('DatabaseConnection');

require_once('simpletest/unit_tester.php');
require_once('simpletest/mock_objects.php');
require_once('database_connection.php');

Mock::generate('DatabaseConnection');

class MyTestCase extends UnitTestCase {
    
    function testSomething() {
        $connection = &new MockDatabaseConnection();
    }
}

Mocks as actors

The mock version of a class has all the methods of the original, so that operations like query()]]> are still legal. The return value will be null, but we can change that with...

$connection->setReturnValue('query', 37)

We can also add extra methods to the mock when generating it and choose our own class name...

Mock::generate('DatabaseConnection', 'MyMockDatabaseConnection', array('setOptions'));

Things aren't always that simple though. One common problem is iterators, where constantly returning the same value could cause an endless loop in the object being tested. For these we need to set up sequences of values. Let's say we have a simple iterator that looks like this...

class Iterator {
    function Iterator() {
    }
    
    function next() {
    }
}

Mock::generate('Iterator');

class IteratorTest extends UnitTestCase() {
    
    function testASequence() {
        $iterator = &new MockIterator();
        $iterator->setReturnValue('next', false);
        $iterator->setReturnValueAt(0, 'next', 'First string');
        $iterator->setReturnValueAt(1, 'next', 'Second string');
        ...
    }
}

Another tricky situation is an overloaded get() operation. An example of this is an information holder with name/value pairs. Say we have a configuration class like...

class Configuration {
    function Configuration() {
    }
    
    function getValue($key) {
    }
}

$config = &new MockConfiguration();
$config->setReturnValue('getValue', 'primary', array('db_host'));
$config->setReturnValue('getValue', 'admin', array('db_user'));
$config->setReturnValue('getValue', 'secret', array('db_password'));

$config->getValue('db_user')

You can set a default argument argument like so...

$config->setReturnValue('getValue', false, array('*'));

$config->setReturnValue('getValue', false);

There are times when you want a specific object to be dished out by the mock rather than a copy. The PHP4 copy semantics force us to use a different method for this. You might be simulating a container for example...

class Thing {
}

class Vector {
    function Vector() {
    }
    
    function get($index) {
    }
}

$thing = &new Thing();
$vector = &new MockVector();
$vector->setReturnReference('get', $thing, array(12));

These three factors, timing, parameters and whether to copy, can be combined orthogonally. For example...

$complex = &new MockComplexThing();
$stuff = &new Stuff();
$complex->setReturnReferenceAt(3, 'get', $stuff, array('*', 1));

A final tricky case is one object creating another, known as a factory pattern. Suppose that on a successful query to our imaginary database, a result set is returned as an iterator with each call to next() giving one row until false. This sounds like a simulation nightmare, but in fact it can all be mocked using the mechanics above.

Here's how...

Mock::generate('DatabaseConnection');
Mock::generate('ResultIterator');

class DatabaseTest extends UnitTestCase {
    
    function testUserFinder() {
        $result = &new MockResultIterator();
        $result->setReturnValue('next', false);
        $result->setReturnValueAt(0, 'next', array(1, 'tom'));
        $result->setReturnValueAt(1, 'next', array(3, 'dick'));
        $result->setReturnValueAt(2, 'next', array(6, 'harry'));
        
        $connection = &new MockDatabaseConnection();
        $connection->setReturnValue('query', false);
        $connection->setReturnReference(
                'query',
                $result,
                array('select id, name from users'));
                
        $finder = &new UserFinder($connection);
        $this->assertIdentical(
                $finder->findNames(),
                array('tom', 'dick', 'harry'));
    }
}

class SessionPool {
    function SessionPool() {
        ...
    }
    
    function &findSession($cookie) {
        ...
    }
    ...
}

class Session {
    ...
}

class Log {
    function Log() {
        ...
    }
    
    function message() {
        ...
    }
}

class LoggingSessionPool {
    function LoggingSessionPool(&$session_pool, &$log) {
        ...
    }
    
    function &findSession($cookie) {
        ...
    }
    ...
}

Mock::generate('Session');
Mock::generate('SessionPool');
Mock::generate('Log');

class LoggingSessionPoolTest extends UnitTestCase {
    ...
    function testFindSessionLogging() {
        $session = &new MockSession();
        $pool = &new MockSessionPool();
        $pool->setReturnReference('findSession', $session);
        $pool->expectOnce('findSession', array('abc'));
        
        $log = &new MockLog();
        $log->expectOnce('message', array('Starting session abc'));
        
        $logging_pool = &new LoggingSessionPool($pool, $log);
        $this->assertReference($logging_pool->findSession('abc'), $session);
    }
}

findSession() is a factory method the simulation of which is described above. The point of departure comes with the first expectOnce() call. This line states that whenever findSession() is invoked on the mock, it will test the incoming arguments. If it receives the single argument of a string "abc" then a test pass is sent to the unit tester, otherwise a fail is generated. This was the part where we checked that the right session was asked for. The argument list follows the same format as the one for setting return values. You can have wildcards and sequences and the order of evaluation is the same.

We use the same pattern to set up the mock logger. We tell it that it should have message() invoked once only with the argument "Starting session abc". By testing the calling arguments, rather than the logger output, we insulate the test from any display changes in the logger.

We start to run our tests when we create the new LoggingSessionPool and feed it our preset mock objects. Everything is now under our control.

This is still quite a bit of test code, but the code is very strict. If it still seems rather daunting there is a lot less of it than if we tried this without mocks and this particular test, interactions rather than output, is always more work to set up. More often you will be testing more complex situations without needing this level or precision. Also some of this can be refactored into a test case setUp() method.

Here is the full list of expectations you can set on a mock object in SimpleTest...

$method

The method name, as a string, to apply the condition to.

$args

The arguments as a list. Wildcards can be included in the same manner as for setReturn(). This argument is optional for expectOnce() and expectAtLeastOnce().

$timing

The only point in time to test the condition. The first call starts at zero.

$count

The number of calls expected.

Also if you have juste one call in your test, make sure you're using expectOnce.
Using $mocked->expectAt(0, 'method', 'args); on its own will not be catched : checking the arguments and the overall call count are currently independant.

Like the assertions within test cases, all of the expectations can take a message override as an extra parameter. Also the original failure message can be embedded in the output as "%s".

Mock objects generated with SimpleTest are dynamic. They are created at run time in memory, using eval(), rather than written out to a file. This makes the mocks easy to create, a one liner, especially compared with hand crafting them in a parallel class hierarchy. The problem is that the behaviour is usually set up in the tests themselves. If the original objects change the mock versions that the tests rely on can get out of sync. This can happen with the parallel hierarchy approach as well, but is far more quickly detected.

The solution, of course, is to add some real integration tests. You don't need very many and the convenience gained from the mocks more than outweighs the small amount of extra testing. You cannot trust code that was only tested with mocks.

If you are still determined to build static libraries of mocks because you want to simulate very specific behaviour, you can achieve the same effect using the SimpleTest class generator. In your library file, say mocks/connection.php for a database connection, create a mock and inherit to override special methods or add presets...

<?php
    require_once('simpletest/mock_objects.php');
    require_once('../classes/connection.php');

    Mock::generate('Connection', 'BasicMockConnection');
    class MockConnection extends BasicMockConnection {
        function MockConnection() {
            $this->BasicMockConnection();
            $this->setReturn('query', false);
        }
    }
?>

Use this trick if you find you have a lot of common mock behaviour or you are getting frequent integration problems at later stages of testing.

What are mock objects?

Creating mock objects.

Mocks as actors or stubs.

Mocks as critics with expectations.

Other approaches including mock libraries.

The original Mock objects paper.

SimpleTest project page on SourceForge.

SimpleTest home page on LastCraft.