Manual:PHP unit testing

Unit testing in MediaWiki is performed using the PHPUnit framework.

The unit tests are located in the tests/phpunit directory. Tests are organized into a directory structure that matches the directory structure of the code that they are testing. For example: The unit tests for file includes/IP.php can be found in tests/phpunit/includes/IP.php.

Installing PHPUnit

To run the unit tests, PHPUnit must be installed. To install PHPUnit, follow the installation instructions in the PHPUnit manual.

On Linux systems, the distributon may have provided a version of PHPUnit that you can use. If you'd like to use it, run make install from the tests/phpunit directory.

Running the unit tests

Caution:

Some of the unit tests are destructive. Do not run the tests on a production wiki.

Run the unit tests from the command line, ensuring that you are in the tests/phpunit directory.

• On UNIX-like operating systems, run make. To see options for running the tests, run make help.
• On Windows-family operating systems, run the run-tests.bat batch file.

Writing unit tests

The PHPUnit Manual provides good instructions for understanding and developing unit tests. Pay particularly close attention to the sections on writing and organizing tests.

Developers new to unit testing in MediaWiki should use SampleTest.php as a starting point – it contains helpful comments that will ease the process of learning to write unit tests.

Grouping tests

PHPUnit allows tests to be put into arbitrary groups. Groups of tests can be selected for execution or excluded from execution when the test suite is run (see the @group annotation, The Command-Line Test Runner and XML Configuration File documentation in the PHPUnit manual for additional details.)

To add a test (or class) to a group, use the @group annotation in the docblock preceding the code. For example:

/**
 * @group Broken
 */
class HttpTest extends PHPUnit_Framework_TestCase {
    ...

Eight groups are currently used in the MediaWiki unit tests:

• Broken: Put broken tests into group Broken. Tests in this group will not be run (as is configured in tests/phpunit/suite.xml).
• Database: Tests that require database connectivity should be put into group Database.
• Destructive: Tests that alter or destroy data should be put into group Destructive.
• Search: Tests that use MediaWiki's built-in search put into group Search.
• SeleniumFramework: Tests that alter or destroy data should be put into group Stub.
• Stub: Put test stubs into group Stub. Tests in this group will not be run (as is configured in tests/phpunit/suite.xml).
• sqlite: Tests that use SQLite should be put into group sqlite.
• Upload: Tests that upload files should be put into group Upload.
• Utility: Currently unused by any test. Tests in this group will be not be run (as is configured in tests/phpunit/suite.xml).

Developing best practices

Developers should avoid inventing new conventions or borrowing conventions from other frameworks; using the already well-established PHPUnit conventions will serve to make MediaWiki's tests both useful and usable.

See also

Manual:Writing testable PHP code