{ "doc": { "id": "ui-coverage/troubleshooting", "title": "Troubleshooting: UI Coverage", "description": "Fix common Cypress UI Coverage report problems: duplicate elements, mis-grouped elements, tested elements shown as untested, configuration that has no effect, and unexpected coverage scores.", "section": "ui-coverage", "source_path": "/llm/markdown/ui-coverage/troubleshooting.md", "version": "29f95bf8bb06f320986f3749f5bf09a35a409eab", "updated_at": "2026-09-04T10:49:54.630Z", "headings": [ { "id": "ui-coverage/troubleshooting#troubleshooting-ui-coverage", "text": "Troubleshooting UI Coverage", "level": 1 }, { "id": "ui-coverage/troubleshooting#one-element-is-reported-as-many", "text": "One element is reported as many", "level": 2 }, { "id": "ui-coverage/troubleshooting#distinct-elements-are-reported-as-one", "text": "Distinct elements are reported as one", "level": 2 }, { "id": "ui-coverage/troubleshooting#similar-elements-arent-grouped-together", "text": "Similar elements aren't grouped together", "level": 2 }, { "id": "ui-coverage/troubleshooting#unrelated-elements-are-grouped-together", "text": "Unrelated elements are grouped together", "level": 2 }, { "id": "ui-coverage/troubleshooting#an-element-you-tested-is-shown-as-untested", "text": "An element you tested is shown as untested", "level": 2 }, { "id": "ui-coverage/troubleshooting#an-element-stops-counting-after-you-add-an-allowedinteractioncommands-rule", "text": "An element stops counting after you add an allowedInteractionCommands rule", "level": 2 }, { "id": "ui-coverage/troubleshooting#a-configuration-rule-has-no-effect", "text": "A configuration rule has no effect", "level": 2 }, { "id": "ui-coverage/troubleshooting#the-coverage-score-looks-wrong", "text": "The coverage score looks wrong", "level": 2 }, { "id": "ui-coverage/troubleshooting#still-stuck", "text": "Still stuck?", "level": 2 } ] }, "content": { "type": "root", "children": [ { "type": "heading", "depth": 1, "children": [ { "type": "text", "value": "Troubleshooting UI Coverage" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "UI Coverage produces a report for every recorded run with no setup, and for most applications the defaults are accurate on their own. When a report doesn't match what you expect, the cause is usually one of a small, predictable set: an unstable attribute that splits one control into many, a generic identifier that merges distinct controls, an interaction UI Coverage doesn't recognize, or a configuration change that hasn't been applied to the run yet." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "This page maps each symptom to its cause and the configuration that resolves it. Because you can " }, { "type": "link", "title": null, "url": "/llm/markdown/ui-coverage/configuration/overview.md#Setting-configuration", "children": [ { "type": "text", "value": "regenerate" } ] }, { "type": "text", "value": " any past run with your current configuration, you can confirm every fix in minutes without re-running your Cypress tests, so the fastest path to a coverage score you trust is to make one change, regenerate a recent run, and check the result." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Every run is processed with the configuration that was saved at that moment, so edits you make afterward don't change an existing report until you reprocess it. This timing is the single most common reason a rule \"doesn't work.\"" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "After saving configuration in the App Quality tab of your project settings, open a run's Properties tab and use its \"regenerate\" button, or the \"configuration updated\" message shown on a report processed with older configuration. Every fix on this page assumes you regenerate the run after changing configuration. See " }, { "type": "link", "title": null, "url": "/llm/markdown/ui-coverage/configuration/overview.md#Setting-configuration", "children": [ { "type": "text", "value": "Setting configuration" } ] }, { "type": "text", "value": "." } ] }, { "type": "heading", "depth": 2, "children": [ { "type": "text", "value": "One element is reported as many" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "A single control appears as several separate untested elements, inflating your element count and lowering your score." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Cause. UI Coverage recognizes the same element across " }, { "type": "link", "title": null, "url": "/llm/markdown/ui-coverage/core-concepts/element-identification.md#Snapshots", "children": [ { "type": "text", "value": "snapshots" } ] }, { "type": "text", "value": " by building an " }, { "type": "link", "title": null, "url": "/llm/markdown/ui-coverage/core-concepts/element-identification.md", "children": [ { "type": "text", "value": "identity" } ] }, { "type": "text", "value": " from its attributes and position in the DOM. When an identifying attribute changes on every render, such as a framework-generated `id`, a hashed class, or a per-request token, each snapshot looks like a new element and the one control is split apart." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "UI Coverage already ignores the most common unstable values, including UUIDs and long hexadecimal hashes on any attribute, digit-only `id`, `name`, `for`, and `aria-*` values, and generated class names like `jss*` and `ng-tns-*`. Add configuration only when your application produces unstable identifiers these built-in filters don't cover." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Fixes." } ] }, { "type": "list", "ordered": false, "start": null, "spread": true, "children": [ { "type": "listItem", "spread": true, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "Ignore the dynamic attribute with " }, { "type": "link", "title": null, "url": "/llm/markdown/ui-coverage/configuration/attributefilters.md", "children": [ { "type": "text", "value": "`attributeFilters`" } ] }, { "type": "text", "value": " so UI Coverage falls back to a stable attribute. When you filter a dynamic `id`, also filter the attributes that reference it, such as `for`, `aria-labelledby`, and `aria-describedby`, or the element can still be identified by those related values." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "App Quality Config" } ] }, { "type": "code", "lang": null, "meta": null, "value": "{\n \"attributeFilters\": [\n {\n \"attribute\": \"id|for|aria-labelledby|aria-describedby\",\n \"value\": \":r.*\",\n \"include\": false,\n \"comment\": \"React useId() values like :r0: are regenerated on every render\"\n }\n ]\n}" } ] }, { "type": "listItem", "spread": true, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "Pin one specific element's identity with an " }, { "type": "link", "title": null, "url": "/llm/markdown/ui-coverage/configuration/elements.md", "children": [ { "type": "text", "value": "`elements`" } ] }, { "type": "text", "value": " rule that identifies it by a selector that stays the same across snapshots. This is the right tool for a single control; if many elements share the same generated attribute, filter the attribute instead." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "App Quality Config" } ] }, { "type": "code", "lang": null, "meta": null, "value": "{\n \"uiCoverage\": {\n \"elements\": [\n {\n \"selector\": \"#checkout-form [id^='card-']\",\n \"name\": \"Card Number Field\"\n }\n ]\n }\n}" } ] } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Patterns in `attributeFilters` match the whole value (they're anchored as `^(...)$`, unless your pattern already starts with `^` or ends with `$`), and JSON requires backslashes to be doubled, so a token like `\\d` must be written `\\\\d`. Note that `attribute` is matched case-insensitively while `value` is matched case-sensitively. See " }, { "type": "link", "title": null, "url": "/llm/markdown/ui-coverage/configuration/attributefilters.md#How-rules-are-applied", "children": [ { "type": "text", "value": "How rules are applied" } ] }, { "type": "text", "value": "." } ] }, { "type": "heading", "depth": 2, "children": [ { "type": "text", "value": "Distinct elements are reported as one" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Two or more controls that should each be tracked appear as a single element, so testing one marks all of them tested and real gaps are hidden." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Cause. The elements resolve to the same identity because their identifying attribute shares a generic value, such as several buttons that all carry `data-test=\"button\"`, or because the attribute that would distinguish them isn't one UI Coverage uses by default." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Fixes." } ] }, { "type": "list", "ordered": false, "start": null, "spread": true, "children": [ { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "Add distinct identifiers in your application, giving each control its own `data-cy` or `data-test` value. This is the most durable fix." } ] } ] }, { "type": "listItem", "spread": true, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "Prefer a distinguishing attribute your markup already has with " }, { "type": "link", "title": null, "url": "/llm/markdown/ui-coverage/configuration/significantattributes.md", "children": [ { "type": "text", "value": "`significantAttributes`" } ] }, { "type": "text", "value": ". Attributes you list are checked before the defaults, so an attribute whose value differs between the elements gives each a distinct identity. Icon-only controls, for example, are often distinguishable by their `aria-label`." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "App Quality Config" } ] }, { "type": "code", "lang": null, "meta": null, "value": "{\n \"significantAttributes\": [\"aria-label\"]\n}" }, { "type": "paragraph", "children": [ { "type": "text", "value": "Listing `aria-label` also turns the report into an inventory of your label text, where a vague label that passes automated accessibility checks (`aria-label=\"button\"`) stands out next to a clear one (`aria-label=\"Close dialog\"`)." } ] } ] } ] }, { "type": "heading", "depth": 2, "children": [ { "type": "text", "value": "Similar elements aren't grouped together" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Repeated components, such as a row action rendered for every record, appear as many separate untested elements instead of one " }, { "type": "link", "title": null, "url": "/llm/markdown/ui-coverage/core-concepts/element-grouping.md", "children": [ { "type": "text", "value": "group" } ] }, { "type": "text", "value": ", so a single table can dominate your untested list." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Cause. Each instance carries a per-instance value in its identifier, such as a database ID in an `id` attribute, so UI Coverage treats the instances as unrelated rather than as one repeated component." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Fixes." } ] }, { "type": "list", "ordered": false, "start": null, "spread": true, "children": [ { "type": "listItem", "spread": true, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "Ignore the per-instance value with " }, { "type": "link", "title": null, "url": "/llm/markdown/ui-coverage/configuration/attributefilters.md", "children": [ { "type": "text", "value": "`attributeFilters`" } ] }, { "type": "text", "value": " so the otherwise-identical elements collapse into one group on their own." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "App Quality Config" } ] }, { "type": "code", "lang": null, "meta": null, "value": "{\n \"attributeFilters\": [\n {\n \"attribute\": \"id\",\n \"value\": \"delete-user-\\\\d+\",\n \"include\": false,\n \"comment\": \"Row action ids include the per-user database id\"\n }\n ]\n}" } ] }, { "type": "listItem", "spread": true, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "Force the grouping with an " }, { "type": "link", "title": null, "url": "/llm/markdown/ui-coverage/configuration/elementgroups.md", "children": [ { "type": "text", "value": "`elementGroups`" } ] }, { "type": "text", "value": " rule that matches all the instances by a shared selector and names them, which also makes the report readable." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "App Quality Config" } ] }, { "type": "code", "lang": null, "meta": null, "value": "{\n \"uiCoverage\": {\n \"elementGroups\": [\n {\n \"selector\": \"[id^='delete-user-']\",\n \"name\": \"Delete User Button\"\n }\n ]\n }\n}" } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "Group in your markup by adding the " }, { "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": "text", "value": " to the elements, or to a wrapper around them, when the team that owns the markup also owns the grouping decision. Groups defined this way take priority over `elementGroups` configuration." } ] } ] } ] }, { "type": "heading", "depth": 2, "children": [ { "type": "text", "value": "Unrelated elements are grouped together" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Controls that do different things are combined into one group, so an interaction with one wrongly marks the others tested." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Cause. The elements share an overly generic selector or attribute value, so UI Coverage's automatic grouping or a shared identifying attribute treats them as instances of the same component." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Fixes." } ] }, { "type": "list", "ordered": false, "start": null, "spread": true, "children": [ { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "Add distinct identifiers so each control resolves to its own identity, which prevents the shared-attribute grouping in the first place." } ] } ] }, { "type": "listItem", "spread": true, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "Define the correct split with " }, { "type": "link", "title": null, "url": "/llm/markdown/ui-coverage/configuration/elementgroups.md", "children": [ { "type": "text", "value": "`elementGroups`" } ] }, { "type": "text", "value": ". A custom group overrides the automatic grouping, so a rule for each action separates controls the heuristics lumped together. List specific rules before broad ones, because the first matching rule wins." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "App Quality Config" } ] }, { "type": "code", "lang": null, "meta": null, "value": "{\n \"uiCoverage\": {\n \"elementGroups\": [\n {\n \"selector\": \"[data-cy='quick-view']\",\n \"name\": \"Quick View Button\"\n },\n {\n \"selector\": \"[data-cy='add-to-cart']\",\n \"name\": \"Add to Cart Button\"\n }\n ]\n }\n}" } ] } ] }, { "type": "heading", "depth": 2, "children": [ { "type": "text", "value": "An element you tested is shown as untested" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Your test interacts with an element on every run, but the report still lists it as untested." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Cause. UI Coverage marks an element tested only when a recognized " }, { "type": "link", "title": null, "url": "/llm/markdown/ui-coverage/core-concepts/interactivity.md#Interaction-Commands", "children": [ { "type": "text", "value": "interaction command" } ] }, { "type": "text", "value": " targets it. The built-in set is `blur`, `check`, `clear`, `click`, `dblclick`, `focus`, `rightclick`, `scrollIntoView`, `scrollTo`, `select`, `selectFile`, `submit`, `trigger`, `type`, and `uncheck`. Anything outside that set, including your own custom commands and plugin commands such as `cypress-real-events`' `realClick` and `realHover`, doesn't count until you declare it." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Cause: you used `scrollIntoView`. That command credits the element's nearest scrollable ancestor rather than the element you called it on, so it usually marks nothing tested. Use `click`, `focus`, or `trigger` on the element instead." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Fixes." } ] }, { "type": "list", "ordered": false, "start": null, "spread": true, "children": [ { "type": "listItem", "spread": true, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "Count a custom or plugin command everywhere by adding it to " }, { "type": "link", "title": null, "url": "/llm/markdown/ui-coverage/configuration/additionalinteractioncommands.md", "children": [ { "type": "text", "value": "`additionalInteractionCommands`" } ] }, { "type": "text", "value": "." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "App Quality Config" } ] }, { "type": "code", "lang": null, "meta": null, "value": "{\n \"uiCoverage\": {\n \"additionalInteractionCommands\": [\"realClick\", \"realHover\"]\n }\n}" } ] }, { "type": "listItem", "spread": true, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "Count a command for specific elements, or credit an interaction the defaults ignore such as an `assert` on a read-only badge or total, with " }, { "type": "link", "title": null, "url": "/llm/markdown/ui-coverage/configuration/allowedinteractioncommands.md", "children": [ { "type": "text", "value": "`allowedInteractionCommands`" } ] }, { "type": "text", "value": "." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "App Quality Config" } ] }, { "type": "code", "lang": null, "meta": null, "value": "{\n \"uiCoverage\": {\n \"allowedInteractionCommands\": [\n {\n \"selector\": \"[data-cy='order-total']\",\n \"commands\": [\"assert\"],\n \"comment\": \"This total is only ever validated, never interacted with\"\n }\n ]\n }\n}" } ] } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Two details often explain a command that still doesn't count. First, a custom command only produces coverage if it logs a " }, { "type": "link", "title": null, "url": "/llm/markdown/ui-coverage/core-concepts/element-identification.md#Snapshots", "children": [ { "type": "text", "value": "snapshot" } ] }, { "type": "text", "value": " that references the element it acts on, so register it with " }, { "type": "link", "title": null, "url": "/llm/markdown/api/cypress-api/custom-commands.md#Arguments", "children": [ { "type": "text", "value": "`prevSubject`" } ] }, { "type": "text", "value": " and log the subject as `$el` (see " }, { "type": "link", "title": null, "url": "/llm/markdown/ui-coverage/configuration/additionalinteractioncommands.md#Requirements-for-a-custom-command", "children": [ { "type": "text", "value": "Requirements for a custom command" } ] }, { "type": "text", "value": "). Second, command names you add are matched case-sensitively, exactly as you registered them." } ] }, { "type": "heading", "depth": 2, "children": [ { "type": "text", "value": "An element stops counting after you add an allowedInteractionCommands rule" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "An element that was tested is now reported as untested, right after you added an " }, { "type": "link", "title": null, "url": "/llm/markdown/ui-coverage/configuration/allowedinteractioncommands.md", "children": [ { "type": "text", "value": "`allowedInteractionCommands`" } ] }, { "type": "text", "value": " rule." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Cause. Once an element matches a rule, only the commands listed in the matching rules count for it, and the default commands no longer apply. If your test exercises the element with a command you didn't list, such as a plain `click`, it's now treated as untested." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Fix. Add the command your test actually uses to the rule's `commands` list, or tighten the `selector` so the rule matches only the elements you intended to restrict." } ] }, { "type": "heading", "depth": 2, "children": [ { "type": "text", "value": "A configuration rule has no effect" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "You saved a rule, but the report looks the same." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Work through these causes in order:" } ] }, { "type": "list", "ordered": false, "start": null, "spread": false, "children": [ { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "The run predates the change. Reports use the configuration saved when they were processed. " }, { "type": "link", "title": null, "url": "/llm/markdown/ui-coverage/configuration/overview.md#Setting-configuration", "children": [ { "type": "text", "value": "Regenerate" } ] }, { "type": "text", "value": " the run to apply your current configuration. This is by far the most common cause." } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "An earlier rule matched first. 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": ", " }, { "type": "link", "title": null, "url": "/llm/markdown/ui-coverage/configuration/elementgroups.md", "children": [ { "type": "text", "value": "`elementGroups`" } ] }, { "type": "text", "value": ", and " }, { "type": "link", "title": null, "url": "/llm/markdown/ui-coverage/configuration/attributefilters.md", "children": [ { "type": "text", "value": "`attributeFilters`" } ] }, { "type": "text", "value": ", the first matching rule wins, so a broad rule above your specific one prevents it from applying. List specific rules first, and place `include: true` exceptions before the `include: false` rule they 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 several rules match one element, the last one wins.)" } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "A nested list replaced a root one. Nesting a shared property such as `elementFilters` or `attributeFilters` under a `uiCoverage` or `accessibility` key completely replaces the root-level list for that product; the two are never merged. Repeat any root rules you still want in the nested list. See " }, { "type": "link", "title": null, "url": "/llm/markdown/ui-coverage/configuration/overview.md#Configuration-scope", "children": [ { "type": "text", "value": "Configuration scope" } ] }, { "type": "text", "value": "." } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "The property is in the wrong place. `elementGroups`, `elements`, `additionalInteractionCommands`, and `allowedInteractionCommands` are UI Coverage–only and must live under the `uiCoverage` key, while `views` is set at the root. A misplaced property is rejected by the schema." } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "The pattern or selector doesn't match. `attributeFilters` patterns are anchored to the whole value, so `value: \"user\"` matches only the exact string `user`; use `value: \"user-.*\"` for a prefix. Selectors in `elementFilters`, `elements`, and `elementGroups` must match the interactive element itself, not a wrapper around it, so `footer` matches only the `