Home

WP Cypress is in active development, the API may be unstable until v1.0. Where possible, we will try to maintain backwards compatibility.

Requirements

WP Cypress is an npm package that is designed to be installed on a per project basis. Before installing, ensure you have the following installed on your machine:

• Node
• Yarn
• Docker
• Composer

Installation

1. Install cypress

yarn add cypress --dev

2. Initialize cypress

yarn run cypress open

3. Install WP Cypress

yarn add @bigbite/wp-cypress --dev

4. Add the support file to /cypress/support/index.js

import '@bigbite/wp-cypress/lib/cypress-support';

5. Add the plugin to /cypress/plugin/index.js. It is important the default cypress plugin function is async and it returns the value of wpCypressPlugin.

const wpCypressPlugin = require('@bigbite/wp-cypress/lib/cypress-plugin');

module.exports = async (on, config) => {
  return wpCypressPlugin(on, config);
}

6. Update /cypress.json with your configuration.

{
  "pageLoadTimeout": 30000,
  "wp": {
    "version": ["5.3.2", "5.4"],
    "timezone": "Europe/London",
    "plugins": [
      "./"
    ],
    "themes": []
  }
}

Getting Started

Once installed, WP Cypress is executable from ./node_modules/.bin. The available commands are now available to run in your project root directory:

Name	Description	Example
start	Start a test environment	yarn run wp-cypress start
stop	Stop the current test environment	yarn run wp-cypress stop
wp	Execute the WordPress CLI in the running container	yarn run wp-cypress wp "cli version"

Stuck? Try running yarn run wp-cypress --help

Start a test environment by running yarn run wp-cypress start in your project root directory. This may take a while as it builds and starts a new docker container. However, you only need to run this once. This commands also acts as a restart, firstly removing any containers and volumes before starting the docker container.

Once it is running there is no need to re-start it every time you run cypress. WP Cypress will handle resetting the environment between each suite of integration tests.

Configuration

Configuration options are added to the cypress configuration in cypress.json

Name	Description	Example	Type(s)
version	The version(s) of WordPress to run tests.	["5.3.2, "5.4"]	Array, String
timezone	The timezone of the WordPress install.	"Europe/London"	String
plugins	Relative path(s) to a plugin file or directory, supports globbing.	["./plugins/*"]	Array
themes	Relative path(s) to a theme directory, supports globbing. The first theme in the array will be activated.	["./"]	Array
config	Config variables added to wp-config.php	{ "WP_DEBUG": false }	Object

Additional Configuration

When testing plugins and themes, there may be additional configuration and set up that is required to test certain requirements or features. A common solution to this is to create a plugin that handles this and ensure it is installed by adding it to the plugins configuration array.