How to Test Web Accessibility for the European Accessibility Act With Cypress

Direct answer: Add an accessibility scan to Cypress tests at meaningful points in each user journey, then supplement it with behavior assertions and manual evaluation. A green automated scan does not prove European Accessibility Act (EAA) compliance. First determine whether the service is in scope, identify the applicable requirements and national implementation, and test representative routes and states against those requirements.

This guide shows a Cypress setup using the community cypress-axe plugin and Deque’s axe-core. Check the current Cypress accessibility testing guide and the plugin’s current documentation before adopting exact package versions or APIs; integrations can change. The code below illustrates the documented injectAxe() and checkA11y() workflow.

1. Check EAA scope before choosing tests

The EAA is Directive (EU) 2019/882. It covers defined categories of products and services; it does not automatically apply to every website. EU business guidance gives online shops, ticketing platforms, and banking services as examples. It identifies 28 June 2025 as the application date for covered products and services placed on the market after that date, subject to scope, transition arrangements, and exceptions. A qualifying microenterprise providing services is among the exceptions described in the guidance.

Use the Directive text and Your Europe business guidance to frame an initial scope review. Then verify the rules and implementation in the relevant Member State for the service. This is scoping guidance, not legal advice.

Do not confuse the EAA with the Web Accessibility Directive (WAD), which concerns public-sector websites and apps. Nor should a WCAG version be treated as an automatic synonym for EAA compliance. EN 301 549 is an ICT accessibility standard that covers more than websites; the Commission’s WAD explanation describes requirements beyond WCAG in that context. Those sources do not by themselves establish the current EAA-specific harmonised standard or its Official Journal status. Verify the applicable references and national measures for your service before making a conformance claim. See the AccessibleEU EN 301 549 overview and the Commission explanation of WAD standards.

2. Map requirements to routes, states, and evidence

Before adding a scan, record which requirements and technical references apply to the specific service. Build a small traceable map from those requirements to the user journeys, automated checks, manual evaluations, findings, and fixes. The exact documentation obligations depend on the service and national implementation; Annex V of the Directive describes information service providers must include about the service and how it meets relevant Annex I requirements.

Choose representative routes and interaction states, not just the initial page render. A practical starting inventory might include:

Navigation opened and closed, including keyboard operation.
Forms in their default state, with validation errors, and after successful submission.
Dialogs or menus when opened, including focus placement and return of focus on close.
Authentication, search results, and dynamic content states.
Checkout or payment steps where relevant to the service.
Responsive layouts and any important loading, empty, or error states.

This inventory is a testing recommendation, not a statutory checklist. Select states that reflect the service’s actual requirements and use.

3. Add axe scans to Cypress

Install and register the plugin

Install cypress-axe using your package manager, following the current plugin instructions for the version in your project. Register its commands in the Cypress support file that your project loads for end-to-end tests. For example, the usual setup is:

// cypress/support/e2e.js
import 'cypress-axe';

If your project uses a different support-file path or module format, use that project’s configured file and syntax. Confirm that Cypress loads the support file before relying on the commands.

Scan after the page is ready

Here is a complete example test for a route. Replace the example path with a route in your application. Ensure the page has reached the state you intend to assess before injecting axe and scanning.

// cypress/e2e/accessibility.cy.js
describe('accessibility', () => {
  it('scans the account page', () => {
    cy.visit('/account');
    cy.get('main').should('be.visible');

    cy.injectAxe();
    cy.checkA11y();
  });
});

For dynamic pages, wait for a meaningful application condition such as a visible heading or completed result list. Avoid arbitrary sleeps when a reliable DOM assertion is available. The scan examines the rendered state it sees; it cannot assess a dialog or validation state that the test never opens.

Exercise interaction states before scanning

Use Cypress actions and assertions to reach each state, then scan it. For example, adapt selectors to your application:

it('scans the form error state', () => {
  cy.visit('/contact');
  cy.get('main').should('be.visible');

  cy.get('button[type="submit"]').click();
  cy.get('[role="alert"]').should('be.visible');

  cy.injectAxe();
  cy.checkA11y();
});

Write separate tests or clearly named steps for distinct states so a failure points to a useful point in the journey. Add ordinary Cypress assertions for expected behavior: for example, that an error is announced, focus moves appropriately, a menu responds to keyboard input, or a dialog closes and restores focus. An axe scan does not establish all of those behaviors by itself.

Configure rules deliberately

The plugin’s checkA11y() approach can be configured for selected rules and WCAG success criteria. Start with the tool’s current configuration documentation and the criteria relevant to the service. Do not disable rules simply to make CI green: record why a rule is excluded, who owns the decision, and whether another check covers the risk. A filtered scan only reports on the selected scope and rules, so document the configuration alongside the evidence.

Automated findings commonly include detectable issues such as poor contrast, missing labels for icons or buttons, and images without alternative text. Whether an image needs particular alternative text, whether link wording makes sense in context, and whether a process is usable are examples of questions that need human judgment.

4. Run checks in CI and keep a useful evidence trail

Run the Cypress suite through the same project command your team uses locally and in CI. Make accessibility failures visible in the normal test output and remediation workflow. Keep enough context to reproduce a failure: route, state, relevant test, tool and configuration, and the finding. Avoid reporting a single undifferentiated “compliant” status from a scan.

A useful evidence record includes:

The product or service scope decision, applicable requirements, and reference versions.
The Member State implementation or guidance reviewed and the date of review.
Routes and interaction states covered, plus states or criteria not covered and why.
Cypress, plugin, and rule configuration versions.
Findings, severity or prioritization method, owners, fixes, and re-check results.
Manual and behavior-focused evaluation performed, with enough detail to repeat it.

Keep this record aligned with the actual applicable service obligations. Annex V of the EAA Directive describes information about the service and how relevant requirements are met; confirm the required form for your circumstances.

5. What automated scans can and cannot establish

Cypress describes both in-test plugin integrations and Cypress Accessibility, a paid enterprise option in Cypress Cloud. It identifies cypress-axe as a community plugin integrating axe-core. Compare options based on cost and whether you already use Cypress Cloud, how the checks fit into your tests and CI, the rule configuration and reporting workflow, and how well you can cover the routes and dynamic states that matter.

As Cypress’s guidance cautions, teams need to understand a library’s coverage and limitations, and plan manual checks or traditional Cypress assertions for behavior a generic scan cannot establish. A scan covers detectable rules in the rendered state and selected configuration. It cannot prove every legal requirement, conformance criterion, or usability need. Include keyboard evaluation and assistive-technology testing in the broader plan, and do not claim particular browser or screen-reader results unless those evaluations were actually performed.

6. Troubleshooting

Symptom	Likely cause	What to do
`cy.injectAxe` or `cy.checkA11y` is undefined	The plugin support file did not load, or the installed package/version uses a different setup.	Check the Cypress support-file configuration, import the plugin there as documented for your version, and confirm the dependency is installed.
The scan runs before content appears	The test scans an intermediate loading state or asynchronous content has not rendered.	Wait for a meaningful visible application condition, then inject and scan after that condition.
A modal or error state has no findings, but may be inaccessible	The test scanned only the default page state and never opened or triggered the state.	Drive the interaction with Cypress, assert the state is visible, and run a scan for that state as well.
CI reports failures that developers cannot reproduce	Different data, timing, environment, or application state may affect the rendered page.	Make the route, test data, and readiness condition deterministic; retain the route/state and rule context with the failure.
A scan is green but keyboard use still fails	The issue is behavioral or outside the automated rules and selected state.	Add explicit keyboard and focus assertions, then perform manual keyboard and assistive-technology evaluation.
A team disables a noisy rule repeatedly	The rule may need scoped configuration or a documented exception, or the underlying issue may be real.	Review each finding, document the reason and owner for any exclusion, and ensure another check addresses the relevant requirement.

7. Performance, reliability, and cost

An accessibility scan adds work to each test state where it runs. Keep suites useful by selecting representative journeys and important states rather than scanning the same unchanged page repeatedly. Avoid skipping states that carry distinct content or interaction behavior. Stable readiness assertions, deterministic test data, and clear state setup make failures easier to reproduce.

The community plugin approach adds dependency and maintenance work to the existing Cypress suite. Cypress Accessibility is a paid enterprise option in Cypress Cloud; check current Cypress product information for current availability and terms. Neither approach replaces manual evaluation or proves EAA compliance. Budget time for triage and remediation as well as scan execution: a finding is useful when the team can understand, assign, fix, and re-check it.

Or skip the browser setup

If you need screenshots alongside accessibility work—for visual review, bug reports, or documenting page states—ScreenshotNeo is a website screenshot API and MCP server for developers. It is separate from accessibility testing: a screenshot does not identify accessibility issues or establish EAA compliance.

One GET request returns an image or PDF. See the ScreenshotNeo API documentation for options and setup.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

Cookie banners and consent overlays, newsletter popups, and chat widgets are removed before the shot; each step can be turned off.
Bot checks, blank pages, failed loads, timeouts, and cache hits are never billed; response headers say the page verdict and billing result.
An MCP server gives AI agents tools for screenshots, page information, and PDF capture.
The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000 screenshots.

FAQ

Can Cypress test WCAG compliance?

Cypress can run automated checks against selected rules and rendered states. That helps find some issues, but a green scan does not establish complete WCAG conformance or EAA compliance.

Does an automated accessibility scan prove EAA compliance?

No. Scope, applicable requirements, standards, and national implementation must be determined for the actual service. Automated checks are one part of a larger evaluation and evidence process.

Which standard applies to my website under the EAA?

That depends on the covered service, applicable requirements, relevant Member State measures, and current standards references. Verify those sources for your service; do not assume a WCAG version alone settles the question.

Should every route be scanned?

Cover representative routes and all materially different content or interaction states. The right coverage depends on the service and requirements; scanning one landing page is rarely a useful account of a multi-step service.