Automated Accessibility Testing with Cypress: A Comprehensive Guide

Introduction

Accessibility is a critical aspect of web development, ensuring that all users, including those with disabilities, can interact with your web applications effectively. Automated accessibility testing helps identify and fix accessibility issues early in the development process. In this post, we’ll explore how to implement automated accessibility testing using Cypress, leveraging tools like cypress-axe to make your applications more inclusive.

Why Accessibility Matters

1. Legal Compliance: Ensures your application meets legal requirements such as the Americans with Disabilities Act (ADA) and Web Content Accessibility Guidelines (WCAG).
2. User Experience: Improves the overall user experience for all users, including those with disabilities.
3. Inclusivity: Demonstrates a commitment to inclusivity and diversity, making your application accessible to a broader audience.
4. SEO Benefits: Improves search engine optimization, as search engines favor accessible websites.

Setting Up Automated Accessibility Testing in Cypress

To perform automated accessibility testing in Cypress, we’ll use the cypress-axe plugin, which integrates the Axe accessibility engine with Cypress.

Step 1: Install Cypress and cypress-axe
First, ensure you have Cypress installed in your project. If not, you can install it using the following command:

npm install cypress --save-dev

Next, install the cypress-axe plugin:

npm install cypress-axe --save-dev

Step 2: Configure cypress-axe
Create a new file in the cypress/support directory called commands.js and add the following code to import and configure cypress-axe:

import 'cypress-axe';

Cypress.Commands.add('injectAxe', () => {
    cy.window({ log: false }).then(window => {
        let axe = require('axe-core');
        window.eval(axe.source);
    });
});

Cypress.Commands.add('checkA11y', (selector = null, options = null, violationCallback = null, skipFailures = false) => {
    cy.window({ log: false }).then(window => {
        let document = window.document;
        return axe.run(document, options).then(({ violations }) => {
            if (violations.length) {
                cy.wrap(violations, { log: false }).each(violation => {
                    let nodes = Cypress._.get(violation, 'nodes', []);
                    Cypress._.each(nodes, node => {
                        let target = Cypress._.get(node, 'target', []);
                        if (target.length) {
                            Cypress._.each(target, target => {
                                cy.wrap(target, { log: false }).then($target => {
                                    if (!skipFailures) {
                                        Cypress.log({
                                            name: 'a11y error!',
                                            message: violation.help,
                                            consoleProps: () => violation
                                        });

                                        violationCallback && violationCallback(violation);
                                    }
                                });
                            });
                        }
                    });
                });
            }
        });
    });
});

Step 3: Create Accessibility Tests
Now, let’s create a Cypress test to check the accessibility of a web page. Create a new file in the cypress/e2e directory called accessibility.spec.js and add the following code:

describe('Automated Accessibility Testing with Cypress', () => {
    beforeEach(() => {
        cy.visit('/');
        cy.injectAxe();
    });

    it('should have no detectable accessibility violations on load', () => {
        cy.checkA11y();
    });

    it('should have no detectable accessibility violations on specific elements', () => {
        cy.checkA11y('header');
        cy.checkA11y('main');
        cy.checkA11y('footer');
    });
});

In this example, we are performing accessibility checks on the entire page as well as on specific elements like the header, main content, and footer.

Customizing Accessibility Checks

You can customize the accessibility checks by providing options and configuring rules. For example, you can ignore certain rules or only run specific checks.

Example: Ignoring Specific Rules

cy.checkA11y(null, {
    rules: {
        'color-contrast': { enabled: false }
    }
});

Example: Running Specific Checks

cy.checkA11y(null, {
    runOnly: {
        type: 'tag',
        values: ['wcag2a', 'wcag2aa']
    }
});

Handling Accessibility Violations

You can handle accessibility violations by providing a callback function to log or process the violations. For example:

cy.checkA11y(null, null, (violations) => {
    violations.forEach((violation) => {
        cy.log(`${violation.id} - ${violation.description}`);
        violation.nodes.forEach((node) => {
            cy.log(`Node: ${node.target}`);
        });
    });
});

Best Practices for Accessibility Testing

1. Integrate Early: Integrate accessibility testing early in the development process to catch issues sooner.
2. Test Regularly: Run accessibility tests regularly as part of your CI/CD pipeline to ensure ongoing compliance.
3. Educate Your Team: Educate your development team on accessibility best practices and guidelines.
4. Use Manual Testing: Combine automated and manual testing to cover all aspects of accessibility, as automated tools might not catch everything.

Conclusion

Automated accessibility testing with Cypress and cypress-axe is a powerful way to ensure your web applications are accessible to all users. By integrating accessibility checks into your testing process, you can identify and fix issues early, providing a better user experience and ensuring compliance with accessibility standards. Follow the best practices outlined in this guide to make your applications more inclusive and accessible.

Happy testing!

Comments

[Sebastian Clavijo Suero]

Hi Aswani, great article about accessibility testing with Cypress! It goes over all the main concepts and practical examples.
Also I wanted to let you know that 3 weeks ago, just after your article I released a Cypress plugin called wick-a11y, that using axe-core and cypress-axe as engine, it integrates with any cypress project with almost no configuration, and generates off-the-shelf detailed reports in the Cypress runner and html reports with screenshots of the violations and how to solve them.

It's open source and available in github and npm.
This is the link in case you might be interested in having a look: github.com/sclavijosuero/wick-a11y

Cheers