Cypress - Plugins

Cypress - Extending with Plugins

Cypress has a powerful plugin system that allows you to extend its capabilities. Plugins can add custom commands, modify Cypress’s internal behavior, integrate with third-party services, and more. You can find a wide variety of community and official plugins at plugins.cypress.io.

Plugins typically involve two main aspects: installing them via npm/yarn, and configuring them in your Cypress setup.

General Plugin Installation and Setup

1. Installation: Most plugins are installed as development dependencies using npm or yarn.

npm install --save-dev plugin-name
# or
yarn add --dev plugin-name

2. Configuration: This varies by plugin:

• Custom Commands: Often, you’ll import the plugin in your cypress/support/e2e.js file (or cypress/support/commands.js if you’ve structured it that way). Example: import 'cypress-plugin-name/commands'; or require('cypress-plugin-name/commands');.
• Node-Level Tasks: Some plugins require configuration within the setupNodeEvents function in your cypress.config.js (or cypress.config.ts) file. This allows plugins to tap into Node.js capabilities during test execution (e.g., interacting with a database, modifying webpack config for component testing).

Commonly Used Plugins and Examples

1. File Upload (cypress-file-upload)

For testing file upload functionality.

Installation: npm install --save-dev cypress-file-upload

Setup: Add import 'cypress-file-upload'; to cypress/support/e2e.js.

Usage Example:

cy.get('input[type="file"]').attachFile('path/to/your/fixture/file.json');

2. XPath Support (@cypress/xpath)

Adds XPath selector capabilities to Cypress.

Installation: npm install --save-dev @cypress/xpath

Setup: Add require('@cypress/xpath'); to cypress/support/e2e.js.

Usage Example:

cy.xpath('//button[contains(., "Submit")]').click();

3. Interacting with iframes (cypress-iframe)

Provides commands for easier interaction with elements inside iframes.

Installation: npm install --save-dev cypress-iframe

Setup: Add import 'cypress-iframe'; or require('cypress-iframe'); to cypress/support/e2e.js.

Usage Example:

cy.frameLoaded('#my-iframe');
cy.iframe('#my-iframe').find('button#submit-in-iframe').click();

4. Visual Regression Testing (e.g., cypress-image-snapshot or Applitools/Percy)

Plugins like cypress-image-snapshot (for local comparison) or cloud-based services like Applitools Eyes or Percy allow you to capture screenshots and compare them against baselines to detect visual changes.

Installation (for cypress-image-snapshot): npm install --save-dev cypress-image-snapshot

Setup: Requires adding commands to cypress/support/e2e.js and potentially configuring setupNodeEvents in cypress.config.js.

// In cypress/support/commands.js or e2e.js
import { addMatchImageSnapshotCommand } from 'cypress-image-snapshot/command';
addMatchImageSnapshotCommand();

// In cypress.config.js
const { addMatchImageSnapshotPlugin } = require('cypress-image-snapshot/plugin');

module.exports = defineConfig({
  e2e: {
    setupNodeEvents(on, config) {
      addMatchImageSnapshotPlugin(on, config);
      // ... other node event listeners
    },
  },
});

Usage Example:

cy.get('.my-component').matchImageSnapshot('component-name');

5. Accessibility Testing (e.g., cypress-axe)

Integrates Axe-core for automated accessibility testing.

Installation: npm install --save-dev cypress-axe axe-core

Setup: Add import 'cypress-axe'; to cypress/support/e2e.js.

Usage Example:

cy.visit('/my-page');
cy.injectAxe();
cy.checkA11y(); // Checks the entire page
cy.checkA11y('.specific-component', { /* options */ }); // Checks a specific component

Important Notes:

• Always refer to the specific plugin’s documentation for the most up-to-date installation and configuration instructions.
• The cypress.config.js file is the central place for Cypress configuration, including plugin setup that involves Node.js capabilities.
• The cypress/support/e2e.js file is executed before each spec file and is ideal for importing custom commands or global configurations.

Further Reading:

• Cypress Plugins Guide
• Official Cypress Plugins Directory