Manual:PHP unit testing/Code coverage

From MediaWiki.org
Jump to navigation Jump to search
MediaWiki Flower
« Unit testing
PHPUnit testing

This manual explains how to generate code coverage on your local workstation. This can be useful to understand how coverage works and to see progress on your work before submitting your change to Gerrit.

Ensure you have:

  • PHPUnit installed.
  • Xdebug installed.

Run the following script:

$ cd mediawiki/tests/phpunit/
# $ php phpunit.php --coverage-html ../../docs/coverage [files]
# For example:
$ php phpunit.php --coverage-html ../../docs/coverage includes/MessageTest.php

Viewing coverage reports[edit]

Coverage reports for MediaWiki core, extensions, and all of our separate libraries are published regularly on doc.wikimedia.org. (See the tutorial on how to add your extension to the list).

CoverMe provides an alternative view, sorting functions by how often they are called in Wikimedia production, helping identify functions that will benefit the most from additional test coverage.

Coverage scope[edit]

When running PHPUnit on a subset of files or sub directory, the tests are much quicker. However, building the coverage report may still take a long time.

By changing filter whitelist in phpunit/suite.xml to match the scope of your test run, you can generate coverage reports much faster.

For example:

--- a/tests/phpunit/suite.xml
+++ b/tests/phpunit/suite.xml

    <filter>
        <whitelist addUncoveredFilesFromWhitelist="true">
-           <directory suffix=".php">../../includes</directory>
-           <directory suffix=".php">../../languages</directory>
-           <directory suffix=".php">../../maintenance</directory>
-           <directory suffix=".php">../../skins</directory>
+           <directory suffix=".php">../../includes/libs</directory>
        </whitelist>
    </filter>

In case the relevant file(s) are in a large directly (e.g. /includes), you can also specify individual files:

--- a/tests/phpunit/suite.xml
+++ b/tests/phpunit/suite.xml

    <filter>
        <whitelist addUncoveredFilesFromWhitelist="true">
-           <directory suffix=".php">../../includes</directory>
+           <file>../../includes/includes/WebRequest.php</file>
        </whitelist>
    </filter>

MediaWiki-Vagrant[edit]

$ vagrant ssh
$ cd /vagrant/mediawiki/tests/phpunit/
$ sudo -u www-data php phpunit.php --wiki wiki --coverage-html ../../docs/coverage includes/MessageTest.php

You can view the coverage report at http://dev.wiki.local.wmftest.net:8080/w/docs/coverage/.

Use a shortcut:

$ alias mwpun='sudo -u www-data php phpunit.php --wiki wiki'
$ mwpun --coverage-html ../../docs/coverage includes/MessageTest.php

You may get a permissions error about www-data being unable to write to this directory. In that case, try the following:

$ alias mwpun='sudo -u www-data php phpunit.php --wiki wiki'
$ sudo rm -rf /vagrant/mediawiki/docs/coverage /tmp/coverage
$ mwpun --coverage-html /tmp/coverage includes/MessageTest.php
$ sudo mv /tmp/coverage /vagrant/mediawiki/docs/coverage

mediawiki-docker-dev[edit]

you@host:mediawiki-docker-dev$ ./bash
root@container:/var/www/mediawiki# cd tests/phpunit/
root@container:phpunit# php phpunit.php --coverage-html ../../docs/coverage includes/MessageTest.php

View the coverage report at http://default.web.mw.localhost:8080/mediawiki/docs/coverage/.

External links[edit]