Cypress-puppeteer-a11y NPM

Cypress a11y plugin

This plugin allows teams to fetch the accessibility (a11y) tree using Puppeteer.

Installation

To install the latest version of the plugin, run the following command:

npm install cypress-puppeteer-a11y@{version} or
npm install cypress-puppeteer-a11y@latest

Setup

After installing the plugin, you need to add it to your cypress.config.js file.

1. Update cypress.config.js:

In your cypress.config.js file, you need to add the plugin configuration:

const { fetchA11yTreeForPage, findDuplicates, fetchA11yTreeForDialog, fetchA11yTreeForMenu } = require('cypress-puppeteer-a11y/cypress/plugins/a11yPlugin.js');

module.exports = defineConfig({
  e2e: {
    setupNodeEvents(on, config) {
      on("task", {
        fetchA11yTreeForPage({ url, cookies, localStorageData }) {
          return fetchA11yTreeForPage(url, cookies, localStorageData);
        },
        findDuplicates(a11yTree) {
          return findDuplicates(a11yTree);
        },
        fetchA11yTreeForDialog({ cookies, localStorageData, url, actions }) {
          return fetchA11yTreeForDialog({
            cookies,
            localStorageData,
            url,
            actions,
          });
        },
        fetchA11yTreeForMenu({ cookies, localStorageData, url, actions, menuSelector }) {
          return fetchA11yTreeForMenu({
            cookies,
            localStorageData,
            url,
            actions,
            menuSelector
          });
        },
      });

      // Return the updated config object
      return config;
    },
    // other config options
  },
});

Plugin Validation

To validate if the plugin is working correctly, you can run the provided validation script. This script verifies the functionality of core tasks, including fetching accessibility trees and detecting duplicates.

Steps to Run Plugin Validation

Ensure the Plugin is Set Up Correctly: Follow the setup instructions above to configure the plugin in your cypress.config.js.
Navigate to the Scripts Folder: The validation script is located in the scripts folder of your project.
Run the Validation Script:

node scripts/validateA11yPlugin.js

Example Validation Script Output

Starting Plugin Validation...

Navigating to https://en.wikipedia.org/wiki/World_history...
Fetched Cookies: [ ...cookie details... ]
Fetched Local Storage: { ...local storage details... }
Validating fetchA11yTreeForPage...
Accessibility Tree for Page: { ...tree details... }
✅ fetchA11yTreeForPage executed successfully.

Navigating to https://example.com...
Fetched Cookies: [ ...cookie details... ]
Fetched Local Storage: { ...local storage details... }
Validating fetchA11yTreeForMenu...
Accessibility Tree for Menu: { ...tree details... }
✅ fetchA11yTreeForMenu executed successfully.

Navigating to https://example.com...
Fetched Cookies: [ ...cookie details... ]
Fetched Local Storage: { ...local storage details... }
Validating fetchA11yTreeForDialog...
Accessibility Tree for Dialog: { ...tree details... }
✅ fetchA11yTreeForDialog executed successfully.

Plugin Validation Completed.

Available Tasks

The plugin adds the following tasks for accessibility tree validation:

Fetch Accessibility Tree for a Page Fetches the accessibility tree for a specified page.

cy.task('fetchA11yTreeForPage', {
  url: 'https://example.com',
  cookies: JSON.stringify(cookies), // Optional: Pass cookies if required
  localStorageData: JSON.stringify(window.localStorage) // Optional: Pass local storage data if needed
}).then((a11yTree) => {
  cy.wrap(a11yTree).as('a11yTree');
});

Find Duplicates in A11y Tree Identifies duplicate element names in the accessibility tree.

cy.get('@a11yTree').then((a11yTree) => {
  cy.task('findDuplicates', a11yTree).then((result) => {
    cy.log(result);
  });
});

Fetch A11y Tree for Dialogs Performs actions (e.g., clicking buttons) to open a dialog and fetches the accessibility tree.

cy.task('fetchA11yTreeForDialog', {
  url: 'https://example.com',
  cookies: JSON.stringify(cookies),
  localStorageData: JSON.stringify(window.localStorage),
  actions: [
    { action: 'click', selector: '#dialog-trigger' }
  ]
}).then((a11yTree) => {
  cy.wrap(a11yTree).as('a11yTree');
});

Fetch A11y Tree for Menus Performs actions to navigate to a menu and fetches its accessibility tree.

cy.task('fetchA11yTreeForMenu', {
  url: 'https://example.com',
  cookies: JSON.stringify(cookies),
  localStorageData: JSON.stringify(window.localStorage),
  menuSelector: '#menu',
  actions: [
    { action: 'click', selector: '#menu-trigger' }
  ]
}).then((a11yTree) => {
  cy.wrap(a11yTree).as('a11yTree');
});