WP_Mock, the WordPress API mocking layer for PHPUnit

Why unit testing WordPress code needs a mocking layer

WordPress plugin code is easy to write and awkward to test, because almost every function it calls is a global WordPress function that exists only inside a bootstrapped WordPress install. A test that loads WordPress is slow, order dependent, and coupled to whatever plugins and database happen to be present. WP_Mock exists to break that dependency.

The project describes itself as an API mocking framework, built and maintained by 10up and GoDaddy, for the purpose of making it possible to properly unit test within a WordPress project. The repository topics make the mechanism visible: mocking-library, monkey-patching, patchwork, phpunit, testing-library, unit-testing, and wordpress. In other words, it is a PHPUnit integration that stands in for WordPress functions rather than a WordPress test harness.

The audience is therefore narrow but clear: PHP developers and teams who want unit-level tests on plugin and theme code, run in a normal Composer and PHPUnit pipeline, without a database and without booting the platform.

Installing it as a Composer dev dependency

Installation is a single Composer command, and the framework is intended to live in your development dependencies rather than your production ones:

composer require --dev 10up/wp_mock

That is the whole documented install. There is no plugin to activate, no service provider to register, and no bootstrap file to wire up by hand, which is what makes the tool droppable into an existing project without restructuring it.

The version expectations are visible in the badges: PHP 7.4 and above is the stated floor, and the project is published on Packagist under the 10up/wp_mock name. The repository also ships a composer.json and a composer.lock, along with a bootstrap.php.dist file, a phpunit.xml configuration, and separate configuration for PHPStan, PHP_CodeSniffer and phpDocumentor, so the project is set up to be consumed as a library and checked by the usual static analysis tools.

What lives in the repository beyond the framework itself

The directory layout tells you what kind of project this is. Alongside the php/ directory that holds the framework code there is a tests/ directory, a features/ directory paired with a behat.yml file, and a docs/ directory that feeds the GitBook site.

The presence of behat.yml and a features directory is the most telling entry. Behat is a behaviour-driven testing tool for PHP, and it implies that WP_Mock is checked with acceptance-style feature tests in addition to unit tests, which is a different and more expensive way to test a mocking library than unit tests alone. A .gitbook.yaml at the top level confirms that the documentation is maintained on GitBook rather than in the repository alone.

For an adopter, this layout matters in one specific way: the framework is developed with the same kind of tooling you would use in your own project, and the changelog is kept as a CHANGELOG.md in the trunk branch, so you can read what changed between versions before upgrading.

Support level, release cadence and the licence question

The README states a support level, and it is not the usual hedge. It says that 10up and GoDaddy are actively working on this and that work is expected to continue for the foreseeable future, including testing with the most recent version of WordPress and PHP, and that bug reports, feature requests, questions and pull requests are welcome.

The release record backs that up in a limited way. The most recent release is 1.1.1, published on 2026-07-03, with 1.1.0 in 2025-03-12 and 1.0.1 in 2024-03-12 before it, and the last push to the trunk branch was on 2026-07-06. The version numbers move in step, and the latest release landed three days before the last push to trunk.

The licence needs care. The README badge reads BSD 3-Clause, and the repository contains a LICENSE.md file, but the licence field GitHub shows for this repository is one it cannot classify. Read LICENSE.md in the checkout and check what it actually says before you rely on the badge, and note that the project's own positioning is corporate-backed by two companies rather than a community foundation, which has implications for who carries long term maintenance.

Where a mocking framework is the wrong tool

A mocking library answers a narrow question: what do I assert when the code under test calls a WordPress function? It cannot answer whether that call is the right one, whether a hook is registered early enough, or whether a query returns what you expect from a real database. If your failure mode is a broken integration rather than a broken unit, mocking pushes the problem sideways rather than fixing it.

There is a second limit worth naming. Mocked WordPress functions behave the way the mock is configured to behave, so a test that passes tells you the plugin code followed the contract the mock encodes. When the mock itself diverges from what WordPress actually does, the test stays green and the production bug ships. That is the classic weakness of any mocking approach, and it is sharper here because the API being mocked is large and versioned.

A testing toolkit rather than a single library

WP_Mock is best understood as one piece of a toolchain rather than a standalone product. The project depends on a mocking library and on Patchwork for the monkey-patching behaviour, and it plugs into PHPUnit as the test runner. The topics list carries both unit-testing and testing-library, and the badges link to a Coveralls coverage report, so the project tracks its own test coverage as part of its CI.

That framing matters for evaluation. A team that already has PHPUnit, Composer and a static analysis setup gets a drop-in addition. A team that wants end-to-end coverage of a WordPress install gets none of that here, because a mocked API is by construction a boundary between your code and the platform.

The documentation entry point is the WP_Mock GitBook site, and the README points at the getting started page for configuration and usage. Since the repository keeps the framework in php/ and the tests in tests/, anyone extending the project, for example to add support for a WordPress function the framework does not yet mock, is working inside a conventional PHP library layout with a conventional contribution process, including a contributing guide, a code of conduct and a credits file.

Editorial conclusion

Adopt WP_Mock when you maintain a WordPress plugin or theme and want fast unit tests around code that touches the WordPress API, especially if your CI already runs Composer and PHPUnit. Skip it if you need integration coverage of real WordPress behaviour, since mocking the API deliberately does not test WordPress itself, and do not reach for it in a non-PHP stack. Before you commit, check the composer.json requirements against your project's PHP version, confirm the licence by reading LICENSE.md rather than trusting the badge, since the licence field on the repository is one GitHub cannot classify, and read the documentation at wp-mock.gitbook.io to see whether its mocking model fits the way your code calls hooks and filters.

Frequently asked questions

Official sources

1. 10up/wp_mock on GitHub
2. Issues
3. Project website
4. README
5. Releases