Home

WP Cypress is in active development, the API may be unstable until v1.0. Where possible, we will try to maintain backwards compatibility. This documentation is relevant for versions > 0.8.0.

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 [version: >=12.22.0]
• NPM
• Docker

Installation

1. Install cypress

npm i cypress --save-dev

2. Initialize cypress

cypress open

3. Install WP Cypress

npm i @bigbite/wp-cypress --save-dev

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

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

5. Add the plugin to /cypress/plugins/index.js.

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. Start WP Cypress

wp-cypress start

Configuration

Configuration options are added to the cypress configuration in cypress.json under the wp key. See the configuration schema for a full reference of available configuration.

Example Configurations

Plugins/Themes

{
 "wp": {
    "version": ["5.5"],
    "plugins": ["./path/to/plugin", "./another/path/to/plugin"],
    "themes": ["./path/to/theme"]
  }
}

Plugins/Theme with VIP

{
 "wp": {
    "version": ["5.5"],
    "plugins": ["./path/to/plugin", "./another/path/to/plugin"],
    "themes": ["./path/to/theme"],
    "muPlugins": {
       "vip": true
     }
  }
}

Plugins/Theme/Mu-plugins

{
 "wp": {
    "version": ["5.5"],
    "plugins": ["./path/to/plugin", "./another/path/to/plugin"],
    "themes": ["./path/to/theme"],
    "muPlugins": {
       "path": "./path/to/mu-plugins "
     }
  }
}

Plugins/Theme/Mu-plugins with VIP

{
 "wp": {
    "version": ["5.5"],
    "plugins": ["./path/to/plugin", "./another/path/to/plugin"],
    "themes": ["./path/to/theme"],
    "muPlugins": {
       "path": "./path/to/client-mu-plugins",
       "vip": true
     }
  }
}

WP Content

{
 "wp": {
      "version": ["5.5"],
      "wpContent": {
        "path": "./wp-content",
        "activeTheme": "twentynineteen",
        "activePlugins": ["my-plugin", "askimet"]
      },
  }
}

WP Content with VIP

{
  "wp": {
    "version": ["5.5"],
    "wpContent": {
      "path": "./wp-content",
      "activeTheme": "twentynineteen",
      "activePlugins": ["my-plugin", "askimet"]
    },
    "muPlugins": {
      "vip": true
    },
    "configFile": "./wp-content/vip-config/vip-config.php",
  }
}

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	Flags
start	Start a test environment	wp-cypress start	--no-volumes
stop	Stop the current test environment	wp-cypress stop
wp	Execute the WordPress CLI in the running container	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 or you are using a multisite with custom domains and subdomains. In this case you should specify the baseUrl for cypress.

Start a test environment by running 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.

Note: 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 wp-cypress --help or please refer to Troubleshooting for common issues.

What next?

• 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.

• Learn more about how to use wp-cypress:

  • Core Concepts
  • Seeds and Fixtures
  • Cypress Commands
  • Authentification and Users