This plugin allows teams to fetch the accessibility (a11y) tree and validate it for duplicates or other issues using Cypress.
To install the latest version of the plugin, run the following command:
npm install cypress-a11y-puppeteer@1.0.1
After installing the plugin, you need to add it to your cypress.config.js file.
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
},
});
The plugin adds the following tasks for accessibility tree validation:
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');
});
This task identifies duplicate element names in the accessibility tree.
cy.get('@a11yTree').then((a11yTree) => {
cy.task('findDuplicates', a11yTree).then((result) => {
cy.log(result);
});
});
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
}
});
});
});
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.
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.
This project adheres to a Code of Conduct. Please review it before participating.
Please check the Issues page for existing bugs and report new ones if needed.