Developer · Guide
How to Test WordPress Plugins With PHPUnit

Short answer
To test a WordPress plugin with PHPUnit, run wp scaffold plugin-tests to generate the test files, then run bin/install-wp-tests.sh to build a test database. Write test methods that start with test_ in the tests folder, and run phpunit from the plugin folder. Match the PHPUnit version to your WordPress and PHP versions first.
Key takeaways
- wp scaffold plugin-tests generates the test files, the install script, and a CI config for your plugin.
- WordPress 7.1 uses PHPUnit 9 on PHP 7.4 through PHP 8.5, as of November 2026.
- Test method names must start with test_, and fixture methods must use snake_case such as set_up().
- The install script deletes all data in the test database, so use a fresh database name.
- The PHPUnit Polyfills library lets tests written for PHPUnit 9 run on older PHPUnit versions.
What does testing a WordPress plugin with PHPUnit mean?
Testing a WordPress plugin with PHPUnit means writing small checks that run your plugin code and confirm it behaves as you expect.
Each check is a test method that calls a function from your plugin and compares the result with the value you expect. When the values match, the test passes; when they differ, the test fails and shows you what went wrong.
The WordPress test suite uses PHPUnit to run its own PHP tests. Make WordPress Core states that the WordPress PHPUnit test suite holds thousands of automated tests (checked November 2026).
Plugin tests that load WordPress are really integration tests. Make WordPress states that they test the link between a plugin or theme and WordPress core, while a strict unit test would not load WordPress at all (checked November 2026).
What do you need before you start?
You need a local WordPress install, WP-CLI, PHPUnit, and a plugin with code you can call from a test.
Install WP-CLI first, because it creates the test files for you. The scaffold command needs a WordPress install to work from, so set one up locally before you start.
Install PHPUnit through Composer as a development dependency of the plugin. The version you need depends on your PHP and WordPress versions, which the next section covers.
Use a separate database for tests. The install script warns that all data in the test database will be deleted, so never point it at a live or shared database.
A guide on how to create a WordPress plugin covers the plugin structure the tests will load, and you need a local WordPress install to run the suite against.
Which PHPUnit version matches your WordPress version?
Match the PHPUnit version to your WordPress and PHP versions using the core compatibility table, because the wrong pairing will not run.
WordPress 7.1 works with PHPUnit 9 on PHP 7.4 through PHP 8.5. Make WordPress Core lists PHPUnit 9 for WordPress 7.1 on every PHP version from 7.4 to 8.5 (checked November 2026).
WordPress 7.0 dropped support for PHP 7.2 and 7.3, and with them PHPUnit 8. Make WordPress Core records that change in its list of supported version changes (checked November 2026).
| WordPress | PHP | PHPUnit |
|---|---|---|
| 7.1 | 7.4 to 8.5 | 9 |
| 7.0 | 7.4 to 8.5 | 9 |
| 6.9 | 7.2 to 8.4 | 9, or 8 on PHP 7.2 |
| 6.8 | 7.2 to 8.4 | 9, or 8 on PHP 7.2 |
| 6.6 | 7.0 to 8.3 | 9, or 8 on PHP 7.0 |
| 6.5 | 7.0 to 8.3 | 9, 8, 7, or 6 by PHP version |
| 5.9 | 7.4 to 8.1 | 9, 8, or 7 by PHP version |
WordPress 5.9 added the PHPUnit Polyfills library as a dependency. Make WordPress Core states that the polyfills let the tests run on the most fitting PHPUnit version for each PHP version (checked November 2026).
The polyfills library lets you write tests with the PHPUnit 9 feature set and still run them on older PHPUnit versions. Make WordPress Core states that as of WordPress 5.9, all assertions from PHPUnit 9 can be used in the WordPress test suite (checked November 2026).
PHPUnit is the testing tool behind the suite, and its site lists the supported versions for each release. GitHub hosts the polyfills library, which you add through Composer as yoast/phpunit-polyfills (checked November 2026).
A guide on which PHP version to use for WordPress helps you pick a PHP version that matches your host before you choose the PHPUnit version.
How do you scaffold the test files?
Run wp scaffold plugin-tests from the WordPress root to generate the test files for your plugin.
Change into the WordPress install folder, then run the command with your plugin slug:
wp scaffold plugin-tests my-plugin
Developer.WordPress.org states that the command generates phpunit.xml.dist, a CircleCI config file, bin/install-wp-tests.sh, tests/bootstrap.php, tests/test-sample.php, and a PHP_CodeSniffer rules file (checked November 2026).
| File | What it does |
|---|---|
| phpunit.xml.dist | PHPUnit settings, including where to find tests |
| tests/bootstrap.php | Loads WordPress and activates your plugin for the run |
| tests/test-sample.php | A sample test file you can copy and change |
| bin/install-wp-tests.sh | Sets up the WordPress test suite and test database |
| .circleci/config.yml | Runs the tests on CircleCI after each push |
| .phpcs.xml.dist | Code style rules for PHP_CodeSniffer |
Use the --ci flag to pick a different service. Developer.WordPress.org states that the default is CircleCI, with GitLab, Bitbucket, and GitHub as options (checked November 2026).
The bootstrap file looks for the WP_TESTS_DIR environment variable to find the test suite. Developer.WordPress.org states that the install script sets that path up for you (checked November 2026).
How do you set up the test database?
Run bin/install-wp-tests.sh with a test database name, user, password, host, and WordPress version to build the test install.
Move into your plugin folder and run the script:
bash bin/install-wp-tests.sh wordpress_test root '' localhost latest
Make WordPress states that the script installs a copy of WordPress in the /tmp folder and creates the database used while the tests run (checked November 2026).
The five arguments set up the test database. Make WordPress states that wordpress_test is the database name, root is the MySQL user, the empty quotes are the password, localhost is the host, and latest is the WordPress version (checked November 2026).
All data in that database will be deleted when the tests run. Use a fresh database name that holds nothing you care about, and never use the name of a live database.
You can run the script more than once without errors. Make WordPress states that it will not overwrite files that already exist (checked November 2026).
How do you write your first test?
Create a test file in the tests folder with a class that extends WP_UnitTestCase and a method whose name starts with test_.
Test method names must begin with test_. Make WordPress Core states that methods without that prefix will not run, and that test names should use snake_case (checked November 2026).
Here is a small test for a plugin function that formats a price:
<?php
class My_Plugin_Test extends WP_UnitTestCase {
public function test_format_price_adds_currency_symbol() {
$this->assertSame( '$10.00', my_plugin_format_price( 10 ) );
}
public function test_format_price_handles_zero() {
$this->assertSame( '$0.00', my_plugin_format_price( 0 ) );
}
}
Each test calls the plugin function and checks the result with an assertion. assertSame checks that the value and the type both match, so a string '10' would fail against the number 10.
Put one idea in each test method. A test that checks one thing gives a clear failure message, while a test that checks five things hides which one broke.
Use the snake_case fixture methods when your tests need setup or cleanup. Make WordPress Core states that set_up(), tear_down(), and the other snake_case methods must be used in the WordPress test suite for cross-version support (checked November 2026).
When you write a set_up() method, call parent::set_up() as its first line. Make WordPress Core states that this first-line call is critical (checked November 2026).
How do you run the tests and read the results?
Run phpunit from your plugin folder, then read the summary line to see how many tests passed, failed, or were skipped.
phpunit
PHPUnit finds the tests through phpunit.xml.dist and runs every test file it finds under the tests folder. The sample test in tests/test-sample.php runs first, so you can check the setup works before you write your own tests.
A passing run ends with a line such as OK, followed by the count of tests and assertions. A failing run names the test, shows the expected and actual values, and prints the file and line where the check failed.
Run one test file on its own while you work on it:
phpunit tests/test-my-plugin.php
Fix the code or the test, then run the suite again. A test that fails after a code change is doing its job: it caught a change in behavior before your users did.
How do you test code that uses the database?
Use the WordPress test factories to create posts, users, and terms inside the test database, then check what your plugin does with them.
The test suite ships with factories for posts, users, comments, terms, and more. Create the data your plugin needs at the start of the test, run the plugin code, and check the result.
public function test_plugin_counts_published_posts() {
$this->factory->post->create_many( 3 );
$this->assertSame( 3, my_plugin_count_posts() );
}
Each test starts with a clean database state, so data from one test does not leak into the next. Create only the rows the test needs, and keep the setup short.
Test the failure paths too. Check what the plugin does when a post is missing, when a user has no rights, and when an option holds no value.
A guide on how to check a plugin for vulnerabilities covers the security checks that pair well with database tests, such as checking that untrusted input is cleaned before use.
How do you run tests on every commit?
Add the CI config the scaffold generated, push it to your repo, and let the service run phpunit after each commit.
The scaffold writes a config file for the CI service you picked, with CircleCI as the default. Commit that file with the test files, and the service runs the suite on every push.
A guide on how to deploy WordPress with GitHub Actions covers the GitHub side of that setup, including the workflow file that runs checks on each pull request.
Keep the CI run fast. A suite that takes ten minutes gets ignored, while a suite that takes one minute runs on every change.
When a test fails in CI but passes on your computer, check the versions first. A different PHP or WordPress version in CI is the most common cause, and the compatibility table in this guide shows which pairings work.
What mistakes should you avoid?
Avoid running tests against a live database, writing tests that depend on each other, and testing only the happy path.
Running the suite against a live database deletes its data. The install script is clear that all data in the test database will be deleted, so use a throwaway database name.
Tests that depend on each other fail in confusing ways. Each test should set up its own data and pass on its own, in any order.
Testing only the happy path leaves the faults users hit first. Add tests for empty input, missing posts, and wrong user roles, not just the case where all goes well.
Skipping the polyfills library breaks the suite on older PHPUnit versions. Make WordPress Core states that the test bootstrap throws an error when the PHPUnit Polyfills are missing or too old (checked November 2026).
A guide on how to profile WordPress performance with Xdebug covers the next step when a test shows that a function is slow, rather than wrong.
Frequently asked questions
Can I run plugin tests against my live database?
No. The install script deletes all data in the test database, so use a fresh database name that holds nothing you care about. Never point the script at a live database or a shared database.
Why does my test method not run?
A test method name must start with test_ or PHPUnit will not run it. Method names should use snake_case, such as test_format_price_adds_currency_symbol, and each method should check one idea.
Are plugin tests unit tests or integration tests?
They test the link between your plugin and WordPress core, because they load WordPress to run. A strict unit test would not load WordPress at all, but the scaffold approach is the standard way to test plugins.
Can I run the tests automatically on every commit?
Yes. The scaffold writes a config file for CircleCI by default, and you can pick GitHub, GitLab, or Bitbucket with the --ci flag. Commit the file, and the service runs the suite after each push.
How do I run tests on more than one PHPUnit version?
Add yoast/phpunit-polyfills through Composer. The polyfills library lets you write tests with the PHPUnit 9 feature set and run them on older PHPUnit versions, and the test bootstrap throws an error when it is missing.
Sources
- wp scaffold plugin-tests - WP-CLI Command WordPress Developer Resources
- Plugin Integration Tests Make WordPress
- PHPUnit Compatibility and WordPress Versions Make WordPress Core
- Writing PHP Tests Make WordPress Core
- PHPUnit PHPUnit
- PHPUnit Polyfills GitHub
- Requirements WordPress.org
Is your product missing, or something out of date?
Tell us what to add or correct. We read every note and reply when we need a source. A message does not buy a ranking.
Thanks — we review requests within 3 business days.
Related guides
About the editors
Researched from the primary sources listed above and checked against our editorial rules before publishing.


