Accessibility E2E Testing: Automating User Journeys

WHY IT EXISTS Static code analysis and unit tests can't catch accessibility issues that only appear when a user interacts with a live application. We need a way to automatically test the accessibility of a complete, multi-step user journey as it would appear in a browser.

THE MENTAL MODEL Think of accessibility E2E testing as hiring a very fast, but not very clever, robot to click through your app. This robot follows a script (your E2E test) and runs an accessibility scanner (like axe-core) on every page and state it sees. It's great at catching obvious, machine-detectable violations but misses anything requiring human judgment.

HOW IT WORKS You use a standard E2E testing framework like Cypress or Selenium to script a user flow, such as logging in, adding an item to a cart, and checking out. Then, you use a wrapper library like cypress-axe or axe-selenium to inject an accessibility engine into the test. At key steps in your test script, you command the engine to scan the current state of the page and fail the test if any violations are found.

WHEN TO USE IT Integrate it into your CI/CD pipeline as an automated quality gate to catch accessibility regressions in critical user flows before they reach production. It is especially effective for testing complex interactions involving multiple pages, dialogs, or other temporary UI elements that linters cannot analyze.

WHEN NOT TO USE IT Do not use it as your only form of accessibility testing. Automated tools are fundamentally limited and find, at best, only 30-50% of all accessibility problems. They cannot check for logical content order, confusing link text, or whether an animation is distracting. Manual testing by a human is always required to supplement automation.

ONE CANONICAL EXAMPLE A team uses Cypress for their E2E tests and adds the cypress-axe plugin. In their test for the checkout flow, after the test script fills out the shipping address and clicks "Next," they add a cy.checkA11y() command. This runs axe-core on the newly rendered payment page. If the payment form has a missing input label or a color contrast issue, the CI build fails, preventing the bug from being deployed.