What is SimpleTest?

The heart of SimpleTest is a testing framework built around test case classes. These are written as extensions of base test case classes, each extended with methods that actually contain test code. Each test method of a test case class is written to invoke various assertions that the developer expects to be true such as assertEqual(). If the expectation is correct, then a successful result is dispatched to the observing test reporter, but any failure or unexpected exception triggers an alert and a description of the mismatch. These test case declarations are transformed into executable test scripts by including a SimpleTest aurorun.php file.

These documents apply to SimpleTest version 1.1, although we try hard to maintain compatibility between versions. If you get a test failure after an upgrade, check out the file "HELP_MY_TESTS_DONT_WORK_ANYMORE" in the simpletest directory to see if a feature you are using has since been deprecated and later removed.

A test case looks like this...

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

class CanAddUp extends UnitTestCase {
    function testOneAndOneMakesTwo() {
        $this->assertEqual(1 + 1, 2);
    }
}
?>

Tests are grouped into test cases, which are just PHP classes that extend UnitTestCase or WebTestCase. The tests themselves are just normal methods that start their name with the letters "test". You can have as many test cases as you want in a test script and each test case can have as many test methods as it wants too.

This test script is immediately runnable. You just invoke it on the command line like so...

php adding_test.php

When run on the command line you should see something like...

adding_test.php
OK
Test cases run: 1/1, Passes: 1, Failures: 0, Exceptions: 0

If you place it on a web server and point your web browser at it...

Of course this is a silly example. A more realistic example might be...

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

class TestOfLogging extends UnitTestCase {
    function testWillCreateLogFileOnFirstMessage() {
        $log = new Log('my.log');
        $this->assertFalse(file_exists('my.log'));
        $log->message('Hello');
        $this->assertTrue(file_exists('my.log'));
    }</strong>
}
?>

This tool is designed for the developer. The target audience of this tool is anyone developing a small to medium PHP application, including developers new to unit and web regression testing. The core principles are ease of use first, with extendibility and essential features.

Tests are written in the PHP language itself more or less as the application itself is built. The advantage of using PHP as the testing language is that there are no new languages to learn, testing can start straight away, and the developer can test any part of the code. Basically, all parts that can be accessed by the application code can also be accessed by the test code when they are in the same programming language.

The simplest type of test case is the UnitTestCase. This class of test case includes standard tests for equality, references and pattern matching. All these test the typical expectations of what you would expect the result of a function or method to be. This is by far the most common type of test in the daily routine of development, making up about 95% of test cases.

The top level task of a web application though is not to produce correct output from its methods and objects, but to generate web pages. The WebTestCase class tests web pages. It simulates a web browser requesting a page, complete with cookies, proxies, secure connections, authentication, forms, frames and most navigation elements. With this type of test case, the developer can assert that information is present in the page and that forms and sessions are handled correctly.

A WebTestCase looks like this...

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

class MySiteTest extends WebTestCase {
    
    function testHomePageHasContactDetailsLink() {
        $this->get('http://www.my-site.com/index.php');
        $this->assertTitle('My Home Page');
        $this->clickLink('Contact');
        $this->assertTitle('Contact me');
        $this->assertText('/Email me at/');
    }
}
?>

Feature list

The following is a very rough outline of past and future features and their expected point of release. I am afraid it is liable to change without warning, as meeting the milestones rather depends on time available.

Green stuff has been coded, but not necessarily released yet. If you have a pressing need for a green but unreleased feature then you should check-out the code from Sourceforge SVN directly.

Feature	Description	Release
Unit test case	Core test case class and assertions	1.0
Html display	Simplest possible display	1.0
Autoloading of test cases	Reading a file with test cases and loading them into a group test automatically	1.0
Mock objects	Objects capable of simulating other objects removing test dependencies	1.0
Web test case	Allows link following and title tag matching	1.0
Partial mocks	Mocking parts of a class for testing less than a class or for complex simulations	1.0
Web cookie handling	Correct handling of cookies when fetching pages	1.0
Following redirects	Page fetching automatically follows 300 redirects	1.0
Form parsing	Ability to submit simple forms and read default form values	1.0
Command line interface	Test display without the need of a web browser	1.0
Exposure of expectation classes	Can create precise tests with mocks as well as test cases	1.0
XML output and parsing	Allows multi host testing and the integration of acceptance testing extensions	1.0
Browser component	Exposure of lower level web browser interface for more detailed test cases	1.0
HTTP authentication	Fetching protected web pages with basic authentication only	1.0
SSL support	Can connect to https: pages	1.0
Proxy support	Can connect via. common proxies	1.0
Frames support	Handling of frames in web test cases	1.0
File upload testing	Can simulate the input type file tag	1.0.1
Mocking interfaces	Can generate mock objects to interfaces as well as classes and class interfaces are carried for type hints	1.0.1
Testing exceptions	Similar to testing PHP errors	1.0.1
HTML label support	Can access all controls using the visual label	1.0.1
Base tag support	Respects page base tag when clicking	1.0.1
PHP 5 E_STRICT compliant	PHP 5 only version that works with the E_STRICT error level	1.1
Alternate HTML parsers	Can detect compiled parsers for performance improvements	1.1
REST support	Support for REST verbs as put(), delete(), etc.	1.1
BDD style fixtures	Can import fixtures using a mixin like given() method	1.5
Plug-in architecture	Automatic import of extensions including command line options	1.5
Reporting machinery enhancements	Improved message passing for better cooperation with IDEs	1.5
Fluent mock interface	More flexible and concise mock objects	1.6
Localisation	Messages abstracted and code generated as well as UTF support	1.6
CSS selectors	HTML content can be examined using CSS selectors	1.7
HTML table assertions	Can match HTML or other table elements to expectations	1.7
Unified acceptance testing model	Content searchable through selectors combined with expectations	1.7
DatabaseTestCase	SQL selectors and DB drivers	1.7
IFrame support	Reads IFrame content that can be refreshed	1.8
Integrated Selenium support	Easy to use built in Selenium driver and tutorial or similar browser automation	1.9
Code coverage	Reports using the bundled tool when using XDebug	1.9
Deprecation of old methods	Simpler interface for SimpleTest2	2.0
Javascript suport	Use of PECL module to add Javascript to the native browser	3.0

PHP 5 migration is complete, which means that only PHP 5.0.3+ will be supported in SimpleTest version 1.1+. Earlier versions of SimpleTest are compatible with PHP 4.2 up to PHP 5 (non E_STRICT).