• Why
• Requirements
• Installation
• Getting Started
  • CLI
  • Env
  • Cypress
  • Seeds
• API
  • Commands
  • Seeder

Cypress is designed to address the pain points of testing modern web applications. WP Cypress extends Cypress to address specific pain points developers and QA engineers face when testing WordPress [5..] applications.

We make it easier to:

• Create a WordPress environment for testing
• Seed the database with test data
• Perform WordPress specific actions when writing tests

• Yarn
• Node
• Docker
• Cypress

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. Import WP Cypress in /cypress/support/index.js

// ***********************************************************
// This example support/index.js is processed and
// loaded automatically before your test files.
//
// This is a great place to put global configuration and
// behavior that modifies Cypress.
//
// You can change the location of this file or turn off
// automatically serving support files with the
// 'supportFile' configuration option.
//
// You can read more here:
// https://on.cypress.io/configuration
// ***********************************************************

import '@bigbite/wp-cypress';

5. Update /cypress.json with your environment variables.

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

WP Cypress has been installed to your ./node_modules directory, with its binary executable accessible from ./node_modules/.bin.

The available commands are now available to run in your project root directory:

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

To start the test environment run 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.

Having trouble? Use File sharing to allow local directories on the Mac to be shared with Linux containers. See more https://docs.docker.com/docker-for-mac/#file-sharing

Once it is running there is no need to re-start it every time you run cypress. WP Cypress will start and restore the database to it's initial state between each suite of integration tests to ensure a clean slate between tests.

You can add environment variables to the wp key in the cypress.json configuration file. If this file is changed, you will need to re-run wp-cypress start to see the changes take effect.

{
  "baseUrl": "http://localhost:3000",
  "pageLoadTimeout": 30000,
  "wp": {
    "version": "5.4", 
    "port": 3000,
    "plugins": [ 
      "./"
      "./absolute/path/to/plugin"
    ],
    "themes": [
      "../themes/absolute/path/to/theme"
    ]
  }
}

In the cypress directory there a directory specfic to wp-cypress named seeds. Here lives our seeds, which we can use to populate the database with data. By default there will already be one Seed: Init. As it's name suggests, this will be ran when the container is initialised and therefore is a good place to create most data. Using the resetDB command will reset the database and run the Init seed again.

Seeds executed in the running container allowing you to perform any required logic you need to set up your environment. Alongside this there are some helpful tools to help generate dummy data.

If you wish to add more seeds, any file in the seeds directory is autoloaded to be executed at a later date using wp seed ClassName in the running container or alternatively using the seed command cy.seedDB('ClassName').

<?php

use \WP_Cypress\Seeder\Seeder;

class MySeeder extends Seeder {
	public function run() {
    $title = $this->faker->sentence();

		$this->generate->posts( [
			'post_title' => $title,
			'import_id'  => 10,
    ], 1 );
    
    $this->generate->comments( [
			'comment_post_ID' => 20,
		], 10 );
	}
}

The file's name must match the name of the class.

Now you can begin writing tests! To learn more about writing tests with cypress visit their documentation on how to Write Your First Test. This package extends cypress with some additional commands that may be useful, please refer to the API below.

\WP_Cypress\Seeder