PHP: PHPUnit

PHPUnit is the official testing framework chosen by the coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. team to test our PHPPHP The web scripting language in which WordPress is primarily architected. WordPress requires PHP 5.6.20 or higher code.

Step 1: Check out the test repository.

The WordPress tests live in the core development repository, available via SVNSVN Subversion, the popular version control system (VCS) by the Apache project, used by WordPress to manage changes to its codebase. at:

svn co https://develop.svn.wordpress.org/trunk/ wordpress-develop
cd wordpress-develop

Or GitGit Git is a free and open source distributed version control system designed to handle everything from small to very large projects with speed and efficiency. Git is easy to learn and has a tiny footprint with lightning fast performance. Most modern plugin and theme development is being done with this version control system. https://git-scm.com/.:

git clone git://develop.git.wordpress.org/ wordpress-develop
cd wordpress-develop

Step 2: Set up a config file.

Copy wp-tests-config-sample.php to wp-tests-config.php, and enter your database credentials. Use a separate database.

There are several different ways of running the PHPUnit tests. It’s up to you to choose whichever workflow suits you best.

Some workflows require more set-up than others, when in doubt, we recommend you start with the Docker workflow as that will do most setup for you.

1. Docker container
2. Composer
3. PHPUnit PHAR file with Composer available
4. PHPUnit PHAR file without Composer

Step 1: Install and then start Docker

Step 2: Install NPM

Step 3: Make sure you are in the root directory of where you installed WordPress

Step 4: Run from the command-line:

npm install
npm run build:dev
npm run env:start
npm run env:install

Running the tests

Once the docker container is set up and provisioned, you can run the tests from the command-line: npm run test:php.

If you want to pass additional command-line arguments to PHPUnit, you will need to add an extra double-dash separator between the NPM command and the extra PHPUnit arguments to get NPM to pass them onto PHPUnit.

Step 1: Install Composer

Step 2: Make sure you are in the root directory of where you installed WordPress

Step 3: Run from the command-line: composer update -W

Running the tests

Once the Composer dependencies are installed, you can run the tests from the command-line: vendor/bin/phpunit.

Step 1: Install PHPUnit Phar

Install the PHAR which is appropriate for your PHP version. Installation instructions can be found in the PHPUnit manual or on the PHPUnit website.

Step 2: Install Composer

Step 3: Make sure you are in the root directory of where you installed WordPress

Step 4: Install Composer dependencies

Run from the command-line: composer update -W

Running the tests

Once the PHPUnit PHAR and the Composer dependencies are installed, you can run the tests from the command-line: [path/to/]phpunit.

This method is most suitable if you want to install PHPUnit and the PHPUnit Polyfills globally and run tests in multiple directories.

Step 1: Install PHPUnit PHAR

Install the PHAR which is appropriate for your PHP version. Installation instructions can be found in the PHPUnit manual or on the PHPUnit website.

Step 2: Install PHPUnit Polyfills

Typically, you would clone the GitHub repository:

git clone git@github.com:Yoast/PHPUnit-Polyfills.git [target/path]

Step 3: Define path to Polyfills

Once the Polyfills are installed, tell the WordPress test bootstrap where to find them by passing the path via a WP_TESTS_PHPUNIT_POLYFILLS_PATH constant.

This constant can be declared in the phpunit.xml[.dist] file like this:

<php>
     <const name="WP_TESTS_PHPUNIT_POLYFILLS_PATH" value="path/to/yoast/phpunit-polyfills"/>
</php>

or can be declared as a PHP constant in the wp-tests-config.php file.

Running the tests

Once the PHPUnit PHAR and Polyfills are installed, you can run the tests from the root directory of your WordPress install via the command-line: [path/to/]phpunit.

You should see output that looks roughly like the following:

...........................................................    59 / 12524 (  0%)
...........................................................   118 / 12524 (  0%)
...........................................................   177 / 12524 (  1%)
...........................................................   236 / 12524 (  1%)
...........................................................   295 / 12524 (  2%)
.......SS..................................................   354 / 12524 (  2%)
...
........................................................... 12449 / 12524 ( 99%)
........................................................... 12508 / 12524 ( 99%)
................                                            12524 / 12524 (100%)

Time: 01:46.744, Memory: 235.10 MB

OK, but incomplete or skipped tests! 
Tests: 12524, Assertions: 57712, Skipped: 56.

What each symbol means:

• . – Each dot signifies one “test” that passed.
• S means a test was skipped. This usually means that the test is only valid in certain configurations, such as when a test requires Multisite or a certain PHP extension.
• F means a test failed. More output will be shown for what exactly failed and where.
• E means a test failed due to a PHP error, warning, or notice.
• R means a test is marked as “risky”. What will be marked as risky, very much depends on the configuration in the phpunit.xml.dist file. This can be tests which are particularly slow or don’t perform assertions.
• I means a test was marked as incomplete, i.e. not yet implemented.

To run an individual class, use --filter with the name of the class:

phpunit --filter Tests_Formatting_wpParseStr

The --filter option in PHPUnit is very flexible and has lots of supported options. Please see the PHPUnit Manual for more examples.

To run a group of tests – defined by @group in code comments:

phpunit --group dependencies
phpunit --group themes

You may also combine groups: (Depending on your platform you may have to wrap the groups in double quotes)

phpunit --group shortcode,17657,6562,14050

...
OK (229 tests, 417 assertions)

To view all groups:

phpunit --list-groups

To see information about skipped and incomplete tests, use --verbose:

phpunit --group wpdb --verbose

 
There was 1 skipped test: 
1) Tests_DB::test_charset_switched_to_utf8
This test requires utf8mb4 to not be supported.

tests/phpunit/tests/db.php:1332

By default, the AJAX tests (tests written for core’s use of wp-admin/admin-ajax.php) are not run. To run these:

phpunit --group ajax

To run the tests under multisite, you must switch to the multisite.xml configuration file:

phpunit -c tests/phpunit/multisite.xml

Additionally, you can npm run grunt phpunit and run PHPUnit tests, including the ajax and multisite tests.

Rather than having to switch to a terminal and manually run a test group repeatedly while working on a patch, you can keep it running continuously. Whenever you save any file, the group will run again automatically. This lets you instantly know when a change you’ve made breaks a test, or causes it to pass.

To run PHPUnit tests and all other watch tasks, use:

npm run grunt watch -- --phpunit --group={testgroup}

To run only the PHPUnit watch task, use:

npm run grunt watch:phpunit -- --group={testgroup}

Run multiple groups by comma-separating them:

npm run grunt watch:phpunit -- --group=community-events,privacy

You can speed up the suite in some cases by defining the WP_TESTS_SKIP_INSTALL environment variable to 1, so that the suite will skip the install step. While this shouldn’t be used for full test runs, it’s useful for saving time when running small groups of tests.

WP_TESTS_SKIP_INSTALL=1 phpunit --group=privacy

We’ve written a guide for getting started writing PHPUnit tests for WordPress.

There are three primary ways to contribute:

Write tests for a reported bug. A great way to contribute is to write tests that demonstrate an existing bug report. The core developers are reluctant to consider patches for many sensitive areas in core without test coverage. Well-written tests can help confirm that a patch fixes a problem without side effects, and can prevent any regressions from occurring in the future. When tests are particularly needed or desired for a ticket to proceed, they receive the needs-unit-tests workflow keyword. You can submit tests for existing tickets directly on the WordPress core Trac. Bonus points for submitting a bug report with a test case included.

Write new tests to improve our code coverage. Many areas of WordPress do not have adequate test coverage. Pick a function, class, or component and write tests for it. You can submit these tests on the WordPress Trac.

Fix or improve our existing test cases. There are many opportunities for improvement in the existing tests. Some of them are ancient and others are slow or fragile. Some do not tests well in multisite or under certain conditions. Some individual tests try to test too much, and could be improved by using data providers, dependencies, and more narrow assertions.

Unit tests for JavaScript code are currently much more limited in WordPress Core in comparison to PHP unit tests. For more information on JS unit tests, see the Make/Core post or the QUnit section of this Handbook.

• PHPUnit Manual
• PHPUnit on Github

Last updated: April 20, 2023