PHPUnit tests in WordPress plugins

These are the issues I encountered while setting up and writing unit tests for the WordPress plugin.

Before writing about the issues, I’ll review the configuration/requirements.

1) Installing PHPUnit globally

composer global require phpunit/phpunit:8.*

We’re installing PHPUnit 8 dot latest. Run phpunit --version to confirm it’s been installed.

2) Installing WP-CLI globally

I’ll assume that WP-CLI is already installed. Follow the official documentation if it isn’t installed already.

That’s all we’ll need globally.

3) Creating tests files for the plugin

From the WordPress root directory run the following command. Note that ‘wp-force-logout’ is the plugin slug. Replace it with yours.

wp scaffold plugin-tests wp-force-logout

4) Creating a WordPress instance to test against

From the plugin’s root directory run the following command. Note that wordpress_test is the database name you’ll want to create, root is the DB username, empty DB password, localhost is the DB_HOST, and 5.8 is the WordPress version we’re installing.

bin/ wordpress_test root '' localhost 5.8

That’s all. Now when we run the command phpunit from the plugin’s root directory. The tests should be performed for the test file tests/test-sample.php of the plugin directory. To write your tests, there’s a documentation in WordPress handbook. Here’s also the sample test example.

Now into the main topic, the issues when running the command phpunit which should actually run the tests but isn’t to be.

Issue 1

Error: The PHPUnit Polyfills library is a requirement for running the WP test suite.
If you are trying to run plugin/theme integration tests, make sure the PHPUnit Polyfills library ( is available and either load the autoload file of this library in your own test bootstrap before calling the WP Core test bootstrap file; or set the absolute path to the PHPUnit Polyfills library in a "WP_TESTS_PHPUNIT_POLYFILLS_PATH" constant to allow the WP Core bootstrap to load the Polyfills.

If you are trying to run the WP Core tests, make sure to set the "WP_RUN_CORE_TESTS" constant to 1 and run composer install before running the tests.
Once the dependencies are installed, you can run the tests using the Composer-installed version of PHPUnit or using a PHPUnit phar file, but the dependencies do need to be installed whichever way the tests are run.


PHPUnit Polyfills library is now required by WordPress tests. This is because it helps to fix the version compatibility issues we often face with WordPress. Here are more details if you’d like to check.

Add a PHPUnit Polyfills library in the plugin. Here’s one of the methods to add which is in composer.json

      "yoast/phpunit-polyfills" : "1.0.3"

Once the PHPUnit Polyfills library is available, load it. There are several methods as described in the error message above. I’ve included in the plugin’s tests directory.

your-plugin/tests/bootstrap.php, in the first line, include this library:

require dirname( dirname( __FILE__ ) ) . '/vendor/yoast/phpunit-polyfills/phpunitpolyfills-autoload.php';

Issue 2

Warning: require_once(/tmp/wordpress/wp-includes/PHPMailer/PHPMailer.php): failed to open stream: No such file or directory in C:\Users\dell\AppData\Local\Temp\wordpress-tests-lib\includes\mock-mailer.php on line 2

Fatal error: require_once(): Failed opening required ‘/tmp/wordpress/wp-includes/PHPMailer/PHPMailer.php’ (include_path=’.;C:/laragon/etc/php/pear’) in C:\Users\dell\AppData\Local\Temp\wordpress-tests-lib\includes\mock-mailer.php on line 2


If you’re on windows, go to C:\Users\{user}\AppData\Local\Temp\wordpress-tests-lib\wp-tests-config.php

In line 4, after the comment:

/* Path to the WordPress codebase you’d like to test. Add a forward slash in the end. */

define( 'ABSPATH', '/tmp/wordpress/' );

Change the absolute path to C:\Users{User}\AppData\Local\Temp/wordpress/. So, that it will be:

define( 'ABSPATH', 'C:\Users\dell\AppData\Local\Temp/wordpress/' );

Issue 3

Fatal error: Declaration of WP_UnitTestCase_Base::setUpBeforeClass() must be compatible with PHPUnit\Framework\TestCase::setUpBeforeClass(): void in C:\Users\dell\AppData\Local\Temp\wordpress-tests-lib\includes\abstract-testcase.php on line 15


This is a void conundrum. The PHP Polyfills should also fix this issue. But, if you’re still facing issues, check the version of WordPress, PHPUnit, PHPUnit Polyfills library, etc. or this is supposed to be fixed in WordPress 5.9. Here are the changes coming in WordPress 5.9 you might want to look.

There’s also a famous core trac.

Common issues while setting up PHP Unit Tests for WordPress plugins

Sanjeev Aryal

Don't bury your thoughts, put your vision into reality ~ Bob Marley.

Leave a Reply

Your email address will not be published.

Pin It on Pinterest