Registry / testing / cypress-wp-test-utils

cypress-wp-test-utils

library1.0.0jsnpmunverified

This package, `cypress-wp-test-utils`, provides a comprehensive collection of custom Cypress commands specifically designed for robust end-to-end testing of WordPress applications. It streamlines interactions with the WordPress admin area and the Gutenberg editor, offering high-level commands such as `loginUser`, `createNewPost`, `insertBlock`, `activatePlugin`, and `clickBlockToolbarButton`. Inspired by `@wordpress/e2e-test-utils` (which targets Puppeteer), this library serves a similar purpose for Cypress users, abstracting complex WordPress-specific DOM interactions. The current stable version is 1.0.0. The project maintains a regular release cadence, primarily focusing on compatibility with new major versions of Cypress and WordPress, alongside bug fixes and new feature introductions. Its key differentiator is providing a focused, high-level API for common WordPress testing scenarios directly within a Cypress test suite, significantly reducing boilerplate and improving test readability.

testing

npm install cypress-wp-test-utils

github ↗package ↗

INSTALL

IMPORT

SIG · CYPRESS-WP-TEST-UT

cypress-wp-test-utils

testingjavascriptv1.0.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

registerWpTestCommands

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

✗ const { registerWpTestCommands } = require('cypress-wp-test-utils');

Registers all custom Cypress commands provided by the library. Should be called in `cypress/support/e2e.ts` or `cypress/support/index.js`.

config

✓ import { config } from 'cypress-wp-test-utils';

✗ import config from 'cypress-wp-test-utils';

Exports the default configuration object, which can be useful for extending or reusing default settings in custom tests. Introduced in v0.6.0.

CypressWpTestUtilsConfig

✓ import type { CypressWpTestUtilsConfig } from 'cypress-wp-test-utils';

TypeScript type definition for the configuration object, useful for type-checking when modifying or extending the library's configuration.

This quickstart demonstrates how to register and use core commands for logging into WordPress, creating a new post, and activating a plugin within a Cypress test suite. It includes best practices for handling credentials.

import { registerWpTestCommands } from 'cypress-wp-test-utils'; // In cypress/support/e2e.ts (or cypress/support/index.js) registerWpTestCommands(); // In cypress/e2e/my-wordpress-test.cy.ts describe('WordPress Post Management', () => { // Configure default credentials if not using Cypress.env // In cypress.json or cypress.config.js: // env: { // "cypress-wp-test-utils": { // "username": "testuser", // "password": "testpass" // } // } beforeEach(() => { // Ensure WordPress is accessible and log in before each test cy.visit('/wp-admin'); cy.loginUser( Cypress.env('CYPRESS_WP_USERNAME') ?? 'admin', // Use environment variable or default Cypress.env('CYPRESS_WP_PASSWORD') ?? 'password' // Use environment variable or default ); }); it('should create a new post with a title and content', () => { cy.createNewPost({ postType: 'post', title: 'Cypress Test Post - ' + Date.now(), content: 'This is the content created by a Cypress E2E test.', showWelcomeGuide: false }); cy.url().should('include', 'post.php'); cy.get('.editor-post-title__input').should('have.value', 'Cypress Test Post - ' + Date.now()); cy.get('.block-editor-block-list__layout').contains('This is the content created by a Cypress E2E test.'); cy.contains('Post published.').should('be.visible'); }); it('should activate a specific plugin', () => { cy.activatePlugin('gutenberg'); // Example: Activating the Gutenberg plugin cy.contains('Plugin activated.').should('be.visible'); cy.url().should('include', 'plugins.php'); }); });

Debug

Known issues

breakingThe `wpVersion` configuration option was removed in version 0.7.0. The library now uses XPath union operators to handle selectors across different WordPress versions dynamically, making the explicit `wpVersion` setting obsolete.

fix

Remove any `wpVersion` entries from your Cypress configuration's `env` variables (e.g., `cypress.json` or `cypress.config.js`). The functionality is now handled internally.

affects: >=0.7.0

breakingVersion 1.0.0 updated the internal XPath dependency from `cypress-xpath` to `@cypress/xpath`. While this often works seamlessly, if your project explicitly used `cypress-xpath` or had specific configurations for it, you might need to adjust.

fix

Ensure `@cypress/xpath` is installed (`npm install -D @cypress/xpath`) and registered in your `cypress/support/e2e.ts` (or `index.js`) if you require `cy.xpath()` for non-library-specific uses. No direct action is required for `cypress-wp-test-utils` commands.

affects: >=1.0.0

gotchaThis library is a collection of Cypress commands and requires Cypress as a peer dependency. It will not function without Cypress installed in your project.

fix

Install Cypress in your project: `npm install cypress --save-dev` or `yarn add cypress --dev`.

affects: >=0.1.0

gotchaThe custom commands provided by this package must be explicitly registered in your Cypress `support` file (e.g., `cypress/support/e2e.ts` or `cypress/support/index.js`) using `registerWpTestCommands()`.

fix

Add `import { registerWpTestCommands } from 'cypress-wp-test-utils'; registerWpTestCommands();` to your Cypress support file.

affects: >=0.1.0

Errors

Common errors & fixes

cy.loginUser is not a function

The Cypress custom commands from `cypress-wp-test-utils` have not been registered.

fix

Ensure `registerWpTestCommands()` is called in your Cypress support file (e.g., `cypress/support/e2e.ts` or `cypress/support/index.js`).

Error: The "wpVersion" config option is no longer supported. Please remove it from your config file.

You are attempting to use the `wpVersion` configuration option, which was deprecated and removed in version 0.7.0 of the library.

fix

Remove the `wpVersion` entry from the `cypress-wp-test-utils` section of your Cypress configuration (`cypress.json` or `cypress.config.js`). The library handles WordPress version compatibility automatically.

CypressError: `cy.xpath()` failed because it is not a registered command. Did you forget to include `cypress-xpath`?

After upgrading to v1.0.0, the package switched from `cypress-xpath` to `@cypress/xpath`. If you had custom XPath usage, the new package might not be set up.

fix

Install `@cypress/xpath` (`npm install -D @cypress/xpath`) and ensure it's imported in your Cypress support file: `import '@cypress/xpath';`.

Cannot find module 'cypress-wp-test-utils'

The package is not installed or the import path is incorrect.

fix

Ensure the package is installed: `npm install cypress-wp-test-utils --save-dev` or `yarn add cypress-wp-test-utils --dev`. Verify the import path in your code.

Upgrade

Version history

1.0.0latest on npm

Audit

Dependencies

cypressrequiredPeer dependency, this package extends Cypress with custom commands.

Agent activity

8 hits · last 30 days

node

Resources

githubhttps://github.com/tschortsch/cypress-wp-test-utils ↗

packagehttps://www.npmjs.com/package/cypress-wp-test-utils ↗