{ "doc": { "id": "ui-coverage/configuration/overview", "title": "Configure UI Coverage in Cypress", "description": "Configure Cypress UI Coverage to get a coverage score you can trust: ignore dynamic attributes, filter out noise, group elements, shape views, and count the interactions that matter.", "section": "ui-coverage", "source_path": "/llm/markdown/ui-coverage/configuration/overview.md", "version": "e6c8d867c21227247f14714fb5690c7c018983c5", "updated_at": "2026-08-08T12:39:37.868Z", "headings": [ { "id": "ui-coverage/configuration/overview#configuration-overview", "text": "Configuration overview", "level": 1 }, { "id": "ui-coverage/configuration/overview#setting-configuration", "text": "Setting configuration", "level": 2 }, { "id": "ui-coverage/configuration/overview#who-can-edit-configuration", "text": "Who can edit configuration", "level": 3 }, { "id": "ui-coverage/configuration/overview#configuration-options", "text": "Configuration options", "level": 2 }, { "id": "ui-coverage/configuration/overview#which-option-do-i-need", "text": "Which option do I need?", "level": 3 }, { "id": "ui-coverage/configuration/overview#comments", "text": "Comments", "level": 3 }, { "id": "ui-coverage/configuration/overview#full-configuration-reference", "text": "Full configuration reference", "level": 3 }, { "id": "ui-coverage/configuration/overview#how-rules-are-applied", "text": "How rules are applied", "level": 2 }, { "id": "ui-coverage/configuration/overview#configuration-scope", "text": "Configuration scope", "level": 2 }, { "id": "ui-coverage/configuration/overview#viewing-configuration-for-a-run", "text": "Viewing configuration for a run", "level": 2 }, { "id": "ui-coverage/configuration/overview#in-cypress-cloud", "text": "In Cypress Cloud", "level": 3 }, { "id": "ui-coverage/configuration/overview#from-the-results-api", "text": "From the Results API", "level": 3 }, { "id": "ui-coverage/configuration/overview#see-also", "text": "See also", "level": 2 } ] }, "content": { "type": "root", "children": [ { "type": "heading", "depth": 1, "children": [ { "type": "text", "value": "Configuration overview" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "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:" } ] }, { "type": "list", "ordered": false, "start": null, "spread": false, "children": [ { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "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." } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "Removing noise: filter out third-party widgets, admin-only pages, and elements your team doesn't own so the report focuses on what matters." } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "Organizing reports around your product: group related elements and shape how URLs roll up into " }, { "type": "link", "title": null, "url": "/llm/markdown/ui-coverage/core-concepts/views.md", "children": [ { "type": "text", "value": "views" } ] }, { "type": "text", "value": " that map to real pages and flows." } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "Counting the interactions you care about: recognize custom or plugin commands, require a meaningful interaction on specific elements, and even credit assertions as coverage." } ] } ] } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "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." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "UI Coverage turns your runs into a visual map of the interactive elements your tests exercise and the ones they miss, with no code changes or instrumentation. " }, { "type": "link", "title": null, "url": "https://www.cypress.io/ui-coverage?utm_medium=premium-solution-tip&utm_source=docs.cypress.io&utm_content=Schedule%20a%20demo", "children": [ { "type": "text", "value": "Schedule a demo" } ] }, { "type": "text", "value": "." } ] }, { "type": "heading", "depth": 2, "children": [ { "type": "text", "value": "Setting configuration" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Configuration lives in Cypress Cloud, not in your repository. To view or change it for a project:" } ] }, { "type": "list", "ordered": true, "start": 1, "spread": false, "children": [ { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "Open your project in Cypress Cloud and go to Project Settings." } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "Select the App Quality tab, which holds the configuration editor." } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "Edit the configuration as JSON, then Save. Discard reverts unsaved edits back to the last saved version." } ] } ] } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "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." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "After you save configuration changes, you can reprocess any historical run to apply them. You can start a reprocess from two places:" } ] }, { "type": "list", "ordered": false, "start": null, "spread": false, "children": [ { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "The Properties tab, using the \"regenerate\" button next to the configuration values that were used for that run." } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "The UI Coverage report, using the \"configuration updated\" message that appears when you view a historical run that was processed with an older configuration." } ] } ] } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Regenerating reports in this way allows you to make config changes and see their effects without running your Cypress tests again." } ] }, { "type": "heading", "depth": 3, "children": [ { "type": "text", "value": "Who can edit configuration" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Editing is limited to Admin users by default. Your Cypress point-of-contact can enable editing for all users on request." } ] }, { "type": "heading", "depth": 2, "children": [ { "type": "text", "value": "Configuration options" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "For a quick overview of the practical application of the most common UI Coverage configuration properties, you can read " }, { "type": "link", "title": null, "url": "https://www.cypress.io/blog/making-the-most-of-ui-coverage", "children": [ { "type": "text", "value": "this blog post" } ] }, { "type": "text", "value": "." } ] }, { "type": "heading", "depth": 3, "children": [ { "type": "text", "value": "Which option do I need?" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Several options change what appears in reports and how it's organized. Pick the one that matches your goal:" } ] }, { "type": "table", "align": [ null, null ], "children": [ { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "Your goal" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "Use" } ] } ] }, { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "Control how URLs are grouped into views" } ] }, { "type": "tableCell", "children": [ { "type": "link", "title": null, "url": "/llm/markdown/ui-coverage/configuration/views.md", "children": [ { "type": "text", "value": "`views`" } ] } ] } ] }, { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "Remove entire views from reports" } ] }, { "type": "tableCell", "children": [ { "type": "link", "title": null, "url": "/llm/markdown/ui-coverage/configuration/viewfilters.md", "children": [ { "type": "text", "value": "`viewFilters`" } ] } ] } ] }, { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "Remove elements from reports and scores entirely" } ] }, { "type": "tableCell", "children": [ { "type": "link", "title": null, "url": "/llm/markdown/ui-coverage/configuration/elementfilters.md", "children": [ { "type": "text", "value": "`elementFilters`" } ] } ] } ] }, { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "Rename or stabilize the identity of a single element" } ] }, { "type": "tableCell", "children": [ { "type": "link", "title": null, "url": "/llm/markdown/ui-coverage/configuration/elements.md", "children": [ { "type": "text", "value": "`elements`" } ] } ] } ] }, { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "Combine repeated or related elements so they count as one" } ] }, { "type": "tableCell", "children": [ { "type": "link", "title": null, "url": "/llm/markdown/ui-coverage/configuration/elementgroups.md", "children": [ { "type": "text", "value": "`elementGroups`" } ] } ] } ] }, { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "Define groups in your application's markup instead of configuration" } ] }, { "type": "tableCell", "children": [ { "type": "link", "title": null, "url": "/llm/markdown/ui-coverage/core-concepts/element-grouping.md#Grouping-with-markup-attributes", "children": [ { "type": "text", "value": "`data-cy-ui-group` attribute" } ] } ] } ] }, { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "Prioritize your own attributes for identifying and naming elements" } ] }, { "type": "tableCell", "children": [ { "type": "link", "title": null, "url": "/llm/markdown/ui-coverage/configuration/significantattributes.md", "children": [ { "type": "text", "value": "`significantAttributes`" } ] } ] } ] }, { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "Stop dynamic or generated attributes from identifying elements" } ] }, { "type": "tableCell", "children": [ { "type": "link", "title": null, "url": "/llm/markdown/ui-coverage/configuration/attributefilters.md", "children": [ { "type": "text", "value": "`attributeFilters`" } ] } ] } ] }, { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "Count your custom commands as interactions" } ] }, { "type": "tableCell", "children": [ { "type": "link", "title": null, "url": "/llm/markdown/ui-coverage/configuration/additionalinteractioncommands.md", "children": [ { "type": "text", "value": "`additionalInteractionCommands`" } ] } ] } ] }, { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "Limit which interaction commands count for specific elements" } ] }, { "type": "tableCell", "children": [ { "type": "link", "title": null, "url": "/llm/markdown/ui-coverage/configuration/allowedinteractioncommands.md", "children": [ { "type": "text", "value": "`allowedInteractionCommands`" } ] } ] } ] }, { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "Apply different configuration to runs based on run tags" } ] }, { "type": "tableCell", "children": [ { "type": "link", "title": null, "url": "/llm/markdown/ui-coverage/configuration/profiles.md", "children": [ { "type": "text", "value": "`profiles`" } ] } ] } ] } ] }, { "type": "heading", "depth": 3, "children": [ { "type": "text", "value": "Comments" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "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 " }, { "type": "link", "title": null, "url": "/llm/markdown/ui-coverage/configuration/significantattributes.md", "children": [ { "type": "text", "value": "`significantAttributes`" } ] }, { "type": "text", "value": " and " }, { "type": "link", "title": null, "url": "/llm/markdown/ui-coverage/configuration/additionalinteractioncommands.md", "children": [ { "type": "text", "value": "`additionalInteractionCommands`" } ] }, { "type": "text", "value": ", do not take a per-entry comment." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "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." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "App Quality Config" } ] }, { "type": "code", "lang": null, "meta": null, "value": "{ \"elementFilters\": [ { \"selector\": \".intercom-launcher\", \"include\": false, \"comment\": \"Third-party chat widget, not covered by our tests\" } ]}" }, { "type": "heading", "depth": 3, "children": [ { "type": "text", "value": "Full configuration reference" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "The shape of every available option, with the type each value expects:" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "App Quality Config" } ] }, { "type": "code", "lang": null, "meta": null, "value": "{ \"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 } } ]}" }, { "type": "heading", "depth": 2, "children": [ { "type": "text", "value": "How rules are applied" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Two behaviors govern every rule you write, regardless of which property it belongs to:" } ] }, { "type": "list", "ordered": false, "start": null, "spread": false, "children": [ { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "Order matters. For " }, { "type": "link", "title": null, "url": "/llm/markdown/ui-coverage/configuration/elementfilters.md", "children": [ { "type": "text", "value": "`elementFilters`" } ] }, { "type": "text", "value": ", " }, { "type": "link", "title": null, "url": "/llm/markdown/ui-coverage/configuration/viewfilters.md", "children": [ { "type": "text", "value": "`viewFilters`" } ] }, { "type": "text", "value": ", and " }, { "type": "link", "title": null, "url": "/llm/markdown/ui-coverage/configuration/elementgroups.md", "children": [ { "type": "text", "value": "`elementGroups`" } ] }, { "type": "text", "value": ", 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. " }, { "type": "link", "title": null, "url": "/llm/markdown/ui-coverage/configuration/elements.md", "children": [ { "type": "text", "value": "`elements`" } ] }, { "type": "text", "value": " is the exception: when more than one rule matches the same element, the last one wins." } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "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 " }, { "type": "link", "title": null, "url": "#Comments", "children": [ { "type": "text", "value": "`comment`" } ] }, { "type": "text", "value": "." } ] } ] } ] }, { "type": "heading", "depth": 2, "children": [ { "type": "text", "value": "Configuration scope" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Some properties are shared across App Quality products, and some belong to UI Coverage alone." } ] }, { "type": "list", "ordered": false, "start": null, "spread": false, "children": [ { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "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." } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "Shared, but not nestable: `views` applies to both UI Coverage and Cypress Accessibility and can only be set at the root." } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "UI Coverage only: `elementGroups`, `elements`, `additionalInteractionCommands`, and `allowedInteractionCommands` are specific to UI Coverage and are always set under the `uiCoverage` key." } ] } ] } ] }, { "type": "heading", "depth": 2, "children": [ { "type": "text", "value": "Viewing configuration for a run" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "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." } ] }, { "type": "heading", "depth": 3, "children": [ { "type": "text", "value": "In Cypress Cloud" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "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 " }, { "type": "link", "title": null, "url": "#Setting-configuration", "children": [ { "type": "text", "value": "regenerate" } ] }, { "type": "text", "value": " the run to reprocess it with the current configuration." } ] }, { "type": "heading", "depth": 3, "children": [ { "type": "text", "value": "From the Results API" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "The " }, { "type": "link", "title": null, "url": "/llm/markdown/ui-coverage/results-api.md", "children": [ { "type": "text", "value": "UI Coverage Results API" } ] }, { "type": "text", "value": " exposes the applied configuration on the `config` property of its result, so you can read it in a CI workflow:" } ] }, { "type": "code", "lang": null, "meta": null, "value": "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) }})" }, { "type": "paragraph", "children": [ { "type": "text", "value": "If no configuration was applied to the run, `config` may be absent, so check for it before reading `value`." } ] }, { "type": "heading", "depth": 2, "children": [ { "type": "text", "value": "See also" } ] }, { "type": "list", "ordered": false, "start": null, "spread": false, "children": [ { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "link", "title": null, "url": "/llm/markdown/ui-coverage/configuration/views.md", "children": [ { "type": "text", "value": "Views" } ] } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "link", "title": null, "url": "/llm/markdown/ui-coverage/configuration/viewfilters.md", "children": [ { "type": "text", "value": "View Filters" } ] } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "link", "title": null, "url": "/llm/markdown/ui-coverage/configuration/elementfilters.md", "children": [ { "type": "text", "value": "Element Filters" } ] } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "link", "title": null, "url": "/llm/markdown/ui-coverage/configuration/elements.md", "children": [ { "type": "text", "value": "Elements" } ] } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "link", "title": null, "url": "/llm/markdown/ui-coverage/configuration/elementgroups.md", "children": [ { "type": "text", "value": "Element Groups" } ] } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "link", "title": null, "url": "/llm/markdown/ui-coverage/configuration/significantattributes.md", "children": [ { "type": "text", "value": "Significant Attributes" } ] } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "link", "title": null, "url": "/llm/markdown/ui-coverage/configuration/attributefilters.md", "children": [ { "type": "text", "value": "Attribute Filters" } ] } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "link", "title": null, "url": "/llm/markdown/ui-coverage/configuration/additionalinteractioncommands.md", "children": [ { "type": "text", "value": "Additional Interaction Commands" } ] } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "link", "title": null, "url": "/llm/markdown/ui-coverage/configuration/allowedinteractioncommands.md", "children": [ { "type": "text", "value": "Allowed Interaction Commands" } ] } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "link", "title": null, "url": "/llm/markdown/ui-coverage/configuration/profiles.md", "children": [ { "type": "text", "value": "Profiles" } ] } ] } ] } ] } ] }, "token_estimate": 1843 }