{"id":13052,"library":"cypress-wp-test-utils","title":"Cypress WordPress Test Utilities","description":"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.","status":"active","version":"1.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/tschortsch/cypress-wp-test-utils","tags":["javascript","WordPress","cypress","command","e2e","testing","Gutenberg","editor","typescript"],"install":[{"cmd":"npm install cypress-wp-test-utils","lang":"bash","label":"npm"},{"cmd":"yarn add cypress-wp-test-utils","lang":"bash","label":"yarn"},{"cmd":"pnpm add cypress-wp-test-utils","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency, this package extends Cypress with custom commands.","package":"cypress","optional":false}],"imports":[{"note":"Registers all custom Cypress commands provided by the library. Should be called in `cypress/support/e2e.ts` or `cypress/support/index.js`.","wrong":"const { registerWpTestCommands } = require('cypress-wp-test-utils');","symbol":"registerWpTestCommands","correct":"import { registerWpTestCommands } from 'cypress-wp-test-utils';"},{"note":"Exports the default configuration object, which can be useful for extending or reusing default settings in custom tests. Introduced in v0.6.0.","wrong":"import config from 'cypress-wp-test-utils';","symbol":"config","correct":"import { config } from 'cypress-wp-test-utils';"},{"note":"TypeScript type definition for the configuration object, useful for type-checking when modifying or extending the library's configuration.","symbol":"CypressWpTestUtilsConfig","correct":"import type { CypressWpTestUtilsConfig } from 'cypress-wp-test-utils';"}],"quickstart":{"code":"import { registerWpTestCommands } from 'cypress-wp-test-utils';\n\n// In cypress/support/e2e.ts (or cypress/support/index.js)\nregisterWpTestCommands();\n\n// In cypress/e2e/my-wordpress-test.cy.ts\ndescribe('WordPress Post Management', () => {\n  // Configure default credentials if not using Cypress.env\n  // In cypress.json or cypress.config.js:\n  // env: {\n  //   \"cypress-wp-test-utils\": {\n  //     \"username\": \"testuser\",\n  //     \"password\": \"testpass\"\n  //   }\n  // }\n\n  beforeEach(() => {\n    // Ensure WordPress is accessible and log in before each test\n    cy.visit('/wp-admin');\n    cy.loginUser(\n      Cypress.env('CYPRESS_WP_USERNAME') ?? 'admin', // Use environment variable or default\n      Cypress.env('CYPRESS_WP_PASSWORD') ?? 'password' // Use environment variable or default\n    );\n  });\n\n  it('should create a new post with a title and content', () => {\n    cy.createNewPost({\n      postType: 'post',\n      title: 'Cypress Test Post - ' + Date.now(),\n      content: 'This is the content created by a Cypress E2E test.',\n      showWelcomeGuide: false\n    });\n    cy.url().should('include', 'post.php');\n    cy.get('.editor-post-title__input').should('have.value', 'Cypress Test Post - ' + Date.now());\n    cy.get('.block-editor-block-list__layout').contains('This is the content created by a Cypress E2E test.');\n    cy.contains('Post published.').should('be.visible');\n  });\n\n  it('should activate a specific plugin', () => {\n    cy.activatePlugin('gutenberg'); // Example: Activating the Gutenberg plugin\n    cy.contains('Plugin activated.').should('be.visible');\n    cy.url().should('include', 'plugins.php');\n  });\n});","lang":"typescript","description":"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."},"warnings":[{"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.","message":"The `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.","severity":"breaking","affected_versions":">=0.7.0"},{"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.","message":"Version 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.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Install Cypress in your project: `npm install cypress --save-dev` or `yarn add cypress --dev`.","message":"This library is a collection of Cypress commands and requires Cypress as a peer dependency. It will not function without Cypress installed in your project.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Add `import { registerWpTestCommands } from 'cypress-wp-test-utils'; registerWpTestCommands();` to your Cypress support file.","message":"The 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()`.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure `registerWpTestCommands()` is called in your Cypress support file (e.g., `cypress/support/e2e.ts` or `cypress/support/index.js`).","cause":"The Cypress custom commands from `cypress-wp-test-utils` have not been registered.","error":"cy.loginUser is not a function"},{"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.","cause":"You are attempting to use the `wpVersion` configuration option, which was deprecated and removed in version 0.7.0 of the library.","error":"Error: The \"wpVersion\" config option is no longer supported. Please remove it from your config file."},{"fix":"Install `@cypress/xpath` (`npm install -D @cypress/xpath`) and ensure it's imported in your Cypress support file: `import '@cypress/xpath';`.","cause":"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.","error":"CypressError: `cy.xpath()` failed because it is not a registered command. Did you forget to include `cypress-xpath`?"},{"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.","cause":"The package is not installed or the import path is incorrect.","error":"Cannot find module 'cypress-wp-test-utils'"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":""}