Cypress Accessibility FAQ
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 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 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 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
footermatches only the<footer>element. Match the container and its descendants, likefooter, footer *, to ignore a whole region. - The rule has a
documentScopethat 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 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 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 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 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 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: truerule 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 matchwww.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?
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.
componentskeeps a listed attribute wherever it appears on the element or an ancestor, but it can't add one that isn't in the DOM. includeInSelectorisfalse, which keeps the entry for documentation but doesn't change selectors.- A
componentAttributeFiltersrule withinclude: falsematches 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.
Axe Core® rules
Which accessibility rules does Cypress Accessibility run?
Cypress Accessibility runs the full Axe-Core® ruleset against every captured snapshot, plus a few custom Cypress rules. A small number of Axe-Core® rules are off by default: 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.
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, soaq-config-regressionmatches only the tagaq-config-regression, notAQ-Config-Regressionoraq-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 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.