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. Please ensure your machine has the following requirements installed.

• Node
• Yarn or npm
• 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.

7. Initialize WP Cypress

yarn run wp-cypress start

Configuration

Configuration options are added to the cypress configuration in cypress.json under the wp key.

Name	Description	Example	Type(s)
version	The version(s) of WordPress to run tests against.	["5.3.2", "5.4"]	Array, String
mu-plugins	Relative path to an mu-plugin directory	"./mu-plugins"	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
timezone	The timezone of the WordPress install.	"Europe/London"	String
port	The primary port number to use for the environment.	3000	Number

Example Configuration

Tip! There is no need to define a baseURL, as explained here in the cypress documentation. WP Cypress knows where to look when running your tests.

cypress.json

{
  "pageLoadTimeout": 30000,
  "wp": {
    "version": ["5.3.2", "5.4"],
    "plugins": [
      "./plugins/*"
    ],
    "themes": [
      "./theme"
    ],
    "config": {
      "WP_DEBUG": false
    }
  }
}

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. Alternatively, you may wish to read WP Cypress's core concepts to learn about how you can leverage Seeds to handle any set up.

Getting Started

Once installed, WP Cypress is executable from ./node_modules/.bin. These 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"

By default, WP Cypress will run on port 80 and be available to access at http://localhost unless a custom port number is specified in the configuration options. 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, subsequent builds will be quicker.

If you make a change to the configuration, you will need to re-run wp-cypress start and restart cypress for the changes to take effect.

Having Trouble?

Try running yarn run wp-cypress --help or please refer to Troubleshooting for common issues.

What next?

You can now start writing tests! If you're new to Cypress, the Cypress documentation is a great place to start learning about how to write tests in Cypress.