The following assumes that you are familiar with the concept of unit testing as well as the PHP web development language. It is a guide for the impatient new user of SimpleTest. For fuller documentation, especially if you are new to unit testing see the ongoing documentation, and for example test cases see the unit testing tutorial.

Using the tester quickly

Amongst software testing tools, a unit tester is the one closest to the developer. In the context of agile development the test code sits right next to the source code as both are written simultaneously. In this context SimpleTest aims to be a complete PHP developer test solution and is called "Simple" because it should be easy to use and extend. It wasn't a good choice of name really. It includes all of the typical functions you would expect from JUnit and the PHPUnit ports, and includes mock objects.

What makes this tool immediately useful to the PHP developer is the internal web browser. This allows tests that navigate web sites, fill in forms and test pages. Being able to write these test in PHP means that it is easy to write integrated tests. An example might be confirming that a user was written to a database after a signing up through the web site.

The quickest way to demonstrate SimpleTest is with an example.

Let us suppose we are testing a simple file logging class called Log in classes/log.php. We start by creating a test script which we will call tests/log_test.php and populate it as follows...

<?php
require_once('simpletest/autorun.php');
require_once('../classes/log.php');

class TestOfLogging extends UnitTestCase {
}
?>

Here the simpletest folder is either local or in the path. You would have to edit these locations depending on where you unpacked the toolset. The "autorun.php" file does more than just include the SimpleTest files, it also runs our test for us.

The TestOfLogging is our first test case and it's currently empty. Each test case is a class that extends one of the SimpleTet base classes and we can have as many of these in the file as we want.

With three lines of scaffolding, and our Log class include, we have a test suite. No tests though.

For our first test, we'll assume that the Log class takes the file name to write to in the constructor, and we have a temporary folder in which to place this file...

<?php
require_once('simpletest/autorun.php');
require_once('../classes/log.php');

class TestOfLogging extends UnitTestCase {
    function testLogCreatesNewFileOnFirstMessage() {
        @unlink('/temp/test.log');
        $log = new Log('/temp/test.log');
        $this->assertFalse(file_exists('/temp/test.log'));
        $log->message('Should write this to a file');
        $this->assertTrue(file_exists('/temp/test.log'));
    }
}
?>

When a test case runs, it will search for any method that starts with the string "test" and execute that method. If the method starts "test", it's a test. Note the very long name testLogCreatesNewFileOnFirstMessage(). This is considered good style and makes the test output more readable.

We would normally have more than one test method in a test case, but that's for later.

Assertions within the test methods trigger messages to the test framework which displays the result immediately. This immediate response is important, not just in the event of the code causing a crash, but also so that print statements can display their debugging content right next to the assertion concerned.

To see these results we have to actually run the tests. No other code is necessary - we can just open the page with our browser.

On failure the display looks like this...

...and if it passes like this... And if you get this... it means you're missing the classes/Log.php file that could look like...

<?php
class Log {
    function Log($file_path) {
    }

    function message() {
    }
}
?>

It's fun to write the code after the test. More than fun even - this system is called "Test Driven Development".

For more information about UnitTestCase, see the unit test documentation.

Building test suites

It is unlikely in a real application that we will only ever run one test case. This means that we need a way of grouping cases into a test script that can, if need be, run every test for the application.

Our first step is to create a new file called tests/all_tests.php and insert the following code...

<?php
require_once('simpletest/autorun.php');

class AllTests extends TestSuite {
    function AllTests() {
        $this->TestSuite('All tests');
        $this->addFile('log_test.php');
    }
}
?>

The "autorun" include allows our upcoming test suite to be run just by invoking this script.

The TestSuite subclass must chain it's constructor. This limitation will be removed in future versions.

The method TestSuite::addFile() will include the test case file and read any new classes that are descended from SimpleTestCase. UnitTestCase is just one example of a class derived from SimpleTestCase, and you can create your own. TestSuite::addFile() can include other test suites.

The class will not be instantiated yet. When the test suite runs it will construct each instance once it reaches that test, then destroy it straight after. This means that the constructor is run just before each run of that test case, and the destructor is run before the next test case starts.

It is common to group test case code into superclasses which are not supposed to run, but become the base classes of other tests. For "autorun" to work properly the test case file should not blindly run any other test case extensions that do not actually run tests. This could result in extra test cases being counted during the test run. Hardly a major problem, but to avoid this inconvenience simply mark your base class as abstract. SimpleTest won't run abstract classes. If you are still using PHP4, then a SimpleTestOptions::ignore() directive somewhere in the test case file will have the same effect.

Also, the test case file should not have been included elsewhere or no cases will be added to this group test. This would be a more serious error as if the test case classes are already loaded by PHP the TestSuite::addFile() method will not detect them.

To display the results it is necessary only to invoke tests/all_tests.php from the web server or the command line.

For more information about building test suites, see the test suite documentation.

Using mock objects

Let's move further into the future and do something really complicated.

Assume that our logging class is tested and completed. Assume also that we are testing another class that is required to write log messages, say a SessionPool. We want to test a method that will probably end up looking like this...

class SessionPool {
    ...
    function logIn($username) {
        ...
        $this->_log->message("User $username logged in.");
        ...
    }
    ...
}

In the spirit of reuse, we are using our Log class. A conventional test case might look like this...

<?php
require_once('simpletest/autorun.php');
require_once('../classes/log.php');
require_once('../classes/session_pool.php');

class TestOfSessionLogging extends UnitTestCase {
    
    function setUp() {
        @unlink('/temp/test.log');
    }
    
    function tearDown() {
        @unlink('/temp/test.log');
    }
    
    function testLoggingInIsLogged() {
        $log = new Log('/temp/test.log');
        $session_pool = &new SessionPool($log);
        $session_pool->logIn('fred');
        $messages = file('/temp/test.log');
        $this->assertEqual($messages[0], "User fred logged in.\n");
    }
}
?>

We'll explain the setUp() and tearDown() methods later.

This test case design is not all bad, but it could be improved. We are spending time fiddling with log files which are not part of our test. We have created close ties with the Log class and this test. What if we don't use files any more, but use ths syslog library instead? It means that our TestOfSessionLogging test will fail, even thouh it's not testing Logging.

It's fragile in smaller ways too. Did you notice the extra carriage return in the message? Was that added by the logger? What if it also added a time stamp or other data?

The only part that we really want to test is that a particular message was sent to the logger. We can reduce coupling if we pass in a fake logging class that simply records the message calls for testing, but takes no action. It would have to look exactly like our original though.

If the fake object doesn't write to a file then we save on deleting the file before and after each test. We could save even more test code if the fake object would kindly run the assertion for us.

Too good to be true? We can create such an object easily...

<?php
require_once('simpletest/autorun.php');
require_once('../classes/log.php');
require_once('../classes/session_pool.php');

Mock::generate('Log');

class TestOfSessionLogging extends UnitTestCase {
    
    function testLoggingInIsLogged() {
        $log = &new MockLog();
        $log->expectOnce('message', array('User fred logged in.'));
        $session_pool = &new SessionPool($log);
        $session_pool->logIn('fred');
    }
}
?>

The Mock::generate() call code generated a new class called MockLog. This looks like an identical clone, except that we can wire test code to it. That's what expectOnce() does. It says that if message() is ever called on me, it had better be with the parameter "User fred logged in.".

The test will be triggered when the call to message() is invoked on the MockLog object by SessionPool::logIn() code. The mock call will trigger a parameter comparison and then send the resulting pass or fail event to the test display. Wildcards can be included here too, so you don't have to test every parameter of a call when you only want to test one.

If the mock reaches the end of the test case without the method being called, the expectOnce() expectation will trigger a test failure. In other words the mocks can detect the absence of behaviour as well as the presence.

The mock objects in the SimpleTest suite can have arbitrary return values set, sequences of returns, return values selected according to the incoming arguments, sequences of parameter expectations and limits on the number of times a method is to be invoked.

For more information about mocking and stubbing, see the mock objects documentation.

Web page testing

One of the requirements of web sites is that they produce web pages. If you are building a project top-down and you want to fully integrate testing along the way then you will want a way of automatically navigating a site and examining output for correctness. This is the job of a web tester.

The web testing in SimpleTest is fairly primitive, as there is no JavaScript. Most other browser operations are simulated.

To give an idea here is a trivial example where a home page is fetched, from which we navigate to an "about" page and then test some client determined content.

<?php
require_once('simpletest/autorun.php');
require_once('simpletest/web_tester.php');

class TestOfAbout extends WebTestCase {
    function testOurAboutPageGivesFreeReignToOurEgo() {
        $this->get('http://test-server/index.php');
        $this->click('About');
        $this->assertTitle('About why we are so great');
        $this->assertText('We are really great');
    }
}
?>

With this code as an acceptance test, you can ensure that the content always meets the specifications of both the developers, and the other project stakeholders.

You can navigate forms too...

<?php
require_once('simpletest/autorun.php');
require_once('simpletest/web_tester.php');

class TestOfRankings extends WebTestCase {
    function testWeAreTopOfGoogle() {
        $this->get('http://google.com/');
        $this->setField('q', 'simpletest');
        $this->click("I'm Feeling Lucky");
        $this->assertTitle('SimpleTest - Unit Testing for PHP');
    }
}
?>

...although this could violate Google's(tm) terms and conditions.

For more information about web testing, see the scriptable browser documentation and the WebTestCase.