Skip to main content
UI CoveragePremium Solution

Configuration overview

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

  • Reflecting your app, not the framework: ignore dynamic or auto-generated attributes so the same button is recognized as one element across snapshots instead of many.
  • Removing noise: filter out third-party widgets, admin-only pages, and elements your team doesn't own so the report focuses on what matters.
  • Organizing reports around your product: group related elements and shape how URLs roll up into views that map to real pages and flows.
  • Counting the interactions you care about: recognize custom or plugin commands, require a meaningful interaction on specific elements, and even credit assertions as coverage.

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.

The Cypress Cloud UI showing the configuration editor

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 UI Coverage 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 allows you to make config changes and see their effects 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​

info

For a quick overview of the practical application of the most common UI Coverage configuration properties, you can read this blog post.

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 goalUse
Control how URLs are grouped into viewsviews
Remove entire views from reportsviewFilters
Remove elements from reports and scores entirelyelementFilters
Rename or stabilize the identity of a single elementelements
Combine repeated or related elements so they count as oneelementGroups
Define groups in your application's markup instead of configurationdata-cy-ui-group attribute
Prioritize your own attributes for identifying and naming elementssignificantAttributes
Stop dynamic or generated attributes from identifying elementsattributeFilters
Count your custom commands as interactionsadditionalInteractionCommands
Limit which interaction commands count for specific elementsallowedInteractionCommands
Apply different configuration to runs based on run tagsprofiles

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 and additionalInteractionCommands, 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": ".intercom-launcher",
      "include": false,
      "comment": "Third-party chat widget, not covered by our tests"
    }
  ]
}

Full configuration reference​

The shape of every available option, with the type each value expects:

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
    }
  ],
  "uiCoverage": {
    "elements": [
      {
        "selector": string,
        "name": string,
        "documentScope": [string],
        "comment": string
      }
    ],
    "elementGroups": [
      {
        "selector": string,
        "name": string,
        "documentScope": [string],
        "comment": string
      }
    ],
    "significantAttributes": [
      string
    ],
    "attributeFilters": [
      {
        "attribute": string,
        "value": string,
        "include": boolean,
        "comment": string
      }
    ],
    "additionalInteractionCommands": [
      string
    ],
    "allowedInteractionCommands": [
      {
        "selector": string,
        "commands": [string],
        "documentScope": [string],
        "comment": string
      }
    ]
  },
  "profiles": [
    {
      "name": string,
      "config": {
        // Any App Quality configuration options
      }
    }
  ]
}

How rules are applied​

Two behaviors govern every rule you write, regardless of which property it belongs to:

  • Order matters. For elementFilters, viewFilters, and elementGroups, rules are evaluated top to bottom and the first rule that matches an element or URL wins; later rules that also match it are ignored. List specific rules before broad, catch-all rules, and place an include: true exception above the include: false rule it should override. elements is the exception: when more than one rule matches the same element, the last one wins.
  • 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 UI Coverage alone.

  • Shared properties: elementFilters, viewFilters, attributeFilters, and significantAttributes apply to both UI Coverage and Cypress Accessibility when set at the root of your configuration. To apply one to a single product, nest it under a uiCoverage or 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 UI Coverage and Cypress Accessibility and can only be set at the root.
  • UI Coverage only: elementGroups, elements, additionalInteractionCommands, and allowedInteractionCommands are specific to UI Coverage and are always set under the uiCoverage key.

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, as shown below. 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.

The properties tab for a run, with an Application Quality section at the bottom

From the Results API​

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

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

getUICoverageResults().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​

Contents