Manual:PHP unit testing/Running the tests

First run
Make sure you have installed PHPUnit.

Unit tests are run from the command line as there is no graphical user interface as of January 2012. Although phpunit provide a bootstrapping facility, we use a wrapper script. It makes sure the MediaWiki framework is properly initialized using your LocalSettings.php file, then directly call PHPUnit API. Invoking phpunit as is will simply not work.

Make sure your LocalSetting.php has language set to English. (This is bug 26464): $wgLanguageCode = "en";

Unit tests fail might when run with locale enabled, therefore you should unset LANG, LC_ALL, LC_COLLATE, LC_CTYPE, LC_MESSAGES, LC_MONETARY</tt>, LC_NUMERIC</tt>, LC_TIME</tt> environment variables or make sure they are set to C</tt> (This is bug 35114).

The wrapper script phpunit.php</tt> is located in the tests/phpunit</tt> directory and is invoked using the PHP interpreter:

$ cd tests/phpunit $ php phpunit.php

The wrapper script is itself a MediaWiki maintenance script, and will pass all arguments to PHPUnit. To get a list of possible arguments have a look at phpunit --help</tt>.

Using default test groups
To make it easier to newcomers, we have a makefile providing some sane default targets. They will run sub groups of tests and are easier to remember than some long shell commands. You will obviously need the make utility. The list of targets and their descriptions, is available by running make help</tt>.

The sub group names my looks obscure to you right now, we will describe them later on in the writing unit tests section. Just remember the makefile target gather test sub-groups and give them an easy to remember name. Think about them as shortcuts.

For instance, to run all tests that do not require a database connection, the target is named databaseless</tt> which you pass to the make utility:

As said above, a list of other targets is always available using the special help target (make help</tt>).

Running group of tests might be long and tedious, specifically when you are only altering a very specific part of the MediaWiki codebase. For example, you might be implementing some IPv6 functionality in the includes/IP.php file. In the test suite, that file code is covered by includes/IPTest.php which you can pass as an argument to our PHPUnit wrapper.

Running the individual tests from includes/IPTest.php looks like:

To see the name of each running test, uses the Test Anything Protocol format available in PHPUnit using --tap</tt>:

This format is great to filter the output for non passing test. For example with the grep command:

phpunit also provide a kind of checklist that give out a great output for people not familiar with tests or shells: the testdox format:

An unchecked box ([ ]</tt>), means the test failed, such as the one named « RC ns filter association » above.