Skip to main content
Cypress AccessibilityPremium Solution

Axe Core® configuration

Cypress Accessibility runs Axe-Core®'s default ruleset against every snapshot captured during your test run, with no setup, assertions, or cy. commands to add to your specs. The ruleset is tuned to favor high-confidence results, so the report you get out of the box is already the recommended configuration for most teams.

Because you decide what actually blocks a build with the Accessibility Results API, where you have full control over how to parse results and which rules to react to, there is rarely a need to change which rules run in Cypress Cloud. Keeping the ruleset broad means you can still see and understand every accessibility finding, even when only a subset of results is treated as blocking in your pipeline.

When you do need to change how the ruleset behaves for your project, Cypress can tune it for you. This is a guided process handled through your Cypress point of contact rather than a setting in the App Quality editor, so you get results that fit your application without the risk of silently turning off important checks.

What the default ruleset covers​

Cypress applies no conformance filter of its own, so a run evaluates whatever Axe-Core® enables by default, minus the three rules Cypress turns off by default:

Axe-Core® rule groupRuns by defaultNotes
WCAG 2.0 Level A and AAYesMinus color-contrast, no-autoplay-audio, and meta-refresh, which are WCAG-tagged but off by default
WCAG 2.1 Level A and AAYes
Best PracticesYesDeque's own recommendations, such as region and landmark-one-main. These are not WCAG success criteria.
WCAG 2.2 Level A and AANoOff by default in Axe-Core® itself. Cypress can enable these for your project.
WCAG Level AAANoOff by default in Axe-Core® itself. Cypress can enable these for your project.
Experimental and deprecatedNoOff by default in Axe-Core® itself.

Two consequences are worth knowing if you're measuring against a formal standard:

  • The default report is broader than any single WCAG level. Best Practices findings appear alongside WCAG ones, so a violation in your report is not automatically a WCAG failure. Use the Rules filter in a report to separate WCAG 2.1 A, WCAG 2.1 AA, and Best Practices results.
  • The default report is also not complete WCAG coverage. The three rules that are off by default map to WCAG success criteria (1.4.3, 1.4.2, and 2.2.1), and no automated ruleset can evaluate every success criterion in the first place. See accessibility automation principles for what conformance requires beyond automation.

To align a project's report with a specific conformance target, ask Cypress to scope the ruleset for you, as described below.

How Cypress can tune the ruleset for your project​

Teams reach out for a few common adjustments. In each case, Cypress applies the change on your behalf and can regenerate historical runs so you can preview the effect before adopting it:

  • Enable a rule that is off by default. The most common request is turning on color contrast checking for a project where you've confirmed it produces reliable results.
  • Turn off a rule that is a known false positive. If a specific rule consistently misfires because of a third-party framework you can't change, it can be disabled project-wide so it stops adding noise to your reports.
  • Scope the report to a conformance target. Cypress can narrow the ruleset to the standard your team is committed to, such as WCAG 2.1 Level A and AA, so the report reflects exactly the criteria you're measuring against. This is also how you enable rule groups that Axe-Core® keeps off by default, such as WCAG 2.2 or Level AAA.

We're happy to have a call to dial in your report configuration and make sure you're getting the most useful reports possible.

Adjustments you can make yourself​

Some ways of shaping your results don't require any rule configuration and are fully in your control:

  • To ignore a specific rule for individual elements, add the data-a11y-ignore attribute in your application code.
  • To keep a rule enabled but stop a particular element or page from being reported, use elementFilters or viewFilters.
  • To decide which findings block a build in CI, parse your run's results with the Results API. Leaving a rule reported but non-blocking is often the best choice, since you keep full visibility into the issue.

Rules that are off by default​

A small number of Axe-Core® rules are turned off in Cypress Accessibility by default. Color contrast can be enabled per project on request. The other two depend on live runtime behavior that isn't reproduced when Cypress re-renders a captured snapshot for analysis, so they can't be evaluated reliably.

RuleWhy it's off by default
Elements must meet minimum color contrast ratio thresholdsThis is the slowest rule in the Axe-Core® ruleset and the one most likely to produce false positives or incomplete results. It works well in many projects, so we're happy to turn it on for you on request.
<video> or <audio> elements must not play automaticallyDetecting a violation requires loading and playing the media to measure how long it plays. Cypress analyzes a reconstructed snapshot of the page without playable media, so this rule can't be evaluated.
Delayed refresh under 20 hours must not be usedThis rule reads a page's meta refresh directive, which Cypress disables while it analyzes a run so the reconstructed page doesn't navigate away. With the directive disabled, the rule can't be evaluated.

In addition, the custom Cypress rule Interactive elements should be semantically correct is available in all projects but is not enabled by default. Reach out to Cypress if you'd like it turned on.

You can confirm which rules were turned off for any run in its Accessibility report. In the Rules view, disabled rules are listed with an Ignored by configuration status, so it's always clear which checks a run did and did not include.

Component testing​

Cypress Accessibility works with component testing as well as end-to-end testing. Alongside the rules that are off by default above, page-level rules do not run for component tests. Because a component is usually a fragment of a page rather than a complete document, rules that assert on overall page structure would report failures that don't apply to a component in isolation.

Rules skipped for component tests include page-structure and document-level checks, such as whether the page has a main landmark, a single top-level heading, a language attribute, and a document title. Rules that evaluate the components themselves, such as color contrast (when enabled), button naming, and image alternative text, run as normal.

The exact set of skipped rules isn't a fixed list Cypress maintains. It's derived from which rules Axe-Core® classifies as page-level, so it can shift when Cypress updates its Axe-Core® version. In a component's report, these page-structure rules are reported as not applicable rather than as failures.

Axe-Core® library version and updates​

Cypress pins a specific, tested version of the Axe-Core® library. New Axe-Core® versions are released several times a year. While Cypress doesn't commit to updating our internal version within a specific timeframe, we always wait at least 30 days before adopting a new release.

Because some updates introduce new rules or change how existing issues are detected, this buffer gives you time to adjust how you use the Results API if needed. You can track Axe-Core® releases on GitHub.

The exact Axe-Core® version used for a given run is shown in the Properties tab for that run in Cypress Cloud, and is also included as axeVersion in the Results API response. To get a heads-up in CI when the version changes, see how to detect a change in the axe-core version.

See also​

Contents