Unit Testing Dokuwiki

Tests are available in the _test directory of a darcs checkout- see the README. The test suite uses the Simple Test Unit Test Framework for PHP (available via http://www.lastcraft.com/simple_test.php - hosted on SourceForge at http://sourceforge.net/projects/simpletest).

• What is Unit Testing? In very brief it's writing code to test “units” of other code, so that tests can be re-run at any time to determine whether or not code has been “broken” (vs. manually testing applications, which is lengthy and potentially unreliable). The word “unit” is used to mean anything that provides a clearly defined API, such as a PHP class or function. For more thoughts on Unit Testing head to http://en.wikipedia.org/wiki/Unit_testing
• What is SimpleTest? Simple Test is a unit test framework. It provides tools for testing your code to reduce the effort required to write tests and make re-running tests easy. See simple test resources.
• Where are the tests for DokuWiki? The DokuWiki test suite can be found in the _test subdirectory of a _darcs checkout. They are not included in the regular releases.

First step is modifying the ./_test/tests.ini file - see the ./_test/README for details.

Once done you can run the tests either using a web browser (e.g. http://localhost/dokuwiki/_test/index.php) or from the command line like:

$> pwd
/home/username/public_html/dokuwiki/_test
$> ./runtests.php -h

This assumes you have PHP setup to run from the command line and the binary is as /usr/local/bin/php. You could alternatively run the tests like;

$> php runtests.php

A third option is running “remote tests” against a DokuWiki test suite running on a remote web server. This is basic “client/server” testing - the remotetests.php is a command line script able to run the tests on a remote web server, over HTTP. On the test server side, available tests are listed using RSS while the tests themselves are available in an alternative XML form - these can be seen when appending the GET variable ”&output=xml” to URL's you are viewing via the normal browser interface. ¹⁾

The Dokuwiki test suite aims to make writing new tests as painless as possible. In general it means writing a fairly simple PHP class and placing it in the right directory with the right file name. Once that's done, the test can immediately be executed via the test suite, without any further modifications.

Tests are placed somewhere below the ./_test/cases/ directory. Generally it's recommended this directory structure follow that of the DokuWiki code it is testing i.e. tests for ./feed.php go directly under ./_test/cases while tests for ./inc/auth/plain.php would go under ./_test/cases/inc/auth.

A normal test file should be given an extension like foo.test.php. The last part .test.php is required for the test to be found automatically by the test suite.

The other file naming convention is .group.php which is for “Group Tests”²⁾.

Let's say I want to test the buildURLparams() function in ./inc/common.php.

The first step is creating a file called ./_test/cases/inc/common_buildURLparams.test.php. The first part of this is a recommendation for a naming convention. Rather than having a single file which tests everything in ./inc/common.php it's probably easier to have seperate files for each function in ./inc/common.php so I use a name which helps identify what I'm testing. Using common_ in the file name may also allow a group test to be written which automatically loads all the relevant files for that group, by locating all those that start with common_.

The next step is writing the test class itself;

<?php
require_once DOKU_INC . 'inc/common.php';
 
class common_buildURLparams_test extends UnitTestCase {
 
    function testNoParams() {
        // No params should mean empty string
        $this->assertEqual(buildURLparams(array()),'');
    }
 
    function testOneParam() {
        // No params should mean empty string
        $this->assertEqual(
            buildURLparams(array('x'=>1)),
            'x=1'
            );
    }
 
    function testTwoParams() {
        // No params should mean empty string
        $this->assertEqual(
            buildURLparams(array('x'=>1,'y'=>2)),
            'x=1&amp;y=2'
            );
    }
}

The test is now runnable (see running the tests).

TODO

TODO

We will be placing the code here

Simple Test has excellent documentation which is a must read before attempting to do anything serious with the DokuWiki test suite. There are also various online articles about Simple Test. Check out the following links;

• Core Simple Test Documentation
• Simple Test Tutorial
• SimpleTest
• http://www.simpletest.org/ - contains all the info in the first two links plus SimpleTest API docs. Exactly the same can also be found at http://simpletest.sourceforge.net
• Coding a Login Box Shouldn't Hurt - discusses writing “Web Test Cases” where Simple Test act's as a PHP-scriptable web browser
• UnitTesting in PHP using SimpleTest - general intro tutorial
• How To Test Methods that Write to the Database - thoughts on this problem (similar also might apply to writing to files)
• Introducing PHP: Testing times - another intro tutorial (be warned - site uses excessive Flash ads)
• Introduction to SimpleTest - talk on SimpleTest at FOSDEM, Bruxelles, 2005
• PHP Unit Testing Forum - many Simple Test users here
• http://del.icio.us/tag/simpletest - A place to find further Simple Test related links