Skip to main content
Cypress AccessibilityPremium Solution

Configure Axe Core® rules - axeConfig

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 favors high-confidence results, so the report you get out of the box is already the recommended configuration for most teams.

When you need a different ruleset for your project, set axeConfig under the accessibility key in App Quality Config. You can enable a rule that is off by default, turn off a rule that is a known false positive, or scope the report to the WCAG tags your team measures against. Changes apply the next time a run is processed, and you can regenerate a past run to preview the effect without rerunning your tests.

Because you decide what actually blocks a build with the Accessibility Results API or webhook-driven workflows, turning rules off only to keep CI green is unnecessary. Leaving a rule reported but non-blocking keeps full visibility into every finding while you control the gate in your pipeline.

Why use axeConfig?​

  • Enable a rule that is off by default: The most common change 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, disable it project-wide so it stops adding noise to your reports.
  • Scope the report to a conformance target: Limit the run to the WCAG tags your team measures against, including rule groups that Axe-Core® keeps off by default, such as WCAG 2.2 or Level AAA.

Customize included elements, pages, and CI-blocking behavior​

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.

Scope​

axeConfig is only valid under an accessibility key in your App Quality configuration. It can also be set inside a profiles entry to apply different rulesets to tagged runs.

Setting axeConfig​

To add or edit axeConfig, open the App Quality tab in your project settings in Cypress Cloud. See Setting configuration for details, including how to regenerate past reports with a new configuration without rerunning your tests.

The App Quality tab of a project's settings in Cypress Cloud, showing the configuration editor with JSON configuration

Syntax​

App Quality Config
{
  "accessibility": {
    "axeConfig": {
      "runOnly": {
        "type": "tag" | "tags" | "rule" | "rules",
        "values": [string]
      },
      "rules": {
        "<rule-id>": { "enabled": boolean }
      }
    }
  }
}

Options​

OptionRequiredDefaultDescription
runOnlyOptionalLimits which Axe-Core® rules run to the listed tags or rule IDs. type is tag or tags for Axe-Core® tags such as wcag2aa, and rule or rules for individual rule IDs. values is the list of tags or rule IDs to include.
rulesOptionalPer-rule overrides. Each key is an Axe-Core® rule ID, and enabled turns that rule on or off. Overrides apply on top of Cypress defaults and any runOnly selection.

How is axeConfig applied?​

  • rules overrides win over Cypress defaults. Cypress Accessibility starts from its default disabled rules. Any rule you set in axeConfig.rules replaces that default for that rule, so "color-contrast": { "enabled": true } turns color contrast on for the project.
  • runOnly narrows the ruleset. When you set runOnly, only rules that match the listed tags or IDs run. Rules outside that selection are reported as ignored by configuration.
  • Combine runOnly and rules when you need both. A common pattern is scoping to WCAG tags with runOnly, then enabling or disabling individual rules inside that scope with rules.
  • Disabled rules stay visible in the report. In the Rules view, rules turned off by configuration appear with an Ignored by configuration status, so it's clear which checks a run did and did not include.
  • Unknown properties are rejected. Cypress Cloud validates axeConfig against a strict schema. Only runOnly and rules are accepted, and each rules entry accepts only enabled.

Validation rules​

Cypress Cloud rejects a configuration when:

  • axeConfig is set at the root of the configuration instead of under accessibility.
  • axeConfig contains a property other than runOnly or rules.
  • runOnly is missing type or values, or uses an unsupported type.
  • A rules entry is missing enabled, or contains a property other than enabled.

Examples​

Enable color contrast checking​

Color contrast is off by default. Turn it on for the project.

Config​

App Quality Config
{
  "accessibility": {
    "axeConfig": {
      "rules": {
        "color-contrast": { "enabled": true }
      }
    }
  }
}

Result​

The color-contrast rule runs for the project. The other rules that are off by default stay off.

Disable a noisy rule project-wide​

Turn off a rule that's not relevant to your project or your current accessibility goals, to reduce noise for your team when parsing reports.

Config​

App Quality Config
{
  "accessibility": {
    "axeConfig": {
      "rules": {
        "region": { "enabled": false }
      }
    }
  }
}

Result​

The region rule is listed as Ignored by configuration and stops adding violations to the report.

Scope the report to WCAG 2.1 A and AA​

Limit the run to WCAG 2.0 and 2.1 Level A and AA tags, and leave Best Practices rules out of the report.

Config​

App Quality Config
{
  "accessibility": {
    "axeConfig": {
      "runOnly": {
        "type": "tag",
        "values": ["wcag2a", "wcag2aa", "wcag21a", "wcag21aa"]
      }
    }
  }
}

Result​

Only rules tagged for those WCAG levels run. Best Practices rules, such as region and landmark-one-main, are ignored by configuration.

Scope to WCAG tags and enable color contrast​

Combine runOnly with a per-rule override so the report stays on your conformance target while color contrast still runs.

Config​

App Quality Config
{
  "accessibility": {
    "axeConfig": {
      "runOnly": {
        "type": "tag",
        "values": ["wcag2a", "wcag21a"]
      },
      "rules": {
        "color-contrast": { "enabled": true }
      }
    }
  }
}

Result​

The report includes WCAG 2.0 and 2.1 Level A rules, including color-contrast, and leaves Best Practices rules out.

Apply a different ruleset on pull request runs​

Use a profiles entry so tagged pull request runs scope to WCAG 2.0 and 2.1 Level A and AA tags while regression runs keep the broader base ruleset.

Config​

App Quality Config
{
  "profiles": [
    {
      "name": "aq-config-pr",
      "comment": "Pull request gate: WCAG A/AA only",
      "config": {
        "accessibility": {
          "axeConfig": {
            "runOnly": {
              "type": "tag",
              "values": ["wcag2a", "wcag2aa", "wcag21a", "wcag21aa"]
            }
          }
        }
      }
    }
  ]
}

Usage​

cypress run --record --tag "aq-config-pr"

Result​

Runs recorded with the aq-config-pr tag use the scoped ruleset. Runs recorded without that tag keep the base configuration.

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. Enable these for your project with runOnly or per-rule rules.
WCAG Level AAANoOff by default in Axe-Core® itself. Enable these for your project with runOnly or per-rule rules.
Experimental and deprecatedNoOff by default in Axe-Core® itself.

Keep these behaviors in mind 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.

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 with axeConfig. 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 even if you enable them.

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; enable it with "color-contrast": { "enabled": true }.
<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. An axeConfig rule override can't force a page-level rule to run for component tests.

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