wp-now playwright testing

The purpose of this project is to quickly and easily integrate WordPress Playground environments with Microsoft's Playwright with minimal setup. It uses WordPress Playground CLI as the bridge for end-to-end testing of WordPress plugins and themes. This runs locally and does not require Docker or other global installs.

Getting Started

npm i -D wp-now-playwright-testing @wp-playground/cli

NOTE: Because the WordPress Playground is still very much in active development, @wp-playground/cli is a required dependency, rather than automatically included. This way you can define the specific version to match your project's features and compatibility needed for your project.

Usage

In its most basic form, all you have to do is import into your playwright.config.js, then get the projects and webServer output from the getPlaywrightConfig function and pass it to your Playwright config, shown below. That's it!

1. Add wp-now-playwright-testing to your Playwright config...

// playwright.config.js

import { defineConfig } from '@playwright/test'
import { getPlaywrightConfig } from 'wp-now-playwright-testing'

const { projects, webServer } = await getPlaywrightConfig()

// You can modify projects and webServer here, if needed

const config = {
	/* The rest of your config */
	// ...

	/* Configure projects for major browsers */
	projects,

	/* Run your local dev server before starting the tests */
	webServer,
}
/**
 * See https://playwright.dev/docs/test-configuration.
 */
export default defineConfig(config)

2. Run your Playwright tests with additional environment variables...

cross-env USE_VERSIONS=8468,8367,8266 USE_BROWSERS=chrome,firefox,safari npx playwright test -c playwright.config.js

This command uses cross-env to set environment variables, but you can set the environment variables any way you'd like. This will spin up multiple environments at once and test them based on your project's Playwright tests. If you don't add the environment variables, it will default to just Chrome with the latest version of WordPress, and the oldest supported version of PHP. For a better understanding of the customizations via environment variables, we'll need to go over some of the basics of how this works, as seen in the next section.

How it works

wp-now-serve

This project uses the @wp-playground/cli repo to spin up the playground environments in the background. If you go to the @wp-playground/cli docs, they show you how to use their code via npx or installed globally. However, we're not going to use it that way. Instead, we're going to programmatically use it in our JavaScript code. The binary command wp-now-serve, provided by this project, is just a wrapper and can be used the same way the @wp-playground/cli docs outline. Think of it like replacing npx @wp-playground/cli@latest server with wp-now-serve.

# Instead of...
npx @wp-playground/cli@latest server --wp=6.8 --php=8.4

# You can...
wp-now-serve --wp=6.8 --php=8.4

wp-now-serve supports the following optional @wp-playground/cli arguments:

• --php=<version>: The version of PHP to use.
• --port=<port>: The port number on which the server will listen.
• --wp=<version>: The version of WordPress to use.
• --blueprint=<path>: The path to a JSON file with the Blueprint steps (requires Node 20). See Using Blueprints for more details.

But, there is one additional optional argument (this is not supported in @wp-playground/cli):

• --versions=<versions[]>: Comma-delimited set of custom shortcodes to launch multiple environments at once

An example of a --versions value is 81651234,8266,83 which gets converted to three environments...

• 81651234 = PHP: 8.1, WordPress: 6.5 and Port: 1234
• 8266 = PHP: 8.2, WordPress: 6.6 and Port: 8266
• 83 = PHP: 8.3, WordPress: Latest and Port: 8399

...they all get spun up with that single command.

Let's explain how --versions shortcodes work...

• The first 2 digits (required) represent the PHP version
• The next 2 digits (optional) represent the WP version
  • The patch version will always be the latest patch
  • If these 2 digits are missing, it defaults to the latest version of WordPress
• The next 4/5 digits (optional) represent the port
  • Anything less than 4 or more than 5 digits will be ignored
  • If missing, defaults to PHP and WP versions concatenated
    • Missing WordPress version defaults to the number 99 (as seen above)
• RC and beta versions have exceptions
  • You must use the full version (i.e. 6.7.1-RC1) in replacement of the 3rd and 4th digits
    • e.g. 836.7.1-RC1 or 806.7-beta3
  • The release candidate or beta version MUST be the latest option available
    • If you need an outdated version of WordPress, you must use the previous --wp flag

For additional examples of how to use --versions shortcodes, see the src/wp-now.test.js test file

Integration with Playwright

Now that you understand how to spin up multiple environments at once, we can integrate into our end-to-end testing. Everything from the last section will be done for you by passing the flags as environment variables to your Playwright test config. Both environment variables and flags work, so you can decide how you want to execute your tests. Here is the list of all env/flags available.

| CLI Flag | process.env.* | Default Value | Description | |--------------------|-----------------------|--------------------------------------|--------------------------------------------------------------------| | --php | PHP | null | The version of PHP to use | | --wp | WP | null | The version of WordPress to use | | --port | PORT | null | The port number on which the server will listen | | --versions | USE_VERSIONS | 84 | PHP/WP/Port shortcodes | | --browsers | USE_BROWSERS | chrome | Browsers shortcodes | | | USE_FLAGS | null | CLI Flags to pass through to the @wp-playground/cli | | --login | LOGIN | null | Force admin login on server start | | --local-root | LOCAL_ROOT | process.cwd() | The root location of the WordPress project to use. Defaults to cwd | | --base-blueprint | BASE_BLUEPRINT_FILE | .wp-playground/blueprint.base.json | Your custom blueprint file | | --server-cmd | SERVER_CMD | wp-now-serve-playwright | Command to run for the Playwright webserver |

The command line flags are checked first, then fallback to ENV, then lastly, the default value. This project is designed to work best when most of the options are left to their default values, but it's important to note you do have the option to override things, if needed.

Additional argument info

USE_BROWSERS / --browsers

Like USE_VERSIONS/--versions, this is a comma-separated list of shortcodes. These are slugified versions of Playwright's device names. You can use the -l suffix for landscape and skip the desktop prefix. Some examples of slugified strings are...

• galaxy-s9+-l for the Galaxy S9+ landscape device
• chrome-hidpi for the Desktop Chrome HiDPI device
• For devices with multiple versions (like iphone, ipad and pixel), if no version is specified, the latest version will be used.
  • So if iPhone 15 Pro Max is the highest version of the iPhone at the time, iphone will be the same as iphone-15-pro-max This is designed so the most used shortcodes would be... chrome,firefox,safari,pixel,iphone,ipad You only need more complex shortcodes when your use case is more granular.

For more details on how shortcode works, see the src/playwright.test.js test file.

SERVER_CMD/--server-cmd

This, again, should probably not be altered. It is the command that runs when Playwright spins up a server for testing. If you want to make your own, you'll need your custom script to accept the process.env.WP_NOW variable which contains the args for the @wp-playground/cli getWpNowConfig() function.

BASE_BLUEPRINT_FILE/--base-blueprint

While you can add your own blueprint.json directly in the cli command

Cleanup script

Over time, old and outdated directories can build up on your system. It's best to clean them up from time to time. So this project comes with a script to help clean up old or outdated directories.

wp-now-clean -bp -wp -pw --simulate

| Flag | Default Value | Description | |-----------------------|---------------|------------------------------------------------------------| | --wordpress, -wp | false | Remove outdated WordPress installations | | --playwright, -pw | false | Remove outdated Playwright browser installations | | --blueprint, -wp | false | Remove old blueprint.json files stored in the $TEMP dir | | --all | false | Force delete ALL directories, even if they're not outdated | | --simulate | false | Run in simulation mode without actually deleting files |

You may want to run simulation mode --simulate first, to see what will actually get deleted.

Example scripts

Basic server commands:

{
	"scripts": {
		"serve": "wp-now-serve",
		"serve:env": "cross-env USE_VERSIONS=8165,8367,8266 wp-now-serve",
		"serve:args": "wp-now-serve --versions=8165,8367,8266"
	}
}

Cleanup commands:

{
	"scripts": {
		"clean:simulate": "wp-now-clean -wp -pw -bp --simulate",
		"clean": "wp-now-clean -wp -pw -bp"
	}
}

Customizations without ENV and CLI flags

There is a third option that is less flexible. You can configure its usage directly in the playwright.config.js file

// playwright.config.js

import { defineConfig } from '@playwright/test'
import { getPlaywrightConfig, getWpNowConfigs } from 'wp-now-playwright-testing'

await getWpNowConfigs({ versions: '8468,8367,8266' })
const { projects, webServer } = await getPlaywrightConfig({ browsers: 'chrome,firefox,safari' })

/* You can modify projects or webServer here for additional control */

const config = {
	/* Configure projects for major browsers */
	projects,
	/* Run your local dev server before starting the tests */
	webServer,
}
export default defineConfig(config)

Normally the getWpNowConfigs() function is called behind the scenes using the ENV and/or CLI flags. However, if you don't want to use it in that way, or you want to override it, you can call it directly (before calling getPlaywrightConfig() as shown above). You can also make customizations to the Playwright options here, as well. However, you may find this to be less flexible when automating different scripts.

CLI Interface

This package provides binary commands for managing WordPress Playground environments:

Binary Commands

wp-now-serve

Starts one or more WordPress Playground servers for development and testing.

# Start server with default settings
wp-now-serve

# Start server with specific PHP and WordPress versions
wp-now-serve --php=8.4 --wp=6.8

# Start multiple environments using version shortcodes
wp-now-serve --versions=8468,8367,8266

wp-now-clean

Cleans up outdated WordPress, Playwright, and Blueprint files to free up disk space.

# Simulate cleanup (see what would be deleted)
wp-now-clean -wp -pw -bp --simulate

# Clean up outdated files
wp-now-clean -wp -pw -bp

# Clean up everything (use with caution)
wp-now-clean -wp -pw -bp --all

NPX Usage

You can also use the main CLI router to access any of these commands:

# These are equivalent to the binary commands above
npx wp-now-playwright-testing serve
npx wp-now-playwright-testing clean

# Pass arguments through the router
npx wp-now-playwright-testing serve --php=8.4 --wp=6.8
npx wp-now-playwright-testing clean -wp -pw -bp --simulate

Quick recap

Install package

npm i -D wp-now-playwright-testing

Call from your Playwright config

import { defineConfig } from '@playwright/test'
import { getPlaywrightConfig } from 'wp-now-playwright-testing'

const { projects, webServer } = await getPlaywrightConfig()
const config = {
	projects,
	webServer,
}
export default defineConfig(config)

Run your Playwright tests with environment variables set

cross-env USE_VERSIONS=8367,8266,8165 USE_BROWSERS=chrome,firefox,safari USE_FLAGS="--auto-mount --login" npx playwright test

That's it, you're done!