cypress-a11y-puppeteer

Cypress a11y puppeteer plugin

This plugin allows teams to fetch the accessibility (a11y) tree and validate it for duplicates or other issues using Cypress.

Installation

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

npm install cypress-a11y-puppeteer@1.0.1

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 { fetchA11yTree, findDuplicates } = require('./cypress/plugins/a11yPlugin');

module.exports = defineConfig({
  e2e: {
    setupNodeEvents(on, config) {
      on('task', {
        fetchA11yTree({ url, cookies, localStorageData }) {
          return fetchA11yTree(url, cookies, localStorageData);
        },
        findDuplicates(a11yTree) {
          return findDuplicates(a11yTree);
        }
      });

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

Usage

The plugin adds the following tasks for accessibility tree validation:

1. Fetch Accessibility Tree:

This command fetches the accessibility tree of a page using Puppeteer.

cy.task('fetchA11yTree', {
  url: 'https://example.com',  // URL to be tested
  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');
});

2. Find duplicates in A11y Tree:

This task identifies duplicate element names in the accessibility tree.

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

Writing Test Cases (Cucumber style)

Here's an example of how the plugin can be used in your Cypress tests:

Then('Fetches the accessibility tree with Puppeteer', () => {
    cy.url().then((currentUrl) => {
        cy.getCookies().then((cookies) => {
            const serializedCookies = JSON.stringify(cookies);

            cy.window().then((window) => {
                const localStorageData = JSON.stringify(window.localStorage);

                cy.task('fetchA11yTree', {
                    url: currentUrl,
                    cookies: serializedCookies,
                    localStorageData
                }).then((a11yTree) => {
                    cy.wrap(a11yTree).as('a11yTree');
                });
            });
        });
    });
});

Then('Validate a11y tree', () => {
    cy.get('@a11yTree').then((a11yTree) => {
        cy.task('findDuplicates', a11yTree).then((result) => {
            if (result.includes('Duplicates found:')) {
                throw new Error(result);
            } else {
                cy.log(result); // Log the result if no duplicates are found
            }
        });
    });
});

Available Tasks

fetchA11yTree: The first Then block fetches the current URL, cookies, and local storage data, and passes them to the fetchA11yTree task, which retrieves the accessibility tree from the page.

findDuplicates: The second Then block uses the findDuplicates task to validate the accessibility tree and logs the result.

Contributing

We welcome contributions from the community! Please review our Contribution Guide and adhere to our Code of Conduct when participating.

If you encounter any issues or have feature requests, please report them in our Issues section.

Code of Conduct

This project adheres to a Code of Conduct. Please review it before participating.

Reporting Issues

Please check the Issues page for existing bugs and report new ones if needed.

cypress-a11y-puppeteer