Tests are available in the _test directory of a git checkout - see the README in that directory. 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). Note that SimpleTest 1.1 is not currently supported.

• 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 git checkout. They are not included in the regular releases.

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

Also, make sure that:

• you ran install.php (else, some acl tests will fail)
• the page playground:playground actually exist (otherwise, some test in pageutils_resolve_pageid.test.php will fail)

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. ¹⁾

There are probably many fails and exceptions in your test output. This does not mean that DokuWiki is broken; many problems are known:

• Failures on auth_aclcheck.test.php: You should run install.php
• Function set_magic_quotes_runtime() is deprecated:
• Equal expectation fails at character 11 with [playground:start] and [playground:playground] at line [58]: You deleted your playground:playground page; name resolution works different in this case
• Non-static method Mock::generate() should not be called statically, assuming $this from incompatible context:
• testEmWithUnknownSchema, testNotEm, testNotEmSchemaAtClose, testNoEmWithInvalidURL, testNoEmWithUnknownURL: Known bug
• http://www.php.net/runkit required: Obviously the test requires the PHP runkit and will not run.
• Several E_NOTICE warnings: You should probably lower your PHP error reporting level, DokuWiki is not E_NOTICE clean
• Call-time pass-by-reference has been deprecated:

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://delicious.com/tag/simpletest - A place to find further Simple Test related links