Integrating WordPress Playground into the plugin development workflow

WordPress Playground is a relatively new thing that allows us to run WordPress directly in the browser – without worrying about servers, just by clicking on a link. There are various configuration options available, making that a really powerful tool we could use for various use cases.

Folks keeping an eye on the news happening in the WordPress world likely heard about the plugin preview feature introduced in the plugin directory. Engineers can now create a configuration file, a sort of “image” of how the WordPress instance should be configured. With that, users can test the plugin safely in their browsers without installing it on their live or staging websites. Engineers can adjust the configuration file to handle test data import, making it easier to demo the plugin features.

Basic example with WP-CLI demo data setup

The configuration file I’m referring to is a JSON file that follows the Blueprint API schema. Engineers can define things like preferred PHP and WordPress core versions (although users can still change these once their instance is running), plugins and themes to install, and can run WP CLI commands (which is a huge advantage).

For my Password Reset Enforcement plugin preview, I wanted to have a few test users created while the Playground instance is spun up. The blueprint.json file looks as follows:

I’ll not go into the details on all of the elements of this file, as that’s really well documented in the official documentation. What’s the most interesting here is:

  • with the networking feature set to true, the Playground instance will be able to make real external connections – e.g., download a plugin,
  • in the installPlugin step, we install the latest version of the Password Reset Enforcement plugin available on the repository,
  • in the following WP-CLI commands, we import test users with various roles,
  • at the very top, the landingPage key defines the page, which should be loaded first as soon as the Playground instance is ready.

All of that creates a great user experience (I believe!) – with a single click of a button, user gets the WordPress instance ready for tests, filled-in with necessary data. See how it works in action:

How the WordPress Playground can improve the plugin development workflow?

Now, to the main point of this article. As mentioned, there are multiple great use cases for WordPress Playground, one of which is the ability to generate previews of plugins that are still in active development (not yet released).

The benefits of this are:

  • QA team can test a feature in full separation – only changes applied in a current PR will be included in the preview,
  • feature can be tested against various versions of PHP and WordPress Core with ease,
  • there’s no need to build a complex infrastructure for running the test WordPress instances; no need for maintaining a deployment pipeline (Docker/Git/etc.) – all we need is just a link,
  • no need to pay for third-party providers of the temporary WordPress instances (although these makes perfect sense for other use cases).

The only difference against the blueprint.json file shared above is how to install the plugin. The installPlugin step can be adjusted to install the plugin from a .zip file loaded from an external URL, but I find the WP-CLI plugin install command better suitable for this task:

Take note of lines 20-23; we replaced the installPlugin step with a WP-CLI command that downloads the plugin artifact (.zip file) from a publicly available URL (the ZIP_FILE is a placeholder for a Bash script shown below) and installs it while spinning up a new Playground instance. Simple!

But that’s obviously not just a copy-paste kind of thing; you’ll need the following process changes implemented in your development workflow:

Step 1: Add or modify the CI pipeline (GitHub workflow, for example) and trigger it on every commit pushed to a Pull Request.

Step 2: Take the current state of your plugin, run all the build processes you have, and zip the result – just like you’d prepare a final artifact once your plugin is ready for release. Note: You might want to add commit hash to the plugin version and/or zip file name to avoid caching issues; for example:

Step 3: Upload that artifact to a publicly available location, for example, an S3 bucket (the file’s ACL must be set to public). This is important – otherwise, WordPress Playground won’t be able to download the package. Remember to enable CORS configuration to allow GET and HEAD methods for the origin.

Step 4. Once the artifact is uploaded, your pipeline should automatically add a comment on the Pull Request, providing a link to the WordPress Playground preview. Here’s how you can leverage GitHub CLI to do that:

To avoid ambiguity in the above code example:

  • $FILE should be dynamically filled in with the URL to the just-generated artifact,
  • $BRANCH should be the head branch of your Pull Request,
  • $BLUEPRINT_FILE should be the path to the blueprint JSON file in your repository, which is created specifically for the plugin preview feature – the one with WP-CLI for plugin installation.

Result in action:



With relatively little effort, WordPress Playground can be integrated with the plugin development workflow, providing great value to the engineering, QA, and product teams. Although this article focuses on plugin development, the same approach could be applied to other projects, too: focused on theme development or even whole websites. That’s a really great tool!

Further reading

If you’d like to find out more about this topic, below are the resources I found helpful: