Cypress AccessibilityPremium Solution

Configuration overview

Cypress Accessibility works out of the box with no setup, but a few lines of configuration make your reports match your application. Configuration lets you get an accessibility score you can trust and act on by:

• Reporting on the application you own: ignore third-party widgets, embedded content, and pages outside your control so violations you can't fix stop counting against your score.
• Organizing reports around your product: group related URLs into views that map to real pages and flows, so a violation on a shared template is triaged once instead of once per URL.
• Speaking your team's vocabulary: identify violation targets by your own attributes, such as a component name or automation ID, so an issue reads as "the ProductImage component" instead of a generated selector.
• Stabilizing identification across snapshots: stop dynamic or auto-generated attributes from splitting one element into many, so the same element is recognized as one across the many snapshots in a run.

You don't need any of this to get started, and you can add it incrementally. Reprocess a past run after each change to see the effect immediately, without re-running your tests.

Setting Configuration

Configuration lives in Cypress Cloud, not in your repository. To view or change it for a project:

1. Open your project in Cypress Cloud and go to Project Settings.
2. Select the App Quality tab, which holds the configuration editor.
3. Edit the configuration as JSON, then Save. Discard reverts unsaved edits back to the last saved version.

The editor validates your JSON against the schema when you save, so an invalid configuration can't be saved, and it shows how long ago the configuration was last saved.

After you save configuration changes, you can reprocess any historical run to apply them. You can start a reprocess from two places:

• The Properties tab, using the "regenerate" button next to the configuration values that were used for that run.
• The accessibility report, using the "configuration updated" message that appears when you view a historical run that was processed with an older configuration.

Regenerating reports in this way lets you iterate on configuration and see the effects immediately, without running your Cypress tests again.

Who can edit configuration

Editing is limited to Admin users by default. Your Cypress point-of-contact can enable editing for all users on request.

Configuration options

Which option do I need?

Several options change what appears in reports and how it's organized. Pick the one that matches your goal:

Your goal	Use
Group related URLs into a single view	views
Remove entire pages or URLs from reports	viewFilters
Remove elements from reports and the score entirely	elementFilters
Enable, disable, or tune individual Axe Core® rules	Axe Core® configuration
Keep an element but ignore specific rules for it	data-a11y-ignore attribute
Identify violation targets by your own attributes	significantAttributes
Stop dynamic or generated attributes from identifying elements	attributeFilters
Add component context to violation-target selectors	components
Apply different configuration to runs based on run tags	profiles

Comments

Most configuration rules support an optional comment property that you can use to record why a value is set. This makes your configuration easier to understand and maintain, especially when working in a team or revisiting configuration after some time. Any rule defined as an object accepts a comment; the options that are plain lists of strings, such as significantAttributes, do not take a per-entry comment.

A comment lives inside the rule and has no effect on behavior. Comments appear only in the configuration itself and are never displayed in reports. Because Cypress Cloud validates every rule and rejects properties it doesn't recognize, comment is the supported place to keep notes.

App Quality Config

{
  "elementFilters": [
    {
      "selector": "#onetrust-banner-sdk, #onetrust-banner-sdk *",
      "include": false,
      "comment": "Third-party cookie consent banner, violations reported upstream to the vendor"
    }
  ]
}

Full configuration reference

The shape of every available option, with the type each value expects. Every property is optional, and you only include the ones you need:

App Quality Config

{
  "views": [
    {
      "pattern": string,
      "groupBy": string | [string],
      "comment": string
    }
  ],
  "viewFilters": [
    {
      "pattern": string,
      "include": boolean,
      "comment": string
    }
  ],
  "elementFilters": [
    {
      "selector": string,
      "include": boolean,
      "documentScope": [string],
      "comment": string
    }
  ],
  "significantAttributes": [string],
  "attributeFilters": [
    {
      "attribute": string,
      "value": string,
      "include": boolean,
      "comment": string
    }
  ],
  "accessibility": {
    // Any of the shared properties above can be nested here to apply to
    // Cypress Accessibility only, replacing the root value for that property.
    "viewFilters": [ /* same shape as the root viewFilters */ ],
    "elementFilters": [ /* same shape as the root elementFilters */ ],
    "significantAttributes": [string],
    "attributeFilters": [ /* same shape as the root attributeFilters */ ],
    "components": {
      "componentAttributes": [
        {
          "attributeName": string,
          "includeInSelector": boolean,
          "comment": string
        }
      ],
      "componentAttributeFilters": [
        {
          "attribute": string,
          "value": string,
          "include": boolean,
          "comment": string
        }
      ],
      "comment": string
    },
    "comment": string
  },
  "profiles": [
    {
      "name": string,
      "config": {
        // Any App Quality configuration options
      },
      "comment": string
    }
  ]
}

Two accessibility-specific controls live outside this JSON: Axe Core® rule configuration is handled with your Account Executive, and the per-element data-a11y-ignore attribute is added to your application's markup.

How rules are applied

A few behaviors govern the rules you write, and some of them differ from UI Coverage:

• viewFilters: first match wins. URLs are compared against your rules top to bottom, and the first rule whose pattern matches decides whether that URL is included. List specific rules before broad, catch-all rules. URLs that match no rule are included by default.
• elementFilters: any exclude wins. In Cypress Accessibility, an element is ignored when any include: false rule matches it, regardless of where the rule sits in the list, and an include: true rule can't protect an element from an exclusion elsewhere. This is different from UI Coverage, where the first matching rule wins. See When to use include: true.
• significantAttributes: order sets priority. The attributes you list are checked before the default attributes, in the order you list them, and the first one that uniquely identifies an element becomes its violation-target selector.
• Unknown properties are rejected. When you save, Cypress Cloud validates your configuration against a strict schema and rejects anything it doesn't recognize, such as a misspelled property, a value of the wrong type, or a note on a property that doesn't accept one. Correct the flagged property to save, and keep freeform notes in a comment.

Configuration scope

Some properties are shared across App Quality products, and some belong to Cypress Accessibility alone.

• Shared properties: viewFilters, elementFilters, significantAttributes, and attributeFilters apply to both Cypress Accessibility and UI Coverage when set at the root of your configuration. To apply one to Cypress Accessibility only, nest it under an accessibility key. A nested value completely replaces the root-level value for that product (the two are not merged), so repeat any shared rules you still want in the nested list.
• Shared, but not nestable: views applies to both Cypress Accessibility and UI Coverage and can only be set at the root.
• Accessibility only: components shapes the violation-target selectors in your accessibility reports and is always set under the accessibility key. UI Coverage has its own product-only options (elements, elementGroups, and interaction commands) set under a uiCoverage key. See the UI Coverage configuration overview for those.

Viewing Configuration for a Run

Every run permanently records the exact configuration it was processed with, so the runs themselves are the history of how your configuration has changed over time. You can review a run's configuration in Cypress Cloud, or read it programmatically with the Results API.

In Cypress Cloud

To review the configuration a specific run used, open its Properties tab, shown in the Setting Configuration screenshot above. This displays the configuration as it was applied when the run was processed. When you open a run that was processed with an older configuration than the one currently saved, the report flags it with a "configuration updated" message, and you can regenerate the run to reprocess it with the current configuration.

From the Results API

The Accessibility Results API exposes the applied configuration on the config property of its result, so you can read it in a CI workflow:

read-accessibility-config.js

const { getAccessibilityResults } = require('@cypress/extract-cloud-results')

getAccessibilityResults().then((results) => {
  if (results.config) {
    // ISO timestamp of when the applied configuration was last saved
    console.log(results.config.updatedAt)

    // The App Quality configuration that was applied to the run
    console.log(results.config.value)
  }
})

If no configuration was applied to the run, config may be absent, so check for it before reading value.

See also

• Group & name views
• Exclude views
• Exclude elements
• Ignore rules per element
• Axe Core® configuration
• Prioritize identifying attributes
• Ignore attributes for identification
• Define components
• Override config by run tag
• Cypress Accessibility FAQ