Skip to content

Home

Jump to bottom
Paul Taylor edited this page Dec 16, 2021 · 34 revisions

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]
  • Yarn or npm
  • Docker

Installation

  1. Install cypress
yarn add cypress --dev
  1. Initialize cypress
yarn run cypress open
  1. Install WP Cypress
yarn add @bigbite/wp-cypress --dev
  1. Add the support file to /cypress/support/index.js 
import '@bigbite/wp-cypress/lib/cypress-support';
  1. Add the plugin to /cypress/plugin/index.js.
const wpCypressPlugin = require('@bigbite/wp-cypress/lib/cypress-plugin');

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

  1. Update /cypress.json with your configuration.

  2. Start WP Cypress

yarn run 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 yarn run wp-cypress start --no-volumes
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 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 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.

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

What next?

Spotted a bug or have an idea for a feature? Raise an issue

Clone this wiki locally