View source for Manual:PHP unit testing/Running the tests

{{Manual:PHP unit testing/navigation}}

== Entrypoints for running the tests ==

We use composer to run PHPUnit tests. If you have not already, run <code>composer update</code> in the root of the MediaWiki core repository.

=== All tests ===
The entry point for running all tests at once is the <code>composer phpunit:entrypoint</code> command, that must be run in the MediaWiki directory:

<pre>
$ composer phpunit:entrypoint -- path/to/my/test
</pre>

==== Error "Cannot access the database: Unknown database" ====

If you get this error you may need to set the environment variable <code>PHPUNIT_WIKI</code>, e.g:<syntaxhighlight lang="bash">
$ PHPUNIT_WIKI=wiki composer phpunit:entrypoint -- path/to/my/test
</syntaxhighlight>

==== The "--filter" option does not exist ====

This and similar errors can occur if you omit the <code>--</code> when invoking the Composer script. Make sure to always use the double dash when running the Composer script, to separate Composer and PHPUnit arguments.

=== Integration tests ===
These are tests that are contained in <code>tests/phpunit/integration</code> folders.<pre>
$ composer phpunit:integration -- path/to/my/test
</pre>

=== Unit tests ===
These are tests that are contained in <code>tests/phpunit/unit</code> folders.

Run only the pure "unit" tests for MediaWiki core and all extensions and skins: 

{{terminal|height=36em|text=
$ composer phpunit:unit
> phpunit --colors=always --testsuite=core:unit,extensions:unit,skins:unit
PHPUnit 8.5.8 by Sebastian Bergmann and contributors.

.............................................................   61 / 8977 (  0%)
.............................................................  122 / 8977 (  1%)
.............................................................  183 / 8977 (  2%)
.............................................................  244 / 8977 (  2%)
.............................................................  305 / 8977 (  3%)
}}

To run specific pure "unit" tests only, use the PHPUnit entrypoint located at <code>vendor/bin/phpunit</code>

{{terminal|text=
$ vendor/bin/phpunit --help
PHPUnit 8.5.8 by Sebastian Bergmann and contributors.

Usage:
  phpunit [options] UnitTest [UnitTest.php]
  phpunit [options] <directory>
}}

{{note|This documentation assumes that you are running tests in a local development environment. Do not run tests on a real website, bad things will happen!}}

{{Warn|Some of the integration tests are destructive. Although they are supposed to use a copy of the database, there are most probably a few bugs in the system and may modify live data. '''Do not run the tests on a production wiki'''.}}

== Select by directory or file ==
Running all tests from all core components and installed extensions may take a while. During development you may want to focus on just a particular test suite or directory of test suites. Pass the directory or file to the phpunit command.

For example, if you're working on a patch that modifies <code>includes/ResourceLoader</code>, with a test covering it under <code>unit/includes/ResourceLoader/</code>, then you might run the tests like so:

{{terminal|text=
$ composer phpunit:entrypoint -- tests/phpunit/unit/includes/ResourceLoader/
  PHPUnit by Sebastian Bergmann.
  
...........................................................       59 / 59 (100%)

Time: 1.78 seconds, Memory: 22.00 MB

<span style="background-color:green; color:black;">OK (59 tests, 80 assertions)</span>
}}

To run tests for a specific extension or skin:

{{terminal|text=
$ composer phpunit:entrypoint -- extensions/EventLogging/tests/phpunit/
  
...........................................................       59 / 59 (100%)
}}

== Select by test name ==
If you're debugging a specific test case and are adding breakpoints or var_dump statements, it may be useful to filter even more closely than by the file, so as to skip past all other invocations of the same underlying code. To do this, use the <code>--filter</code> option to match substrings of the test name. For example, given a test suite like the following:

<syntaxhighlight lang="php">
namespace MediaWiki\Tests\ResourceLoader;

class FileModuleTest extends MediaWikiIntegrationTestCase {
	protected function setUp(): void {
		parent::setUp();
		// ...
	}

	public function testLessCompiler() {
		// ...
	}

	public function testGetScriptPackageFiles() {
		// ...
	}

	public function testGetVersionHash() {
		// ...
	}
}
</syntaxhighlight>You can combine the directory selection with <code>--filter</code> to run only the second <code>testGetScriptPackageFiles</code> test case, like so:

{{terminal|text=
$ composer phpunit:entrypoint -- --filter Package tests/phpunit/includes/ResourceLoader/FileModuleTest.php
  PHPUnit by Sebastian Bergmann.
  
...........................................................       21 / 21 (100%)

Time: 0.17 seconds, Memory: 22.00 MB

<span style="background-color:green; color:black;">OK (21 tests, 21 assertions)</span>
}}


== Select by group ==
Each test case can be grouped using the <code>@group</code> annotation in the test case file. The group names may look obscure at first, we will describe them later on in the [[Manual:PHP unit testing/Writing unit tests|Writing unit tests]] chapter.

To only run tests in a particular group, use the <code>--group</code> option.
{{Note|This may be '''slow''' and will be silent for a few seconds before the tests start, because it still requires PHPUnit to load and data-provide all test suites (including extensions) before the group filter is applied. For fast results, select by directory instead.}}{{terminal|text=
$ composer phpunit:entrypoint -- --group Cache
  PHPUnit by Sebastian Bergmann.
  
  ................................................<span style="color:yellow">IIIII</span>........   61 / 2311 (  2%)
  ............<span style="color:yellow">I</span>................................................  122 / 2311 (  5%)
  .............................................................  183 / 2311 (  7%)
  .............................................................  244 / 2311 ( 10%)
  .............................................................  305 / 2311 ( 13%)
  .............................................................  366 / 2311 ( 15%)
  .............................................................  427 / 2311 ( 18%)
  .............................................................  488 / 2311 ( 21%)
  .............................................................  549 / 2311 ( 23%)
  .....................<span style="color:yellow">I</span>.......................................  610 / 2311 ( 26%)
  .............................................................  671 / 2311 ( 29%)
  .......................................................S...<span style="color:yellow">II</span>  732 / 2311 ( 31%)
  <span style="color:yellow">IIIIIIIIIII</span>...<span style="color:yellow">IIIIIIIIIIIIIII</span>................................  793 / 2311 ( 34%)
  ............................
  
  Time: 10 seconds, Memory: 97.25Mb
  
  There were 35 incomplete tests:
[snip]
  
<span style="color:black; background-color:yellow">OK, but incomplete or skipped tests!
Tests: 821, Assertions: 78982, Incomplete: 35, Skipped: 1.</span>
}}To find all available groups, run <code>$ composer phpunit:entrypoint -- --list-groups</code> to print the available test groups. To run a particular test group, pass it to phpunit, for example:
 $ composer phpunit:entrypoint -- --group Editing

== Output format ==
To see the name of each running test, use the TAP format by passing the <code>--tap</code> option to PHPUnit:
[[en:Test Anything Protocol]]
{{terminal|text=
$ composer phpunit:entrypoint -- --tap tests/phpunit/includes/libs/IPTest.php
TAP version 13
not ok 1 - Error: IPTest::testisIPAddress
ok 2 - IPTest::testisIPv6
ok 3 - IPTest::testisIPv4
ok 4 - IPTest::testValidIPs
^C
$

}}

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

{{terminal|text=
$ composer phpunit:entrypoint -- --tap tests/phpunit/includes/libs/IPTest.php <nowiki>|</nowiki> egrep '^not'
not ok 1 - Error: IPTest::testisIPAddress
$
}}

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

{{terminal|text=
$ composer phpunit:entrypoint -- --testdox tests/phpunit/includes/specials/
PHPUnit by Sebastian Bergmann.

Configuration read from /srv/trunk/tests/phpunit/suite.xml

QueryAllSpecialPages
 [x] Querypage sql query

SpecialRecentchanges
 [x] Rc ns filter
 [x] Rc ns filter inversion
 [ ] Rc ns filter association
 [x] Rc ns filter association with inversion

SpecialSearch
 [x] Profile and namespace loading
}}

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

== How it works ==
=== Database ===
Integration tests that involve a database are automatically run against a temporary clone of your current wiki's database (the one configured in LocalSettings.php).

Because of this, it is important that the MediaWiki installation being tested has an up to date and correct database, or error messages (such as "TestUser.php: Can't create user on real database") will result.