---
id: accessibility/faq
title: Cypress Accessibility FAQ
description: >-
  Get answers to common questions about Cypress Accessibility, including
  ignoring elements with elementFilters, excluding URLs with viewFilters, the
  Ignored status, score impact, element identification, configuration, and
  per-run profiles.
section: accessibility
source_path: docs/accessibility/faq.mdx
version: f34ccd0f7020c81960fdf46482581b53df6955f6
updated_at: '2026-07-21T17:45:38.426Z'
---
# Cypress Accessibility FAQ

## Ignoring elements

### How do I exclude elements from Cypress Accessibility?

Add an [`elementFilters`](/llm/markdown/accessibility/configuration/elementfilters.md) 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](/llm/markdown/accessibility/core-concepts/accessibility-score.md). 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](/llm/markdown/accessibility/configuration/ignoring-rules-per-element.md) instead, and to ignore entire pages, use [`viewFilters`](/llm/markdown/accessibility/configuration/viewfilters.md).

### Do ignored elements affect my accessibility score?

No. An element ignored by [`elementFilters`](/llm/markdown/accessibility/configuration/elementfilters.md) 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](/llm/markdown/accessibility/core-concepts/accessibility-score.md) 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](/llm/markdown/accessibility/core-concepts/run-level-reports.md#Elements) 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](/llm/markdown/accessibility/configuration/elementfilters.md#Scope).

### 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](/llm/markdown/accessibility/configuration/elementfilters.md#When-to-use-include-true).

## Ignoring views and URLs

### How do I exclude URLs from Cypress Accessibility?

Add a [`viewFilters`](/llm/markdown/accessibility/configuration/viewfilters.md) 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](/llm/markdown/accessibility/configuration/viewfilters.md#Scope).

### 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](/llm/markdown/accessibility/configuration/viewfilters.md#A-URL-you-excluded-still-appears-in-the-report) 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](/llm/markdown/accessibility/core-concepts/element-identification.md) 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`](/llm/markdown/accessibility/configuration/significantattributes.md). 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`](/llm/markdown/accessibility/configuration/attributefilters.md) 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`](/llm/markdown/accessibility/configuration/significantattributes.md) 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](/llm/markdown/accessibility/configuration/overview.md#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`](/llm/markdown/accessibility/configuration/profiles.md) array, give each profile a `name`, and record the run with a matching [`--tag`](/llm/markdown/app/references/command-line.md#cypress-run-tag-lt-tag-gt). 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`](/llm/markdown/accessibility/configuration/elementfilters.md), 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](/llm/markdown/accessibility/configuration/profiles.md#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`](/llm/markdown/accessibility/configuration/profiles.md) 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`](/llm/markdown/accessibility/configuration/viewfilters.md) that exclude every view) so Cypress Cloud produces an empty or tightly scoped accessibility report for the run instead. See [Why use profiles?](/llm/markdown/accessibility/configuration/profiles.md#Why-use-profiles).

## See also

*   [Configuration overview](/llm/markdown/accessibility/configuration/overview.md) lists every configuration option and what each one is for.
*   [`profiles`](/llm/markdown/accessibility/configuration/profiles.md) apply different configuration to runs based on run tags.
*   [`elementFilters`](/llm/markdown/accessibility/configuration/elementfilters.md) is the full reference for ignoring elements.
*   [`viewFilters`](/llm/markdown/accessibility/configuration/viewfilters.md) is the full reference for excluding URLs.
*   [Run-level reports](/llm/markdown/accessibility/core-concepts/run-level-reports.md) explains element statuses, including **Ignored**.