Using automated accessibility tests in Cypress

1. Context

Cypress and the Cypress-axe plugin make it very easy to check any web page (in any state) for accessibility issues that can be detected automatically.

It uses Deque’s Axe accessibility issues checker tool under the hood, which is also available as a browser extension. A test will fail if there’s any Web Content Accessibility Guideline (WCAG) 2.1 AA failure.

Note: Automated accessibility testing tools can only detect about 30% of WCAG 2.1 AA issues. So manual testing is still essential.

2. Using automated accessibility in Cypress

2.1. A custom Cypress command to easily detect and log issues: cy.checkForDetectableAccessibilityIssues

On the Kooth engineering team we’ve create a custom Cypress command that makes it easy to detect and log issue. You can find that custom command here.

It’s just a simple helper function built on top of cypress-axe (so also need to install cypress-axe as a development dependency).

2.2. Using cy.checkForDetectableAccessibilityIssues

You can call cy.checkForDetectableAccessibilityIssues as part of any test:

it(‘has no detectable accessibility issues when the page loads’, () => {
  cy.checkForDetectableAccessibilityIssues({
    elsToExclude: [‘[data-testid=”homepage-questionnaire”]’],
  });
});

If your Cypress test activates a button on the page that triggers a change to the page content (revealing a modal dialog for example), you should call cy.checkForDetectableAccessibilityIssues again.

2.3. If you need an escape hatch

The elsToExclude option (els stands for ‘HTML elements’) allows you to tell Axe to ignore issues within certain HTML elements. It takes an array of CSS selectors.

This can be useful if an element on the page has accessibility issues that are already known, and that you’ve decided you’re not going to solve now – but you still want the test to pass (if it’s part of your Continuous Integration / Continuous Deployment pipeline for example).

In that situation, someone once told me that they’d disabled automated accessibility tests altogether. Don’t do that. Do your best to fix the issue instead, and if you can’t, use that escape hatch exceptionally.

If you decide to use the elsToExclude option, make sure that the CSS selector you provide are as narrow as possible (targeting as few HTML elements as possible), so that…

• The accessibility tests cover everything on the page except the exact place where you know there’s an issue you’re going to ignore for now.
• It’s easy to find where issues are later.

3. Understanding the test results

3.1. If you’re using the Cypress Graphical User Interface in headed mode

If there’s any WCAG 2.1 AA issue on the page that Axe can automatically detect, the test will fail and you’ll see something like this:

The Cypress Graphical User Interface. The testing log says that an accessibility violation was detected.

To get more information about what each error is, click on the row that starts with ‘’-a11y error!’, and open the devtool console:

Click on any of the log entry that start with ‘-a11y error!’ and open the console in the browser’s developer tools shows to see exactly what the accessibility error is and how to fix it.

That tells you exactly what the issue is. You can use the Helpurl to get more details.

3.2. If you’re using the Cypress in the terminal

If there’s any WCAG 2.1 AA issue on the page that Axe can auto, the test will fail and you’ll see the details of the error directly in the terminal.

Each accessibility issue is logged in the terminal.

Conclusion

At Kooth we also use Axe as part of our Jest unit tests (using jest-axe). Both complement each other.

What I like about detecting accessibility issues with Cypress, is that it’s so easy to set up, and it’ll save you from introducing lots of accessibility issues.

Image credit: Christopher Gower