WP Tester first beta version

Over the past two months, I’ve been worked on WP Tester, a new tool for testing WordPress projects that focuses on making integration and matrix testing easy, without local dependencies.

If you maintain a plugin, theme, or site, please give it a try! The setup is quick and easy, especially if you already use PHPUnit for testing.

Try it

npx @wp-tester/cli setup
npx @wp-tester/cli test

If you find any issues or would like to suggest features, please comment here or open a GitHub issue.

What’s in the beta

The project is still in an early beta. It’s rough around the edges and lacks many features.
But it enables running PHPUnit tests in multiple environments, including different PHP and WordPress versions.

Because WP Tester uses Playground, it enables you to set up the environment any way you want via Blueprints and mounts.

For the first version, we focused on PHPUnit. With WP Tester unit tests, you won’t need to run MySQL locally or set up the WordPress test library. It will do all of that for you.

If you want to take your tests a step further and stop mocking WordPress features, switch to integration tests. Instead of requiring the WordPress test library, integration tests run inside WordPress, enabling you to test network requests, compatibility with WordPress, and other plugins or themes.

Setup

The setup command (npx @wp-tester/cli setup) will guide you through setting up your project, and if you have a typical plugin or theme, it should be ready in seconds.

The result of the setup is a wp-tester.json file that will be used to configure environments and run tests.

If you have a more complex setup, you should be able to configure it using mounts and Blueprints.
For example, you can install plugin dependencies from WordPress.org or local files.

We were even able to run WordPress core PHPUnit tests using the wp-tester.json configuration file.

{
  "$schema": "https://raw.githubusercontent.com/bgrgicak/wp-tester/trunk/packages/config/src/schema.json",
  "environments": [
    {
      "name": "Latest WordPress and PHP",
      "blueprint": {
        "preferredVersions": {
          "php": "latest",
          "wp": "latest"
        }
      }
    }
  ],
  "tests": {
    "wp": true,
    "plugin": "sqlite-database-integration",
    "phpunit": {
      "phpunitPath": "vendor/bin/phpunit",
      "configPath": "phpunit.xml.dist",
      "testMode": "unit",
      "bootstrapPath": "tests/bootstrap.php"
    }
  },
  "projectHostPath": ".",
  "projectType": "plugin"
}

Known limitations

• WP Tester is slower to run tests from native PHPUnit because it runs inside Playground, but it’s much faster than spinning up a Docker environment (or similar).
• Existing PHPUnit tests that rely on the wordpress-tests-lib won’t work in integration test mode. You either need to modify your tests or create separate integration tests.
• Some common tester features like filtering tests are still missing, but you can pass -- and after that pass any PHPUnit argument just like with native PHPUnit.

What’s next

• Address testing feedback
• Improve smoke tests by adding site health checks
• Add support for regression testing (similar to the Cross fit tool)
• Document how to use WP Tester’s runtime in any JS-based testing tool
• Add end-to-end test support (with Playwright)
• Add Vitest support for JS-based integration testing (similar to this tutorial)
• Support wp-tester.js for more complex configurations
• Interactive test result output for drilling down into failures