Manual:PHP unit testing/Writing unit tests for extensions
Contents
- Running the tests
- Generate code coverage
- Writing testable PHP code
- Writing tests
- Continuous integration
- Understanding build failures
- Appendix
(how to help, resources..)
Tools
The recommended bootstrapping method for extensions is to create your tests in the tests/phpunit/
directory of your extension (or use the UnitTestsList hook). Either of these methods will ensure MediaWiki core is bootstrapped for things like autoloading classes, global functions etc.
Two types of tests
editMediaWiki supports "unit" tests and "integration" tests. The general idea is that with "unit" tests, you create mocks of all the objects that are used by methods you are testing. With integration tests, you have access to actual objects generated by other code, including data loaded from the database. If you are writing unit tests, extend MediaWikiUnitTestCase and place your tests in tests/phpunit/unit
. If you are writing integration tests, extend MediaWikiIntegrationTestCase and place your tests in tests/phpunit/integration
.
Create your tests
editLet's say our Fruits extension has a class called AppleFruit
.
- Create a test file in your extension’s tests/phpunit/ directory, named
AppleFruitTest.php
- Make sure that the file name ends in
Test.php
or else phpunit will not be able to discover it.
- Make sure that the file name ends in
- Create a class in that file named
AppleFruitTest
and extend the MediaWikiTestCase class. - The class must contain a
protected function setUp()
that callsparent::setUp()
as its first task. - If you need to perform an operation on teardown of the test, the class may contain a
protected function tearDown()
that callsparent::tearDown()
as its last task. - Each of your test functions should :
- be
public
. - begin their function name with
test
.
- be
- It’s a good idea to add an
@group
comment to the class. This group name can then be referred to later in order to run tests only in this group or exclude them. You can also place an@group
comment above each test function if you wish to further isolate your tests.- There are two special group names: "
Database
" and "Standalone
":- Tests tagged into the group
Database
are allowed to access the wiki's database and make destructive changes to the wiki; suites from extensions which are tagged this way are tested by Continuous Integration separately, in isolation from each other. Other tests are forbidden from making changes to the wiki, and will fail. - Tests tagged into the group
Standalone
are only run for patches to that repo, and not for other repos which depend on this one. This lets you write extensive, expensive tests for features your extension provides, without slowing down the test runs for other repos. You must get CI configured for your repo to run these tests; by default, the stand-alone test suite isn't run.
- Tests tagged into the group
- There are two special group names: "
<?php
/**
* @group Fruit
* @covers AppleFruit
*/
class AppleFruitTest extends MediaWikiUnitTestCase {
private $apple;
protected function setUp() {
parent::setUp();
$this->apple = Fruit::factory( 'apple' );
}
protected function tearDown() {
unset( $this->apple );
parent::tearDown();
}
public function testIsEdible() {
$this->assertTrue( $this->apple->isEdible(), "apples should be edible." );
}
}
For integration tests that involve global state, MediaWikiServices, etc, extend MediaWikiIntegrationTestCase
instead (formerly known as MediaWikiTestCase
).
Run your tests
editSingle test file
edit# from within the core/ directory
composer phpunit:entrypoint -- extensions/Fruits/tests/phpunit/AppleFruitTest.php
If you are using vagrant and get an error message: "Cannot access the database: Unknown database", try adding --wiki wiki
to the command line.
All test files
edit# from within the core/ directory
composer phpunit:entrypoint -- extensions/Fruits/tests/phpunit/
Create a custom test suite
editcomposer phpunit:entrypoint
runs with a default test suite defined in core/tests/phpunit/suite.xml
. You can alter that test suite by doing the following:
- Copy the
core/tests/phpunit/suite.xml
file tosuite.extensions.xml
. - Edit the suite.extensions.xml file:
- remove any unwanted
<testsuite>
from the<testsuites>
node. - add or make sure a
<testsuite>
node exists with the following:
<testsuite name="extensions">
<file>/full/path/to/core/tests/phpunit/suites/ExtensionsTestSuite.php</file>
<file>/full/path/to/core/tests/phpunit/suites/ExtensionsParserTestSuite.php</file>
</testsuite>
# from within the core/ directory
vendor/bin/phpunit --configuration tests/phpunit/suite.extensions.xml
Tests for any extension loaded in LocalSettings.php
will be run. If you want to isolate tests to only your extension, you can exclude groups of tests within the suite.extensions.xml
file.
List groups
editYou can get a list of test groups available for a specific configuration by running:
vendor/bin/phpunit --configuration tests/phpunit/suite.extensions.xml --list-groups
Exclude groups
editYou can then exclude specific test groups by adding them to the <groups>
, <exclude>
node in suite.extensions.xml
:
<groups>
<exclude>
<group>Utility</group>
<group>Broken</group>
<group>ParserFuzz</group>
<group>Stub</group>
<group>Database</group>
<group>ParserTests</group>
<group>ParserTests_LuaParserTests</group>
<group>__nogroup__</group>
<group>large</group>
<group>medium</group>
</exclude>
</groups>
Tests are considered part of a group when an @group
comment is placed above the class or function.
__nogroup__
covers any test that has not been given an@group
comment.- phpunit also considers an
@author
comment as an@group
comment, but@group
is preferred.