Skip to main content
Cypress AccessibilityPremium Solution

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 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 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.

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: 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?​

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.

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.

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?.

See also​

Contents