Tag: Blueprints

Learn how to leverage WordPress Playground and Blueprints for automated end-to-end browser and performance testing.

Late last year I published a detailed tutorial for getting started with end‑to‑end performance testing in WordPress. It was accompanied by a template GitHub repository and a dedicated GitHub Action for effortlessly running performance tests with zero setup.

Getting started with end‑to‑end performance testing in WordPress

While that GitHub Action works extremely well, the zero-setup approach has two drawbacks:

1. It is not possible to configure the test environment, for example by adding demo content or changing plugin configuration
2. It is not possible to test more complex scenarios, like any user interactions (e.g. for INP)

For (2) the best alternative right now is to go with the manual approach. For (1), I have now found a solution in WordPress Playground. Playground is a platform that lets you run WordPress instantly on any device. It can be seen as a replacement for the Docker-based @wordpress/env tool.

Using Blueprints for automated testing

One particular strength of WordPress Playground is the idea of Blueprints. Blueprints are JSON files for setting up your WordPress Playground instance. In other words, they are a declarative way for configuring WordPress—like a recipe. A blueprint for installing a specific theme and plugin could look like this:

{
	"steps": [
		{
			"step": "installPlugin",
			"pluginZipFile": {
				"resource": "wordpress.org/plugins",
				"slug": "performance-lab"
			}
		},
		{
			"step": "installTheme",
			"themeZipFile": {
				"resource": "wordpress.org/themes",
				"slug": "twentytwentyone"
			}
		}
	]
}Code language: JSON / JSON with Comments (json)

Performance testing 2.0

The newly released version 2 of the performance testing GitHub Action now uses Blueprints under the hood to set up the testing environment and do things like importing demo content and installing mandatory plugins and themes. In addition to that, you can now use Blueprints for your own dedicated setup!

This way you can install additional plugins, change the site language, define some options, or even run arbitrary WP-CLI commands. There are tons of possible steps and also a Blueprints Gallery with real-world code examples.

To get started, add a new swissspidy/wp-performance-action@v2 step to your workflow (e.g. .github/workflows/build-test.yml):

steps:
  - name: Checkout
    uses: actions/checkout@v4
  
  - name: Run performance tests
    uses: swissspidy/wp-performance-action@v2
    with:
      urls: |
        /
        /sample-page/
      plugins: |
        ./my-awesome-plugin
      blueprint: ./my-custom-blueprint.json
      iterations: 5
      repetitions: 1Code language: YAML (yaml)

Then, add the blueprint (my-custom-blueprint.json):

{
  "$schema": "https://playground.wordpress.net/blueprint-schema.json",
  "plugins": [
    "performant-translations",
    "akismet"
  ],
  "steps": [
    {
      "step": "defineWpConfigConsts",
      "consts": {
        "WP_DEBUG": true
      }
    },
    {
      "step": "activatePlugin",
      "pluginName": "My Awesome Plugin",
      "pluginPath": "/wordpress/wp-content/plugins/my-awesome-plugin"
    }
  ]
}Code language: JSON / JSON with Comments (json)

And that’s it!

The GitHub Action will now use your custom blueprint to install and activate your own custom plugin and performance-lab and akismet plugins from the plugin directory.

Alongside this new feature I also included several bug fixes for things I originally planned to add but never really finished. For instance, it is now actually possible to run the performance tests twice and then compare the difference between the results.

This way, when you submit a pull request you can run tests first for the main branch and then for your PR branch to quickly see at a glance how the PR affects performance. Here is an example:

jobs:
  comparison:
    runs-on: ubuntu-latest

    steps:

    # Check out the target branch and build the plugin
    # ...

    - name: Run performance tests (before)
      id: before
      uses: ./
      with:
        urls: |
          /
          /sample-page/
        plugins: |
          ./tests/dummy-plugin
        blueprint: ./my-custom-blueprint.json
        print-results: false
        upload-artifacts: false

    # Check out the current branch and build the plugin
    # ...

    - name: Run performance tests (after)
      uses: ./
      with:
        urls: |
          /
          /sample-page/
        plugins: |
          ./tests/dummy-plugin
        blueprint: ./my-custom-blueprint.json
        previous-results: ${{ steps.before.outputs.results }}
        print-results: true
        upload-artifacts: falseCode language: PHP (php)

The result will look a bit like this:

Playground is the future

Being able to use Playground for automated testing is really exciting. It simplifies a lot of the setup and speeds up the bootstrapping, even though the sites themselves aren’t as fast (yet) as when using a Docker-based setup. However, there is a lot of momentum behind WordPress Playground and it is getting better every day. Applications like this one further help push its boundaries.

I had similar success so far when testing Playground with our WordPress performance comparison script and I think it could work well for the Plugin Check GitHub Action.

WordPress Playground clearly is the future.