{
"doc": {
"id": "ui-coverage/configuration/elements",
"title": "elements: rename and stabilize element identity in UI Coverage",
"description": "Rename elements and give them a stable identity in Cypress UI Coverage reports, so dynamic attributes do not create duplicate untested elements.",
"section": "ui-coverage",
"source_path": "/llm/markdown/ui-coverage/configuration/elements.md",
"version": "e6c8d867c21227247f14714fb5690c7c018983c5",
"updated_at": "2026-08-08T12:39:37.868Z",
"headings": [
{
"id": "ui-coverage/configuration/elements#stabilize-element-identity-elements",
"text": "Stabilize element identity - elements",
"level": 1
},
{
"id": "ui-coverage/configuration/elements#why-use-elements",
"text": "Why use elements?",
"level": 2
},
{
"id": "ui-coverage/configuration/elements#setting-elements",
"text": "Setting elements",
"level": 2
},
{
"id": "ui-coverage/configuration/elements#syntax",
"text": "Syntax",
"level": 2
},
{
"id": "ui-coverage/configuration/elements#options",
"text": "Options",
"level": 3
},
{
"id": "ui-coverage/configuration/elements#how-are-elements-rules-applied",
"text": "How are elements rules applied?",
"level": 3
},
{
"id": "ui-coverage/configuration/elements#validation-rules",
"text": "Validation rules",
"level": 3
},
{
"id": "ui-coverage/configuration/elements#examples",
"text": "Examples",
"level": 2
},
{
"id": "ui-coverage/configuration/elements#stabilize-an-element-with-a-dynamic-id",
"text": "Stabilize an element with a dynamic ID",
"level": 3
},
{
"id": "ui-coverage/configuration/elements#config",
"text": "Config",
"level": 4
},
{
"id": "ui-coverage/configuration/elements#html",
"text": "HTML",
"level": 4
},
{
"id": "ui-coverage/configuration/elements#elements-shown-in-ui",
"text": "Elements shown in UI",
"level": 4
},
{
"id": "ui-coverage/configuration/elements#give-an-element-a-readable-name",
"text": "Give an element a readable name",
"level": 3
},
{
"id": "ui-coverage/configuration/elements#config",
"text": "Config",
"level": 4
},
{
"id": "ui-coverage/configuration/elements#html",
"text": "HTML",
"level": 4
},
{
"id": "ui-coverage/configuration/elements#elements-shown-in-ui",
"text": "Elements shown in UI",
"level": 4
},
{
"id": "ui-coverage/configuration/elements#identify-an-element-inside-a-shadow-dom-or-iframe",
"text": "Identify an element inside a shadow DOM or iframe",
"level": 3
},
{
"id": "ui-coverage/configuration/elements#config",
"text": "Config",
"level": 4
},
{
"id": "ui-coverage/configuration/elements#html",
"text": "HTML",
"level": 4
},
{
"id": "ui-coverage/configuration/elements#elements-shown-in-ui",
"text": "Elements shown in UI",
"level": 4
},
{
"id": "ui-coverage/configuration/elements#see-also",
"text": "See also",
"level": 2
}
]
},
"content": {
"type": "root",
"children": [
{
"type": "heading",
"depth": 1,
"children": [
{
"type": "text",
"value": "Stabilize element identity - `elements`"
}
]
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "The `elements` configuration assigns a stable identity and a display name to a single element in your UI Coverage report."
}
]
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "As your tests run, UI Coverage captures "
},
{
"type": "link",
"title": null,
"url": "/llm/markdown/ui-coverage/core-concepts/element-identification.md#Snapshots",
"children": [
{
"type": "text",
"value": "snapshots"
}
]
},
{
"type": "text",
"value": " of your application's DOM, and the same element usually appears in many of them: on every page load, in every test that visits its page. To count that element once, UI Coverage must recognize it as the same element in every snapshot. When one of its attributes is different on each appearance, such as an `id` generated on every page load, that recognition fails, and each appearance is reported as a new element. One dropdown then shows up as several untested elements and drags down your score."
}
]
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "An `elements` rule fixes this by identifying the element with a selector you choose that matches in every snapshot. The element counts once, and you can rename it to something readable like \"Help Popover\" instead of a machine-generated selector."
}
]
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "Without stable identities and names, a report can list controls under machine-generated selectors that are hard to recognize and act on:"
}
]
},
{
"type": "heading",
"depth": 2,
"children": [
{
"type": "text",
"value": "Why use elements?"
}
]
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "UI Coverage already "
},
{
"type": "link",
"title": null,
"url": "/llm/markdown/ui-coverage/core-concepts/element-identification.md",
"children": [
{
"type": "text",
"value": "identifies elements automatically"
}
]
},
{
"type": "text",
"value": " using significant attributes, location, and other DOM signals. Use `elements` when the automatic identity for a specific element isn't stable or isn't readable:"
}
]
},
{
"type": "list",
"ordered": false,
"start": null,
"spread": false,
"children": [
{
"type": "listItem",
"spread": false,
"checked": null,
"children": [
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "Stabilize an element's identity: Identify an element by a selector that stays the same across snapshots, even when its `id` or other attributes are regenerated on every render, so it isn't duplicated in reports."
}
]
}
]
},
{
"type": "listItem",
"spread": false,
"checked": null,
"children": [
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "Rename elements in reports: Display a human-readable name in place of a machine-generated selector, so anyone reading the report understands what needs testing."
}
]
}
]
}
]
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "If your goal is different, such as combining repeated elements so they count as one, or removing elements from reports entirely, see "
},
{
"type": "link",
"title": null,
"url": "/llm/markdown/ui-coverage/configuration/overview.md#Which-option-do-I-need",
"children": [
{
"type": "text",
"value": "Which option do I need?"
}
]
},
{
"type": "text",
"value": " in the configuration overview."
}
]
},
{
"type": "heading",
"depth": 2,
"children": [
{
"type": "text",
"value": "Setting elements"
}
]
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "To add or edit `elements`, open the App Quality tab in your project settings in Cypress Cloud. See "
},
{
"type": "link",
"title": null,
"url": "/llm/markdown/ui-coverage/configuration/overview.md#Setting-configuration",
"children": [
{
"type": "text",
"value": "Setting configuration"
}
]
},
{
"type": "text",
"value": " for details, including how to regenerate past reports with a new configuration without rerunning your tests."
}
]
},
{
"type": "heading",
"depth": 2,
"children": [
{
"type": "text",
"value": "Syntax"
}
]
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "App Quality Config"
}
]
},
{
"type": "code",
"lang": null,
"meta": null,
"value": "{ \"uiCoverage\": { \"elements\": [ { \"selector\": string, \"name\": string, \"documentScope\": [string], \"comment\": string } ] }}"
},
{
"type": "heading",
"depth": 3,
"children": [
{
"type": "text",
"value": "Options"
}
]
},
{
"type": "table",
"align": [
null,
null,
null,
null
],
"children": [
{
"type": "tableRow",
"children": [
{
"type": "tableCell",
"children": [
{
"type": "text",
"value": "Option"
}
]
},
{
"type": "tableCell",
"children": [
{
"type": "text",
"value": "Required"
}
]
},
{
"type": "tableCell",
"children": [
{
"type": "text",
"value": "Default"
}
]
},
{
"type": "tableCell",
"children": [
{
"type": "text",
"value": "Description"
}
]
}
]
},
{
"type": "tableRow",
"children": [
{
"type": "tableCell",
"children": [
{
"type": "text",
"value": "`selector`"
}
]
},
{
"type": "tableCell",
"children": [
{
"type": "text",
"value": "Required"
}
]
},
{
"type": "tableCell",
"children": []
},
{
"type": "tableCell",
"children": [
{
"type": "text",
"value": "A CSS selector that identifies the element. Supports standard CSS selector syntax, including IDs, classes, attributes, combinators, and functional pseudo-classes like `:has()`. The rule applies only when exactly one interactive element matches."
}
]
}
]
},
{
"type": "tableRow",
"children": [
{
"type": "tableCell",
"children": [
{
"type": "text",
"value": "`name`"
}
]
},
{
"type": "tableCell",
"children": [
{
"type": "text",
"value": "Optional"
}
]
},
{
"type": "tableCell",
"children": [
{
"type": "text",
"value": "`selector`"
}
]
},
{
"type": "tableCell",
"children": [
{
"type": "text",
"value": "A human-readable name for the element, displayed in UI Coverage reports in place of the selector. Each rule's name must be unique."
}
]
}
]
},
{
"type": "tableRow",
"children": [
{
"type": "tableCell",
"children": [
{
"type": "text",
"value": "`documentScope`"
}
]
},
{
"type": "tableCell",
"children": [
{
"type": "text",
"value": "Optional"
}
]
},
{
"type": "tableCell",
"children": []
},
{
"type": "tableCell",
"children": [
{
"type": "text",
"value": "An ordered array of CSS selectors that match document hosts (iframes or shadow DOM hosts) in the element's ancestor chain, from outermost to innermost. Use this to identify an element inside a specific iframe or shadow DOM. Hosts that aren't listed may appear between the ones that are."
}
]
}
]
},
{
"type": "tableRow",
"children": [
{
"type": "tableCell",
"children": [
{
"type": "text",
"value": "`comment`"
}
]
},
{
"type": "tableCell",
"children": [
{
"type": "text",
"value": "Optional"
}
]
},
{
"type": "tableCell",
"children": []
},
{
"type": "tableCell",
"children": [
{
"type": "text",
"value": "A note about why this rule exists, for your team's benefit. Comments have no effect on how elements are identified."
}
]
}
]
}
]
},
{
"type": "heading",
"depth": 3,
"children": [
{
"type": "text",
"value": "How are elements rules applied?"
}
]
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "In each snapshot captured by your tests, every rule is evaluated independently:"
}
]
},
{
"type": "list",
"ordered": false,
"start": null,
"spread": false,
"children": [
{
"type": "listItem",
"spread": false,
"checked": null,
"children": [
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "A rule applies only when it matches exactly one element. A rule identifies a single element, so UI Coverage counts how many of the "
},
{
"type": "link",
"title": null,
"url": "/llm/markdown/ui-coverage/core-concepts/interactivity.md",
"children": [
{
"type": "text",
"value": "interactive elements"
}
]
},
{
"type": "text",
"value": " it tracks match the rule's `selector` in the snapshot. If exactly one matches, the rule applies to that element. If two or more match, the rule is skipped and the elements keep their default identity, because applying it would merge separate elements into one. To intentionally treat several elements as one unit, use "
},
{
"type": "link",
"title": null,
"url": "/llm/markdown/ui-coverage/configuration/elementgroups.md",
"children": [
{
"type": "text",
"value": "`elementGroups`"
}
]
},
{
"type": "text",
"value": " instead. Matches against parts of the page that UI Coverage doesn't track, such as wrapper containers or static text, don't count."
}
]
}
]
},
{
"type": "listItem",
"spread": false,
"checked": null,
"children": [
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "Matching is evaluated per snapshot. A rule can apply in one snapshot and be skipped in another where its selector matches several elements at once."
}
]
}
]
},
{
"type": "listItem",
"spread": false,
"checked": null,
"children": [
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "A matched element is identified by the rule's `selector` alone. Its identity no longer depends on its attributes, structure, or the default "
},
{
"type": "link",
"title": null,
"url": "/llm/markdown/ui-coverage/core-concepts/element-identification.md",
"children": [
{
"type": "text",
"value": "element identification rules"
}
]
},
{
"type": "text",
"value": ", so it stays one element across snapshots even as dynamic attributes change. The report displays the rule's `name`, or its `selector` when no name is given. This includes links, which are otherwise displayed by their URL."
}
]
}
]
},
{
"type": "listItem",
"spread": false,
"checked": null,
"children": [
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "Rules match in any document unless scoped. A rule without `documentScope` can match elements in the main document, in iframes, and in shadow DOMs. Add `documentScope` to restrict a rule to one of those documents, for example when the same selector appears both inside and outside an iframe."
}
]
}
]
},
{
"type": "listItem",
"spread": false,
"checked": null,
"children": [
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "Later rules take precedence. When more than one rule matches the same element, the last matching rule in the list determines its identity and name."
}
]
}
]
},
{
"type": "listItem",
"spread": false,
"checked": null,
"children": [
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "Filtered elements are never matched. Elements excluded from reports by "
},
{
"type": "link",
"title": null,
"url": "/llm/markdown/ui-coverage/configuration/elementfilters.md",
"children": [
{
"type": "text",
"value": "`elementFilters`"
}
]
},
{
"type": "text",
"value": " are not considered, and don't count toward a rule's one-match limit."
}
]
}
]
}
]
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "If a rule doesn't seem to take effect, see "
},
{
"type": "link",
"title": null,
"url": "/llm/markdown/ui-coverage/faq.md#Why-isnt-my-UI-Coverage-elements-rule-applying",
"children": [
{
"type": "text",
"value": "Why isn't my elements rule applying?"
}
]
},
{
"type": "text",
"value": " in the UI Coverage FAQ."
}
]
},
{
"type": "heading",
"depth": 3,
"children": [
{
"type": "text",
"value": "Validation rules"
}
]
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "Cypress Cloud rejects a configuration when:"
}
]
},
{
"type": "list",
"ordered": false,
"start": null,
"spread": false,
"children": [
{
"type": "listItem",
"spread": false,
"checked": null,
"children": [
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "Two rules have the same `selector` (with the same `documentScope`)."
}
]
}
]
},
{
"type": "listItem",
"spread": false,
"checked": null,
"children": [
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "Two rules have the same `name`, or one rule's `name` matches another rule's `selector`. Elements are identified by these values, so they must be unique."
}
]
}
]
},
{
"type": "listItem",
"spread": false,
"checked": null,
"children": [
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "A `selector` or `documentScope` entry isn't valid CSS selector syntax."
}
]
}
]
},
{
"type": "listItem",
"spread": false,
"checked": null,
"children": [
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "A rule contains a property other than the four listed above."
}
]
}
]
}
]
},
{
"type": "heading",
"depth": 2,
"children": [
{
"type": "text",
"value": "Examples"
}
]
},
{
"type": "heading",
"depth": 3,
"children": [
{
"type": "text",
"value": "Stabilize an element with a dynamic ID"
}
]
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "This form's dropdown gets a newly generated `id` on every page load, so each snapshot produces what looks like a new element. A rule with an attribute prefix selector identifies it as one element across snapshots."
}
]
},
{
"type": "heading",
"depth": 4,
"children": [
{
"type": "text",
"value": "Config"
}
]
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "App Quality Config"
}
]
},
{
"type": "code",
"lang": null,
"meta": null,
"value": "{ \"uiCoverage\": { \"elements\": [ { \"selector\": \"#my-form [id^='dropdown']\" } ] }}"
},
{
"type": "heading",
"depth": 4,
"children": [
{
"type": "text",
"value": "HTML"
}
]
},
{
"type": "code",
"lang": null,
"meta": null,
"value": " "
},
{
"type": "heading",
"depth": 4,
"children": [
{
"type": "text",
"value": "Elements shown in UI"
}
]
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "Without the rule, the dropdown can appear as two untested elements:"
}
]
},
{
"type": "code",
"lang": null,
"meta": null,
"value": "#dropdown-142#dropdown-980"
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "With the rule, it appears once, displayed under the rule's selector because no `name` is given:"
}
]
},
{
"type": "code",
"lang": null,
"meta": null,
"value": "#my-form [id^='dropdown']"
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "An `elements` rule is the right tool when one specific element needs a stable identity. If many elements share the same generated attribute, fix the attribute instead: an "
},
{
"type": "link",
"title": null,
"url": "/llm/markdown/ui-coverage/configuration/attributefilters.md",
"children": [
{
"type": "text",
"value": "`attributeFilters`"
}
]
},
{
"type": "text",
"value": " rule stops it from identifying any element."
}
]
},
{
"type": "thematicBreak"
},
{
"type": "heading",
"depth": 3,
"children": [
{
"type": "text",
"value": "Give an element a readable name"
}
]
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "Add a `name` so the report describes the interface instead of your selectors."
}
]
},
{
"type": "heading",
"depth": 4,
"children": [
{
"type": "text",
"value": "Config"
}
]
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "App Quality Config"
}
]
},
{
"type": "code",
"lang": null,
"meta": null,
"value": "{ \"uiCoverage\": { \"elements\": [ { \"selector\": \"#ui-popover-button\", \"name\": \"Help Popover\" } ] }}"
},
{
"type": "heading",
"depth": 4,
"children": [
{
"type": "text",
"value": "HTML"
}
]
},
{
"type": "code",
"lang": null,
"meta": null,
"value": " "
},
{
"type": "heading",
"depth": 4,
"children": [
{
"type": "text",
"value": "Elements shown in UI"
}
]
},
{
"type": "code",
"lang": null,
"meta": null,
"value": "Help Popover"
},
{
"type": "thematicBreak"
},
{
"type": "heading",
"depth": 3,
"children": [
{
"type": "text",
"value": "Identify an element inside a shadow DOM or iframe"
}
]
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "Use `documentScope` to identify an element inside a specific shadow DOM host or iframe. Here, the button inside the `` shadow root shares its `id` with a button in the main document. The scope restricts the rule to the shadow DOM, so the rule matches exactly one element and applies. Without `documentScope`, the rule would match both buttons and be skipped."
}
]
},
{
"type": "heading",
"depth": 4,
"children": [
{
"type": "text",
"value": "Config"
}
]
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "App Quality Config"
}
]
},
{
"type": "code",
"lang": null,
"meta": null,
"value": "{ \"uiCoverage\": { \"elements\": [ { \"selector\": \"#my-button\", \"name\": \"Custom Component Button\", \"documentScope\": [\"custom-component\"] } ] }}"
},
{
"type": "heading",
"depth": 4,
"children": [
{
"type": "text",
"value": "HTML"
}
]
},
{
"type": "code",
"lang": null,
"meta": null,
"value": " #shadow-dom "
},
{
"type": "heading",
"depth": 4,
"children": [
{
"type": "text",
"value": "Elements shown in UI"
}
]
},
{
"type": "code",
"lang": null,
"meta": null,
"value": "#my-buttonCustom Component Button"
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "The button inside the shadow DOM appears under its configured name, while the button in the main document keeps its default identity."
}
]
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "`documentScope` works the same way for embedded content that renders inside an iframe. The scope selector matches the `iframe` element itself in its parent document:"
}
]
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "App Quality Config"
}
]
},
{
"type": "code",
"lang": null,
"meta": null,
"value": "{ \"uiCoverage\": { \"elements\": [ { \"selector\": \"#submit\", \"name\": \"Embedded Form Submit\", \"documentScope\": [\"#embedded-form\"] } ] }}"
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "For nested documents, list one selector per host from outermost to innermost, for example `\"documentScope\": [\"#embedded-form\", \"secure-card-input\"]`."
}
]
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "After saving configuration changes, regenerate a recent run to preview the effect of your rules without rerunning your tests. See "
},
{
"type": "link",
"title": null,
"url": "/llm/markdown/ui-coverage/configuration/overview.md#Setting-configuration",
"children": [
{
"type": "text",
"value": "Setting configuration"
}
]
},
{
"type": "text",
"value": " for how to regenerate a report."
}
]
},
{
"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/core-concepts/element-identification.md",
"children": [
{
"type": "text",
"value": "Element Identification"
}
]
},
{
"type": "text",
"value": ": how elements are identified automatically."
}
]
}
]
},
{
"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": "`elementGroups`"
}
]
},
{
"type": "text",
"value": ": combine related elements into one group."
}
]
}
]
},
{
"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": "`attributeFilters`"
}
]
},
{
"type": "text",
"value": ": stop dynamic attributes from identifying elements."
}
]
}
]
},
{
"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": "`elementFilters`"
}
]
},
{
"type": "text",
"value": ": remove elements from reports entirely."
}
]
}
]
},
{
"type": "listItem",
"spread": false,
"checked": null,
"children": [
{
"type": "paragraph",
"children": [
{
"type": "link",
"title": null,
"url": "/llm/markdown/ui-coverage/configuration/overview.md",
"children": [
{
"type": "text",
"value": "Configuration overview"
}
]
},
{
"type": "text",
"value": ": where to set configuration and regenerate reports."
}
]
}
]
},
{
"type": "listItem",
"spread": false,
"checked": null,
"children": [
{
"type": "paragraph",
"children": [
{
"type": "link",
"title": null,
"url": "/llm/markdown/ui-coverage/faq.md",
"children": [
{
"type": "text",
"value": "UI Coverage FAQ"
}
]
},
{
"type": "text",
"value": ": common questions and troubleshooting."
}
]
}
]
}
]
}
]
},
"token_estimate": 1931
}