Add Playwright E2E tests to existing WordPress plugins

1. Set up local dev environment with wp-env
2. Write and run automated tests with Playwright (later)
3. Set up CI on GitHub Actions using matrix of PHP and WP versions (eventually)

I have begun to write Playwright E2E tests for plugins, and have many older plugins that would benefit from such E2E tests, so I hope this documents an easy way to retroactively add those tests.

I’ll be using Playwright with wp-env, which requires Docker. Previously I had used Codeception’s acceptance tests with WP Browser, but the convention in the future is undoubtedly Playwright. WP Browser is an invaluable tool for unit testing plugin classes which depend on an active WordPress instance.

Backup first – I’m not kidding, I managed to delete an entire project while writing these steps. Thankfully PhpStorm has “local history” where I was able to restore files from (and I also have BackBlaze, and usually Time Machine).

I’m going to use Checkout Rate Limiter (previous commit) in the post as an example plugin. A simple test for that will be to repeatedly place WooCommerce orders until the IP address is blocked.

Let’s start by setting up Composer and NPM to install some commonly used plugins and wp-env itself.

At this point we can start it with npx wp-env start. npx runs executables present in the node-modules/.bin directory.

% npx wp-env start
⚠ Warning: could not find a .wp-env.json configuration file and could not determine if '/Users/brianhenry/Sites/bh-wc-checkout-rate-limiter' is a WordPress installation, a plugin, or a theme.
WordPress development site started at http://localhost:8888
WordPress test site started at http://localhost:8889
MySQL is listening on port 54847
MySQL for automated testing is listening on port 54922

 ✔ Done! (in 111s 199ms)

The port and testPort are the defaults at 8888 and 8889, visit your local development site at http://localhost:8888.

Visit http://localhost:8888/wp-admin/plugins.php, log in with username/password admin / password to see the plugin available and active:

We use a .wp-env.json file in the root of the project for configuration. In it we map the plugins in the project’s wp-content/plugins directory, and configure a script to run when the environment is started.

Copy the contents of these files into the scripts just created:

The initialize-external.sh script uses wp dist-archive to create a zip of the plugin to be installed in the tests environment (:8889), i.e. we want to run the E2E tests against the plugin as it will be downloaded by users, not just as it exists in the development environment. wp dist-archive uses a .distignore file to exclude files from the archive, create one using:

Configure .wp-env.json to run the scripts, and composer.json to sync the installed plugins with .wp-env.json.

Pretty permalinks are not enabled by default, it requires both the added ~apache_modules: mod_rewrite declaration and wp-env run tests-cli call which ultimately runs the wp rewrite command to set the permalinks. Without pretty permalinks, WooCommerce REST API does not work.

Let’s install a copy of WordPress inside our project directory to use with Xdebug:

To start the environment with Xdebug enabled, use: npx wp-env start --xdebug

Now we have the environment ready to being writing tests, let’s install Playwright.

That’s the environment set up.

You can toy around with recording tests using:

npx playwright codegen -o tests/e2e-pw/example.spec.js

and running them with a very useful UI:

npx playwright test --ui &;

To stop your webserver:

npx wp-env stop

I will write another post elaborating on writing the tests themselves when I write them for Checkout Rate Limiter.