Skip to main content
Cypress AccessibilityPremium Solution

Cypress Accessibility FAQ

Fixing violations​

Where do I start when Cypress Accessibility reports hundreds of violations?​

Start by narrowing the report to the code you own with viewFilters and elementFilters, so third-party pages and vendor widgets stop competing for attention. Then open the Rules list for a run and pick a single rule with a small number of failing elements and a fix that fits in one component, such as button-name. Finishing one rule across the application is usually faster than finishing one page, because the fix has the same shape every time. See Fix accessibility violations for the full process.

Should I fix a violation in Cypress Accessibility or ignore it?​

Ignore findings you don't own or have decided not to fix, such as a third-party consent banner or an OAuth provider's sign-in page, so your report reflects work you actually intend to do. Fix findings in your own application: filtering one removes the evidence from the report, but the barrier is still there for the people using your product. When you're unsure, leave the finding reported and use the Results API to decide whether it blocks a build, which keeps full visibility into the issue.

Why didn't my Cypress Accessibility score change after I fixed some violations?​

The accessibility score weighs each failed rule per snapshot, not each failing element. If a rule fails on 10 elements in a snapshot and you fix nine of them, that snapshot's score is unchanged until the last one is fixed and the rule flips to passing. The run score also averages every snapshot in the run, so a rule failing on one page in a large suite barely moves the top-line number. Track failed element counts for the rule you're working on, and the Resolved elements section of Branch Review, rather than watching the score during remediation.

How do I confirm an accessibility fix worked in Cypress Accessibility?​

Compare your branch against a base run in Branch Review. The Resolved elements section should list the rule you worked on across every view where it was failing, which confirms the fix reached more than the one element you tested by hand. Check the New failed elements section in the same review: accessibility fixes commonly introduce new findings, such as an added aria-label that duplicates visible text. See Compare reports for how the comparison works.

Do I need to add assertions or commands to my tests for Cypress Accessibility?​

No. Cypress Accessibility reports are generated in Cypress Cloud from the artifacts your recorded run already uploads, so there is nothing to add to your specs and no impact on how long your tests take. Every page and component your tests visit is checked automatically once the product is enabled for your project. Because the report is produced after the run, nothing in your Cypress pipeline fails from an accessibility violation unless you opt in with the Results API.

How do I fix Cypress Accessibility violations with an AI agent?​

Configure Cypress Cloud MCP so your agent can read results directly from Cypress Cloud with three tools: cypress_get_accessibility_report for a run's failing rules and worst views, cypress_get_accessibility_views to page through every view, and cypress_get_accessibility_rule_failures for the failing elements of a specific rule. Scope each prompt to one rule and ask for a plan before any code changes. Narrowing your report first keeps the agent from triaging findings you were never going to fix, and adding components attributes to violation selectors helps it locate the source file without crawling your markup.

How do I stop a Cypress Accessibility rule I already fixed from regressing?​

Keep a list of remediated rules in your CI verification script and fail the build when any of them appear in a run's results, using the Results API. This inverts the more common pattern of allowlisting known failures: instead of tracking what's still broken, you lock in each rule the day it reaches zero violations. Add a rule to the list as soon as it passes, and the list becomes a record of the barriers your application no longer has.

Inspecting a violation​

How do I see which element failed an accessibility rule in Cypress?​

Open the rule in a run's accessibility report and it expands into the violation detail view, which lists every element the rule matched by its violation target selector. Selecting an element pins it, highlights it in a DOM snapshot of the page state it was captured in, and expands a Solutions list of the specific checks that failed on it. Clicking a rule row on the Rules tab opens All Views scoped to that rule, which collects its failing elements across the entire run.

Can I inspect a Cypress Accessibility violation without running my application locally?​

Yes, and this is the main reason the detail view exists. Every finding is stored with a rehydrated DOM and CSS snapshot of the page state it was found in, so the markup and styles render in your browser exactly as they did during the run. You can inspect the element, read computed styles, and open your browser's accessibility pane against the captured page without starting a server or reproducing the steps. See inspect violation details.

Why does a Cypress Accessibility snapshot highlight only one element?​

By design. The snapshot outlines the element you have pinned, or the one you are hovering in the rules list, and nothing else, so a page with hundreds of failing elements stays readable. Select a different element to move the highlight, or turn the outline off entirely with the Show DOM highlights toggle in the snapshot options menu when it covers something you need to see.

Why does Cypress Accessibility say an element is not in this snapshot?​

The element failed the rule somewhere in the view, but not in the page state currently displayed. A run captures many snapshots per view as your tests interact with the application, and an element such as a modal's close button only exists in the snapshots where the modal was open. Selecting the element moves the snapshot to a page state that contains it. With an element pinned, the snapshot counter also narrows to only the snapshots that element appears in.

What does "One of these must be fixed" mean in a Cypress Accessibility violation?​

It means the listed checks are alternatives, and satisfying any one of them clears the violation. A button failing button-name, for example, can be fixed with inner text, an aria-label, an aria-labelledby reference, or a title attribute. All of these must be fixed means every listed check has to pass, This must be fixed means there is a single check, and This element is failing for multiple reasons introduces more than one group, each with its own rule. See inspect violation details.

How do I share a specific accessibility violation with my team?​

Three ways, from fastest to most durable. Copy the URL, which encodes the view, rule, pinned element, snapshot, and filters, so a teammate opens on exactly what you're looking at. Use Share issue to copy a Markdown or plain text snippet containing the rule, severity, view, element selector, a link to the rule's documentation, and a deep link back into Cypress Cloud. Or use Create Jira issue to open a ticket with those details prefilled. See hand off a violation.

How do I create a Jira issue from a Cypress Accessibility violation?​

Select the failing element to expand its detail, choose Create Jira issue, and pick a Jira project. Summary is prefilled with the rule name and Description with the Markdown issue snippet, including a link back to the violation in Cypress Cloud. Both are editable before you submit, so it's the right moment to add context a triager will want. Choose an issue type, complete any fields your Jira project requires, and submit. This requires the Cypress Cloud Jira integration to be installed for your organization; without it, the button doesn't appear.

Can I file issues for a whole accessibility report at once?​

Yes, with an AI agent connected to both Cypress Cloud MCP and your issue tracker. The agent reads the report for the latest run on a branch, checks Jira or another tracker for the issues that already exist, and creates only the ones that are missing, so a weekly refresh doesn't produce duplicates. File issues in your issue tracker walks through the prompts, how to group violations into tickets, and the guardrails to keep on an agent that can write.

Why does my Cypress Accessibility report show generated class names instead of meaningful selectors?​

Because nothing more meaningful was available on the element. Cypress Accessibility builds each violation target selector from a prioritized list of attributes, so an element with no test attribute and no useful id falls back to whatever identifies it, which in a component library often means a class like .MuiIconButton-colorPrimary. Add the attribute your application already renders to significantAttributes to make it the identifier, or use components to append component and team context to the existing one. Regenerate a past run afterward to see the new selectors without rerunning your tests.

Why does a Cypress Accessibility rule show only 20 failing elements?​

Elements load 20 at a time to keep the rules list responsive on rules with hundreds of findings. A Load more elements row at the bottom of the list fetches the next batch. The count beside the rule name is always the full number of matching elements, not the number currently loaded.

Why don't ignored elements show up in the violation detail view?​

The Element status filter defaults to failed and inconclusive elements, with ignored turned off, so findings you have already excluded stay out of your triage list. Turn Ignored on in the filter menu to review them. Ignored elements keep their full detail, including the Solutions list, which makes this the fastest audit of what your elementFilters and data-a11y-ignore rules are hiding.

How do I get from an accessibility violation to the test that found it?​

Use the Test Replay button above the snapshot. It shows how many tests reached that page state and opens Test Replay for any of them, so you can see which spec ran, which commands led there, and what the application was doing just before the element was captured.

Local development​

Can I get Cypress Accessibility results without waiting for CI?​

Yes. Record the specs you're working on from your own machine with cypress run --record --spec "cypress/e2e/checkout.cy.js". Cypress Accessibility is generated in Cypress Cloud from the run's Test Replay data, so a run recorded from your laptop is processed exactly like a CI run: same App Quality Config, same Axe Core® version, same element identification. Limiting the run with --spec keeps the report to the code you changed and shortens the feedback loop to a couple of minutes. See Local development.

Does cypress open produce a Cypress Accessibility report?​

No. Interactive mode never records a run to Cypress Cloud, and reports are only generated for recorded runs. Use cypress run --record to get accessibility results from your machine.

Which browser should I use to record a local run for Cypress Accessibility?​

Chrome, Edge, Chromium, or Electron. Reports are built from Test Replay data, which is only captured in Chromium-based browsers, so a run recorded with --browser firefox or --browser webkit produces no accessibility report. cypress run defaults to Electron, which is supported, so you get a report without passing --browser at all. See No accessibility report was generated for a run for the other requirements.

How do I check an accessibility fix before I push my branch?​

Record the same specs twice and compare the two Cypress Accessibility reports in Branch Review: once from your base branch before you start (or with your changes stashed), then again from your branch after the fix. Set your branch's run as the Changed run and the base branch's run as the Base run. Resolved elements confirms the rule you fixed cleared everywhere it was failing, and New failed elements catches the violation the fix introduced. Recording the same specs in both runs is what makes the comparison meaningful. See Local development.

Can I use the Cypress Accessibility Results API on my local machine?​

No. getAccessibilityResults() identifies which run to report on from the CI environment variables present when the run was recorded, so running it outside CI fails with "It appears you are not running in CI." The Results API is for enforcing a policy in your pipeline. For local feedback, read the report in Cypress Cloud, compare runs in Branch Review, or query results through Cypress Cloud MCP.

Is my Cypress Accessibility score from a local run comparable to my CI score?​

No, and it isn't meant to be. A run's accessibility score averages every snapshot in that run, so a two-spec local run and a full CI suite have different denominators. Compare rules and failed element counts between two local runs of the same specs, and track the score on your full suite.

Why does my local Cypress Accessibility report include pages my CI report excludes?​

Your viewFilters patterns most likely name a deployed hostname, and hostnames must match exactly, so a rule for https://app.example.com/* never matches http://localhost:3000. Write path-only patterns like /auth/*, which match any protocol, hostname, and port, or add a profiles entry for local runs and tag them with --tag. See Make your configuration match localhost.

Why is my Cypress Accessibility report not ready as soon as the run finishes?​

Each spec's data starts processing as it uploads, but the run-level report is assembled only after Cypress Cloud marks the run complete. For grouped and parallelized runs, completion waits out the project's Run Completion Delay, a grace period of 60 seconds by default that lets late machines join, and report finalization waits with it. A single run recorded without --group or --parallel skips that delay and completes as soon as its specs are done, which is why local runs turn around quickly. To speed up a grouped run, shorten the delay in project settings or close the run with the Run Completion API.

How do I keep local runs from cluttering my Cypress Cloud project?​

Tag them with cypress run --record --tag "local". Tags appear on the run and are filterable in Cypress Cloud, so everyone can skip past them in the run list. A separate Cypress Cloud project for local runs is possible but costs you the comparison workflow, since Branch Review compares runs within one project and App Quality Config is per project. Note that every recorded run consumes test results from your plan regardless of where it ran, which is another reason to keep local runs scoped with --spec.

Detecting changes​

How do I find which pull request introduced a Cypress Accessibility violation?​

Open Branch Review in Cypress Cloud with the pull request's run as the Changed run and the base branch's run as the Base run. The New failed elements section lists only the violations that appear in the Changed run and not in the Base run, grouped by rule and view, with a page snapshot for each. If the violation predates the pull request, keep the Changed run fixed and move the Base run backwards through earlier runs until the violation stops showing as new. See Catch accessibility regressions.

Does Cypress Accessibility fail my build when a new violation appears?​

No. Reports are generated in Cypress Cloud after your tests upload, so a Cypress run never fails because of an accessibility violation, and there is no performance cost to your tests. Blocking a build is an opt-in step you add with the Results API, which fetches the run's results in CI so you can decide what should fail. See Block pull requests and set policies.

Should I block builds on failing rules or on the Cypress Accessibility score?​

Rules are the stricter and more reliable signal in a Cypress Accessibility report: a rule going from zero failures to any failures is a real change in the application, traceable to the build that introduced it. Element counts and the score move on their own as tests reach different states and existing broken components get reused, which makes them better suited to monitoring runs and score thresholds than to gating individual pull requests. Many teams use both, with a rule policy on pull requests and a score threshold on scheduled runs. See Enforce a standard in CI.

Can I compare accessibility reports from two different Cypress projects?​

No. Branch Review compares two runs within a single project, and App Quality Config is set per project, so cross-project comparisons are not available. If two teams need separate reports for the same application, use profiles to give each team's runs its own configuration inside one project, which keeps comparisons working.

Why does Cypress Accessibility show new failed elements in Branch Review when I didn't change that code?​

The most common cause is unstable element identification. Cypress Accessibility matches elements between runs by the identifier described in element identification, so a hashed CSS-in-JS class or a framework-generated ID that changes per build makes one element look like a resolved failure plus a new failure. Exclude those values with attributeFilters. Views can drift the same way when URLs contain IDs or slugs, which views rules resolve. See Make the comparison trustworthy.

Why does my Cypress Accessibility comparison show a long list of resolved elements after a small change?​

The two runs most likely did not cover the same ground. Cypress Accessibility compares what each run actually saw, so if the Base run recorded the full suite and the Changed run recorded a few specs, everything on the pages that were not visited is reported as resolved. Record the same specs on both sides of the comparison. See Accessibility feedback during local development.

What are existing failed elements in a Cypress Accessibility comparison?​

They are the violations present in both runs, which is everything the change neither introduced nor fixed. Cypress Accessibility keeps them out of the Branch Review diff and links to the full report for the Changed run instead, so new and pre-existing findings are never mixed together in the same list. See Compare reports.

Why does Branch Review say my Cypress Accessibility changes are not ready yet?​

At least one of the two runs has not finished processing its report. Reports are assembled after Cypress Cloud marks a run complete, and grouped or parallelized runs also wait out the project's Run Completion Delay. Reload once both runs are complete. If a run was canceled, timed out, or re-ran only its failed specs or tests under Re-run optimization, its Cypress Accessibility report is marked partial and Branch Review says so, because a diff built on partial data can be misleading.

Why did my Cypress Accessibility score change when no application code changed?​

Four things move a score without a code change: someone edited the App Quality Config, which is worth checking first because a new filter or view rule changes what is counted; the tests reached different pages or states than usual; content changed in the environment under test, such as a published image without alternative text; or the Axe Core® version was updated. The Results API exposes both config and axeVersion so you can rule the last two in or out. See Notice when the report itself changes.

How do I detect accessibility regressions with Cypress on a site that isn't tied to pull requests?​

Record the Cypress project on a schedule against staging or production and compare consecutive runs in Branch Review, which works even when every run is on the same branch. This catches the changes no pull request would show, such as published content, a new version of an embedded third-party widget, or a feature flag enabling untested UI. See Production monitoring.

Can Cypress notify my team when accessibility results change?​

Yes, two ways. The Slack and Microsoft Teams integrations include the accessibility score, failed rules by severity, and failed element count in run notifications, and can be filtered by run tag or run group. For conditional alerts, act on the Results API response in CI, which includes deep links per rule and per view so a notification can point at the exact failure.

Use the Cypress Accessibility tab of Enterprise Reporting for scores, severity breakdowns, and weekly violation trends, filtered by date range, team, project, and branch. The same data is available through the Data Extract API with the accessibility-per-project-summary, accessibility-per-project-over-time, and accessibility-details reports. See Track trends over time.

Ignoring elements​

How do I exclude elements from Cypress Accessibility?​

Add an elementFilters rule with include: false for a CSS selector that matches the elements. Their failed and incomplete checks move to the Ignored status and stop counting against your views and your accessibility score. This is the standard way to handle third-party widgets whose violations you can't fix. To ignore only specific rules for an element, use the data-a11y-ignore attribute instead, and to ignore entire pages, use viewFilters.

Do ignored elements affect my Cypress Accessibility score?​

No. An element ignored by elementFilters doesn't count as a failed or incomplete element, and its results don't affect the score. It stays visible in the report under the Ignored status so you can always audit what your configuration ignores.

Why didn't my Cypress Accessibility score improve after ignoring an element?​

The accessibility score weighs each failed rule per snapshot, not each failing element. If a rule has several failing elements in a snapshot and you ignore only some of them, the rule still counts against that snapshot and the score doesn't change. The rule stops affecting the snapshot's score once all of its failing elements there are ignored.

Why is an element still failing in Cypress Accessibility after I added an elementFilters rule?​

The most common causes are:

  • The selector matches a container instead of the element itself. Rules use standard CSS matching against the element with the result, so footer matches only the <footer> element. Match the container and its descendants, like footer, footer *, to ignore a whole region.
  • The rule has a documentScope that doesn't match the element's iframe or shadow DOM hosts.
  • The report was processed before you saved the configuration. Regenerate the run to apply the current configuration.

Why do ignored elements still appear in my Cypress Accessibility report?​

This is by design. Ignored elements appear under the Ignored element status rather than being removed, so the report always shows what your configuration is hiding. They don't count as failed or incomplete elements, and they don't affect your score.

Can I ignore elements in Cypress Accessibility without affecting UI Coverage?​

Yes. An elementFilters list at the root of your configuration applies to both products, but nesting it under an accessibility or uiCoverage key applies it to that product only. A nested list completely replaces a root-level one for that product, and the two are not merged. See Exclude elements.

Does include: true do anything in Cypress Accessibility?​

Not on its own. Every element is included unless an exclude rule matches it, and an include rule can't protect an element from exclusion. The value matters in root-level elementFilters lists shared with UI Coverage, where include rules do protect their elements. See When to use include: true.

Grouping and naming views​

Why do similar URLs show up as separate views in my Cypress Accessibility report?​

Automatic grouping only replaces path segments that are numbers or IDs (UUIDs and UUID-like values) with a wildcard. Segments like usernames or slugs aren't recognized as dynamic, so /users/alice and /users/bob stay separate views, and a violation on that shared template is reported once per URL. Add a views pattern to group them into one view and triage the issue once.

Do query parameters create separate views in Cypress Accessibility?​

No. Query strings are ignored when grouping, so /dashboard?tab=overview and /dashboard?tab=settings become a single /dashboard view. If a query parameter meaningfully changes the page, use a views pattern with groupBy on that parameter to report on each value separately.

How do I create a separate Cypress Accessibility view for each value of a URL parameter?​

Write a views pattern that names the parameter, then list that name in groupBy. For a pattern like /analytics/:type/:id, groupBy: ["type"] creates a distinct view for each type value (such as /analytics/performance/:id and /analytics/usage/:id) while still collapsing the dynamic :id. groupBy accepts a single string or an array of strings, and each name can come from the path, query string, or hash. See Using groupBy.

Does grouping URLs into a view change my Cypress Accessibility score?​

Not your run-level score. The run score averages every snapshot in the run regardless of how snapshots are grouped, so grouping URLs into a view reorganizes the report without moving the top-line number. What changes is the per-view score: the snapshots you group roll up into one view's score instead of several, which makes each page's accessibility easier to read and track over time.

What's the difference between views and viewFilters in Cypress Accessibility?​

They do opposite things. views keeps URLs but changes how they're grouped and named, so related pages collapse into a single view or a dynamic route splits into several. viewFilters removes URLs, so matching snapshots are never scanned and don't appear in your report or score. Use views to organize the pages you scan, and viewFilters for pages you don't own or intend to remediate.

Can I configure views for Cypress Accessibility without affecting UI Coverage?​

No. Unlike viewFilters and elementFilters, views is defined only at the root of your configuration and can't be nested under an accessibility or uiCoverage key. A single set of view patterns groups URLs the same way for both products. To exclude a URL from one product only, use a nested viewFilters list instead. See Scope.

Ignoring views and URLs​

How do I exclude URLs from Cypress Accessibility?​

Add a viewFilters rule with include: false for a URL pattern. Snapshots from matching URLs are not scanned for accessibility violations and don't appear in your report. This is the standard way to keep third-party pages your tests pass through, such as an OAuth provider's login page, out of your results.

Can I exclude URLs from Cypress Accessibility without affecting UI Coverage?​

Yes. A viewFilters list at the root of your configuration applies to both products, but nesting it under an accessibility or uiCoverage key applies it to that product only. A nested list completely replaces a root-level one for that product, and the two are not merged. See Exclude views.

Why is a URL still in my Cypress Accessibility report after I excluded it with viewFilters?​

The most common causes are:

  • An earlier rule matches the URL first. Rules apply in order and the first match wins, so a broad include: true rule listed before your exclusion prevents it from ever applying.
  • The pattern doesn't match the full URL. Hostnames must match exactly (https://my-app.com/* doesn't match www.my-app.com), or you can use a path-only pattern like /admin/* to match any hostname.
  • The report was processed before you saved the configuration. Regenerate the run to apply the current configuration.

See troubleshooting view filters for details.

Element identification​

Which attributes does Cypress Accessibility use to identify elements?​

Cypress Accessibility checks a prioritized list of attributes on each element: data-cy, data-test, data-testid, data-test-id, data-qa, and row-id, in that order, falling back to id, name, class, and other DOM signals when none of those uniquely identify the element. See Element identification for how identification works across snapshots.

How do I make Cypress Accessibility use my own attribute in violation selectors?​

Add the attribute name to significantAttributes. Attributes you list are checked before the default list, in the order you list them, so an attribute your application already renders, such as data-component, can identify elements and appear as the violation target selector in your reports.

Does significantAttributes replace the default attribute list in Cypress Accessibility?​

No. Your attributes are checked first, and the defaults still apply after them, so an element without any of your attributes is identified exactly as it would be without configuration. Listing a default attribute like data-qa promotes it above the other defaults. To stop an attribute from being used at all, use attributeFilters instead.

Can I use aria-label as a significant attribute to review my labels?​

Yes. Any valid HTML attribute qualifies, not only data-* attributes. Listing aria-label identifies elements by their label text, so the elements you triage are shown by their labels. This adds a manual check on top of the automated one: Cypress Accessibility confirms that a control has an accessible name, but not that the name is understandable, so aria-label="button" passes the same name-presence rules as aria-label="Close dialog". Seeing the label as the identifier makes an unclear one easy to catch.

How do I add component or team context to my Cypress Accessibility violation selectors?​

Use components, a Cypress Accessibility-only option that adds attributes like data-component or data-team to the violation target selector when they're present on the element or one of its ancestors. Instead of a bare [data-cy="signup"], the target reads as [data-cy="signup"][data-component="IconButton"], so whoever picks up the issue, whether a developer, a Jira ticket, or an AI agent triaging through Cypress Cloud MCP, can see which component or team it belongs to without opening the page HTML. This differs from significantAttributes, which chooses the single attribute that identifies the element, whereas components adds context on top of that identifier.

What's the difference between significantAttributes and components in Cypress Accessibility?​

Both put your attributes into violation target selectors, but they play different roles. significantAttributes chooses the single attribute that identifies an element, so ["data-component"] makes the selector [data-component="SearchInput"] instead of a test id or generated selector. components adds attributes on top of whatever already identifies the element, so a selector stays [data-cy="signup"] but gains [data-component="IconButton"]. Use significantAttributes when your attribute is the best identifier, and components when you want to keep the identifier but append component, team, or page context around it.

Why isn't my components attribute showing up in my Cypress Accessibility selectors?​

The most common causes are:

  • The attribute isn't on the element or any of its ancestors. components keeps a listed attribute wherever it appears on the element or an ancestor, but it can't add one that isn't in the DOM.
  • includeInSelector is false, which keeps the entry for documentation but doesn't change selectors.
  • A componentAttributeFilters rule with include: false matches the value, so it's skipped.
  • The report was processed before you saved the configuration. Regenerate the run to apply the current configuration.

Can I keep certain component attribute values out of my Cypress Accessibility selectors?​

Yes. Add a componentAttributeFilters rule with include: false for the values you don't want appended, matched by regex. This is useful when an attribute is meaningful on some elements but generic on others, such as a data-component that's a specific component in most places but a layout primitive like Box elsewhere. The default attribute filters that drop dynamic values from identifying selectors don't apply to component attributes, so componentAttributeFilters are the only way to filter them.

Configuration​

Where do I set Cypress Accessibility configuration?​

In the App Quality tab of your project settings in Cypress Cloud. See Setting configuration.

Do I need to rerun my tests after changing configuration?​

No. You can regenerate any historical run from its Properties tab, and the report is reprocessed with the current configuration. This lets you iterate on configuration and see the effects immediately without running your Cypress tests again.

How do I apply a setting to Cypress Accessibility without changing UI Coverage?​

Nest the property under an accessibility key. viewFilters, elementFilters, significantAttributes, and attributeFilters apply to both products when set at the root, but a copy nested under accessibility applies to Cypress Accessibility alone. A nested value completely replaces the root value for that product rather than merging, so repeat any rules you still want. views is the exception: it's shared and can only be set at the root. See Configuration scope.

Can I read the configuration a Cypress Accessibility run was processed with?​

Yes, two ways. In Cypress Cloud, open the run's Properties tab to see the exact configuration that was applied. In CI, the Accessibility Results API exposes it on the config property of getAccessibilityResults(), where config.value is the applied App Quality configuration and config.updatedAt is when it was last saved. See Viewing configuration for a run.

How do I add a note explaining a Cypress Accessibility configuration rule?​

Add a comment property to the rule. Any rule defined as an object accepts one, and it's the supported place for notes because Cypress Cloud rejects properties it doesn't recognize. Comments live in your Cypress Accessibility configuration only and never appear in reports. See Comments.

Accessibility standards​

Does Cypress Accessibility make my application WCAG conformant or ADA compliant?​

No automated tool can determine that, and Cypress Accessibility doesn't claim to. What it reports is factual and narrow: which Axe-Core® rules passed, failed, or couldn't be evaluated on the pages and components your tests visited, on a specific run, with a recorded rule configuration and Axe-Core® version.

Determining conformance with the Web Content Accessibility Guidelines (WCAG), published by the W3C, requires human assessment of criteria no scanner can evaluate. Laws and procurement rules in different regions, including the Americans with Disabilities Act (ADA) in the United States, Section 508 for US federal agencies and their suppliers, and the European Accessibility Act (EAA), commonly point to WCAG as the technical reference. How any of those obligations apply to your organization is a legal question for you and your advisors, not an output of a testing tool. See accessibility automation principles for where automated checks stop.

Which WCAG version and level do the Cypress Accessibility rules cover?​

By default, a run evaluates Axe-Core®'s default ruleset: rules tagged for WCAG 2.0 and WCAG 2.1 Level A and AA, plus Deque's Best Practices rules. Three WCAG-tagged rules are turned off by default in Cypress Accessibility, and Axe-Core®'s WCAG 2.2, Level AAA, experimental, and deprecated rule groups are off unless Cypress enables them for your project. This means the default report is broader than any single WCAG level in one sense, because Best Practices findings are Deque recommendations rather than WCAG success criteria, and narrower in another, because it doesn't run every WCAG-tagged rule. See What the default ruleset covers.

Can Cypress Accessibility run WCAG 2.2 or Level AAA rules?​

Yes, on request. Axe-Core® ships those rules but keeps them off by default, so they don't run in Cypress Accessibility unless they're enabled for your project. Enabling them is a guided change Cypress applies for you rather than a setting in the App Quality editor, and historical runs can be regenerated so you can see the effect before adopting it. See How Cypress can tune the ruleset for your project.

Can I use Cypress Accessibility results in a VPAT or accessibility conformance report?​

You can reference them as one source of evidence, but they don't produce the document. A VPAT or accessibility conformance report is written by people evaluating a product against each criterion, and automated results speak only to the subset of criteria a scanner can check, on the pages and components your tests happened to visit.

What Cypress Accessibility contributes is a durable, dated record: every run permanently stores the rule configuration and Axe-Core® version it was processed with, viewable in the run's Properties tab, and the Results API exposes per-rule and per-view results you can archive alongside your own assessment notes.

Does a 100% Cypress Accessibility score mean my application is accessible?​

No. A 100% score means Axe-Core® detected no violations in the scope your tests covered, with the rules that were enabled for that run. It says nothing about criteria automated checks can't evaluate, such as whether a label is understandable, whether focus order matches the visual layout, or whether the experience works for someone using a screen reader end to end. Automated checks detect around 57% of the issues a manual audit surfaces. Treat a clean report as a solid foundation and a signal that your team is actively managing accessibility, not as a finished state. See What a 100% score means.

Axe Core® rules​

Which accessibility rules does Cypress Accessibility run?​

Cypress Accessibility runs Axe-Core®'s default ruleset against every captured snapshot, plus a few custom Cypress rules. That covers WCAG 2.0 and 2.1 Level A and AA, along with Deque's Best Practices rules, which are recommendations rather than WCAG success criteria. Rule groups that Axe-Core® keeps off by default, including WCAG 2.2, Level AAA, experimental, and deprecated rules, don't run unless Cypress enables them for your project. Three further rules are off by default in Cypress Accessibility: color-contrast, no-autoplay-audio, and meta-refresh. You don't add any assertions or cy. commands to your tests to run these checks; they run automatically when Cypress Accessibility is enabled. See What the default ruleset covers.

Can I change which Axe-Core® rules Cypress Accessibility runs?​

Yes. Cypress can tune the Cypress Accessibility ruleset for your project, including enabling a rule that's off by default, turning off a rule that's a known false positive, or scoping the report to a WCAG conformance target. This is a guided change applied by Cypress rather than a setting in the App Quality editor, so reach out to your Cypress point of contact. To ignore a rule for individual elements yourself, use the data-a11y-ignore attribute in your application code.

Why isn't color contrast reported in my Cypress Accessibility results?​

Color contrast checking is off by default in Cypress Accessibility because it's the slowest Axe-Core® rule and the most likely to produce false positives or incomplete results. It works well in many projects, so Cypress can turn it on for your project on request. Reach out to your Cypress point of contact. See Rules that are off by default.

How do I stop Cypress Accessibility from reporting a rule I can't fix?​

You have three options in Cypress Accessibility, from broadest to narrowest. Ask Cypress to disable the rule project-wide, which is a guided change applied for you; ignore the rule for specific elements yourself with the data-a11y-ignore attribute; or leave the rule on and control whether it blocks your build in CI with the Results API. Keeping a rule reported but non-blocking is often the best choice, since you retain visibility into the issue.

Does Cypress Accessibility work with component tests?​

Yes. Cypress Accessibility runs against component tests as well as end-to-end tests. Because a component is usually a page fragment, "page-level" rules that check page structure and document-wide attributes don't run for component tests, while the rest of the ruleset does. See Component testing.

Why does Cypress Accessibility skip some rules for my component tests?​

Cypress Accessibility skips page-level rules such as region, landmark-one-main, and document-title for component tests. A component is usually a fragment of a page, so rules that assert on overall page structure would report failures that don't apply to a component in isolation. Rules that evaluate the component itself, such as button-name and image-alt, still run.

Which version of Axe-Core® does Cypress Accessibility use?​

Cypress Accessibility pins a specific, tested version of Axe-Core® and waits at least 30 days before adopting a new release, so new or changed rules don't alter your results without warning. The exact version used for a run is shown in that run's Properties tab in Cypress Cloud and in the Results API response. See Axe-Core® library version and updates.

Profiles​

How do I apply different Cypress Accessibility settings to different runs?​

In your project's App Quality configuration in Cypress Cloud, add a profiles array, give each profile a name, and record the run with a matching --tag. When a run's tag matches a profile's name, that profile's config overrides your base Cypress Accessibility configuration for that run, so a smoke run and a full regression run can each use their own settings without changing your test code. If no tag matches, the base configuration is used unchanged.

Does a Cypress Accessibility profile override my base configuration or merge with it?​

Cypress Cloud overrides one property at a time with a shallow merge, not a deep merge. Any property the profile lists replaces the root value for that property entirely (arrays are replaced, not concatenated), so if a profile defines elementFilters, repeat any root rules you still want to keep. Properties the profile doesn't mention are inherited from the root. The accessibility and uiCoverage objects merge one level deep, so a profile can override accessibility.viewFilters while still inheriting accessibility.attributeFilters. See How a profile changes your configuration.

If a run has multiple tags that match profiles, which Cypress Accessibility profile is used?​

Cypress Cloud uses the first profile in the profiles array whose name matches one of the run's tags. The tie is broken by the order of the profiles array, not the order of the tags on the run, so reordering tags on the command line never changes which profile applies.

Why isn't my Cypress Accessibility profile applied even though I tagged the run?​

The most common causes are:

  • The run tag doesn't exactly match the profile name. Matching is case-sensitive and exact, so aq-config-regression matches only the tag aq-config-regression, not AQ-Config-Regression or aq-config-regression-nightly.
  • The tag never reached Cypress Cloud. Profiles are selected from the tags passed to cypress run --record --tag, so a run recorded without --record, or without that specific --tag, falls back to the base configuration.
  • An earlier profile in the array also matches one of the tags and is used instead, because the first match wins.
  • The report was processed before you saved the configuration. Regenerate the run to apply the current configuration.

Can a profile turn off Cypress Accessibility or skip a run entirely?​

There's no dedicated "skip this run" switch in a profile. To suppress a report for certain runs, point a profile at a deliberately narrow configuration (for example, viewFilters that exclude every view) so Cypress Cloud produces an empty or tightly scoped accessibility report for the run instead. See Why use profiles?.

How do I make Cypress Accessibility checks on pull requests faster and more focused than regression runs?​

Add a profile (for example, aq-config-pr) whose config narrows the report to your most critical flows with viewFilters, then tag pull request runs with cypress run --record --tag "aq-config-pr". The pull request report covers only those flows, so it's small and unambiguous for a developer to act on before merging, while regression runs record without the tag and keep the full base configuration. Combine the profile with the Results API to fail the build when a critical flow regresses. See Block pull requests.

Can a Cypress Accessibility profile change which Axe Core® rules run for a specific run?​

No. A profile's config can override the App Quality settings in the editor (views, viewFilters, elementFilters, significantAttributes, attributeFilters, and components), but the Axe Core® ruleset isn't one of those settings. Enabling a rule that's off by default (such as color-contrast), turning off a false positive, or scoping to a WCAG target is a guided change Cypress applies at the project level, so it can't vary run to run through a profile. To ignore a rule only for certain elements yourself, use the data-a11y-ignore attribute in your application code.

Can a Cypress Accessibility profile change how violation targets are identified, such as components or significantAttributes, for certain runs?​

Yes. Anything you can set under an accessibility key can go in a profile's config, including components and significantAttributes. Because the accessibility object merges one level deep, a profile can override just one of them, for example identifying elements by aria-label during a labels audit, while inheriting the rest. See How a profile changes your configuration.

Contents