Cypress test utilities for WordPress

Collection of cypress commands to test your WordPress page. Inspired by the @wordpress/e2e-test-utils package which does the same for Puppeteer.

Installation

1. Install npm dependency

   # NPM
   npm install cypress-wp-test-utils --save-dev
       
   # Yarn
   yarn add cypress-wp-test-utils --dev

2. Register commands in your cypress project (normally in cypress/support/index.js)

   import { registerWpTestCommands } from 'cypress-wp-test-utils';
   
   registerWpTestCommands();

3. Use the commands in your tests!

Configuration

There are several options to configure the commands. These options can be defined in your cypress configuration file (normally cypress.json):

{
  "env": {
    "cypress-wp-test-utils": {
      "username": "myuser",
      "password": "supersecurepassword"
    }
  }
}

• username (string): Username which is used as the default username in the loginUser command. (Default: admin)
• password (string): Password which is used as the default password in the loginUser command. (Default: password)

List of available commands

activatePlugin

Activates a plugin.

Parameters

• slug (string) Slug of the plugin which should be activated.

clickBlockToolbarButton

Clicks a button in the toolbar of the currently selected block.

Parameters

• label (string) The text string of the button label.
• index? (number) The index of the button if multiple buttons were found with the given label. (Default: 0)

clickButton

Clicks a button.

Parameters

• label (string) The text string of the button label.
• buttonLabelType? ('ariaLabel' | 'content') The type of button label: 'ariaLabel' or 'content'. (Default: 'content')

clickElementByText

Clicks an element by a given text.

Parameters

• elementType (string) The element type (eg. 'button', 'input').
• text (string) The text of the element.
• strict? (boolean) If set to true the given text has to match exactly the text of the element (Default: false).
• index? (number) The index of the element if multiple elements were found with the given label. (Default: 0)

closeWelcomeGuide

Closes the welcome guide if displayed.

createNewPost

Creates new post.

Parameters

• object (object) Object to create new post, along with tips enabling option.
• object.postType? (string) Post type of the new post.
• object.title? (string) Title of the new post.
• object.content? (string) Content of the new post.
• object.excerpt? (string) Excerpt of the new post.
• object.showWelcomeGuide? (boolean) Whether to show the welcome guide or not. (Default: false)

deactivatePlugin

Deactivates a plugin.

Parameters

• slug (string) Slug of the plugin which should be deactivated.

ensureSidebarOpened

Ensures that the sidebar is opened (opens sidebar if closed).

getCheckboxByLabel

Gets a checkbox element by label.

Parameters

• label (string) Label of checkbox element.

getCurrentPostContent

Returns current post content as object. see: https://developer.wordpress.org/block-editor/reference-guides/data/data-core-editor/#getCurrentPost

getEditedPostContent

Returns the content of the post being edited as string.

• see: https://developer.wordpress.org/block-editor/reference-guides/data/data-core-editor/#getEditedPostContent

getInputByLabel

Gets a input element by label.

Parameters

• label (string) Label of input element.

getSelectByLabel

Gets a select element by label.

Parameters

• label (string) Label of select element.

getTextControlByLabel

Gets a TextControl element by label.

Parameters

• label (string) Label of TextControl element.

getToggleByLabel

Gets a toggle element by label.

Parameters

• label (string) Label of toggle element.

insertBlock

Opens the inserter, searches for the given term, then selects the first result that appears.

Parameters

• searchTerm (string) The text to search the inserter for.
• blockLabel? (string) The label of the block to insert.

loginUser

Performs a login with specified username and password.

Parameters

• username? (string) Username which should be used. (Default: admin)
• password? (string) Password which should be used. (Default: password)

openGlobalBlockInserter

Opens the global block inserter.

openSidebarPanelWithTitle

Opens sidebar panel with given title (if closed).

Parameters

• title (string) Title of sidebar panel to open.

searchForBlock

Search for block in the global inserter.

Parameters

• searchTerm (string) The text to search the inserter for.

selectBlockByName

Selects a block by its name.

Parameters

• name (string) Name of the block to select. (eg. 'core/paragraph')
• index? (number) The index of the block if multiple blocks were found with the given name.

selectOptionIsAvailable

Checks if a certain option in a select box is available.

Parameters

• selectLabel (string) Label of the select box.
• optionValue (string) The value of the option to search for.

setPostContent

Sets the editor content.

Parameters

• content (string) New editor content.

setTextControlValueByLabel

Sets the value of a TextControl element by its label.

Parameters

• label (string) Label of the TextControl element.
• value (string) Value to set.

toolbarOptionIsActive

Checks if a toolbar option is active.

Parameters

• toolbarLabel (string) Label of the toolbar option to check.
• buttonText (string) Text of the button to check if it's active.
• toolbarIndex? (number) The index of the toolbar option if multiple options were found with the given label.
• buttonIndex? (number) The index of the button if multiple buttons were found with the given text.

visitAdminPage

Visits a given admin page.

Parameters

• adminPath (string) Path to admin page.
• query? (string) Query string which should be added to URL.

Compatibility

• WordPress 5.7, 5.8, 5.9, 6.0, 6.1
• Node >=12
• Cypress >=5.x

Right now those commands are only compatible with WordPress 5.7, 5.8, 5.9, 6.0 and 6.1. The goal is to support further WordPress versions but since there are always a lot of changes in the editor between WordPress versions it's difficult to support all of them.

@cypress/xpath included

This package uses and includes the @cypress/xpath command. If you're using it as well in your tests you don't need to include it again.