{
  "doc": {
    "id": "ui-coverage/configuration/elements",
    "title": "Elements | Cypress UI Coverage",
    "description": "The `elements` configuration allows you to uniquely identify elements in UI Coverage using custom logic.",
    "section": "ui-coverage",
    "source_path": "/llm/markdown/ui-coverage/configuration/elements.md",
    "version": "48b03b5502f7aea1d0454750cce208f775403542",
    "updated_at": "2026-05-20T19:00:20.270Z",
    "headings": [
      {
        "id": "ui-coverage/configuration/elements#elements",
        "text": "elements",
        "level": 1
      },
      {
        "id": "ui-coverage/configuration/elements#why-use-elements-configuration",
        "text": "Why use elements configuration?",
        "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#examples",
        "text": "Examples",
        "level": 2
      },
      {
        "id": "ui-coverage/configuration/elements#identify-elements-by-dynamic-selector-across-snapshots",
        "text": "Identify elements by dynamic selector across snapshots",
        "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-coverage",
        "text": "Elements shown in UI Coverage",
        "level": 4
      },
      {
        "id": "ui-coverage/configuration/elements#identify-elements-with-human-readable-names",
        "text": "Identify elements with human-readable names",
        "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-coverage",
        "text": "Elements shown in UI Coverage",
        "level": 4
      },
      {
        "id": "ui-coverage/configuration/elements#scoping-element-identification-to-shadow-dom",
        "text": "Scoping element identification to shadow DOM",
        "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-coverage",
        "text": "Elements shown in UI Coverage",
        "level": 4
      },
      {
        "id": "ui-coverage/configuration/elements#scoping-element-identification-to-iframes",
        "text": "Scoping element identification to iframes",
        "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-coverage",
        "text": "Elements shown in UI Coverage",
        "level": 4
      }
    ]
  },
  "content": {
    "type": "root",
    "children": [
      {
        "type": "heading",
        "depth": 1,
        "children": [
          {
            "type": "text",
            "value": "elements"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "UI Coverage provides automatic logic to "
          },
          {
            "type": "link",
            "title": null,
            "url": "/llm/markdown/ui-coverage/core-concepts/element-identification.md",
            "children": [
              {
                "type": "text",
                "value": "identify"
              }
            ]
          },
          {
            "type": "text",
            "value": " elements based on their DOM structure. However, in complex applications, elements may lack stable identifiers or have dynamic attributes that vary across snapshots, leading to incorrect identification. The `elements` configuration allows you to specify selectors to uniquely identify elements, ensuring consistency across snapshots and simplifying your coverage reports."
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "The `elements` configuration is used as the element's identity if only one element per snapshot matches. If there are multiple matches in the same snapshot, this configuration is ignored and the default "
          },
          {
            "type": "link",
            "title": null,
            "url": "/llm/markdown/ui-coverage/core-concepts/element-identification.md",
            "children": [
              {
                "type": "text",
                "value": "identify"
              }
            ]
          },
          {
            "type": "text",
            "value": " strategy is used."
          }
        ]
      },
      {
        "type": "heading",
        "depth": 2,
        "children": [
          {
            "type": "text",
            "value": "Why use elements configuration?"
          }
        ]
      },
      {
        "type": "list",
        "ordered": false,
        "start": null,
        "spread": false,
        "children": [
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "text",
                    "value": "Handle Dynamic Attributes: Ensure elements are consistently identified across snapshots, even when attributes change."
                  }
                ]
              }
            ]
          },
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "text",
                    "value": "Ensure Unique Identification: Use custom selectors to uniquely identify elements across snapshots that lack unique attributes or have dynamic values, avoiding misclassification."
                  }
                ]
              }
            ]
          },
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "text",
                    "value": "Simplify Debugging: Assign human-readable names to elements to make reports more interpretable and debugging easier."
                  }
                ]
              }
            ]
          }
        ]
      },
      {
        "type": "heading",
        "depth": 2,
        "children": [
          {
            "type": "text",
            "value": "Syntax"
          }
        ]
      },
      {
        "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": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "For every element considered by UI Coverage, the first applicable rule, determined by a match with the `selector` property, is used for identification. Elements that do not match any rules are identified by the default UI Coverage "
          },
          {
            "type": "link",
            "title": null,
            "url": "/llm/markdown/ui-coverage/core-concepts/element-identification.md",
            "children": [
              {
                "type": "text",
                "value": "element identification rules"
              }
            ]
          },
          {
            "type": "text",
            "value": "."
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "If multiple elements within the same snapshot satisfy the same rule, the rule cannot uniquely identify these elements. In such cases, the rule is bypassed, and either subsequent rules or the default element identification logic are applied."
          }
        ]
      },
      {
        "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 to identify elements. Supports standard CSS selector syntax, including IDs, classes, attributes, and combinators."
                  }
                ]
              }
            ]
          },
          {
            "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."
                  }
                ]
              }
            ]
          },
          {
            "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 array of CSS selectors that identify document hosts (iframes or shadow DOM hosts) that must be ancestors of the matched element. The selector will only match if all specified document hosts are found in the element's ancestor chain."
                  }
                ]
              }
            ]
          },
          {
            "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 comment describing the purpose of this element configuration."
                  }
                ]
              }
            ]
          }
        ]
      },
      {
        "type": "heading",
        "depth": 2,
        "children": [
          {
            "type": "text",
            "value": "Examples"
          }
        ]
      },
      {
        "type": "heading",
        "depth": 3,
        "children": [
          {
            "type": "text",
            "value": "Identify elements by dynamic selector across snapshots"
          }
        ]
      },
      {
        "type": "heading",
        "depth": 4,
        "children": [
          {
            "type": "text",
            "value": "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": "<!-- Snapshot 1 --><body>  <form id=\"my-form\">    <input id=\"dropdown-142\"></input>  </form></body><!-- Snapshot 2 --><body>  <form id=\"my-form\">    <input id=\"dropdown-980\"></input>  </form></body>"
      },
      {
        "type": "heading",
        "depth": 4,
        "children": [
          {
            "type": "text",
            "value": "Elements shown in UI Coverage"
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "#my-form [id^=\"dropdown\"]"
      },
      {
        "type": "thematicBreak"
      },
      {
        "type": "heading",
        "depth": 3,
        "children": [
          {
            "type": "text",
            "value": "Identify elements with human-readable names"
          }
        ]
      },
      {
        "type": "heading",
        "depth": 4,
        "children": [
          {
            "type": "text",
            "value": "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": "<body>  <button id=\"ui-popover-button\">Help</button></body>"
      },
      {
        "type": "heading",
        "depth": 4,
        "children": [
          {
            "type": "text",
            "value": "Elements shown in UI Coverage"
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "Help Popover"
      },
      {
        "type": "thematicBreak"
      },
      {
        "type": "heading",
        "depth": 3,
        "children": [
          {
            "type": "text",
            "value": "Scoping element identification to shadow DOM"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "When you need to uniquely identify elements within a specific shadow DOM host, use the `documentScope` property to scope your selector to that document context."
          }
        ]
      },
      {
        "type": "heading",
        "depth": 4,
        "children": [
          {
            "type": "text",
            "value": "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": "<body>  <button id=\"my-button\">Button Outside Shadow DOM</button>  <custom-component>    #shadow-dom      <button id=\"my-button\">Button Inside Shadow DOM</button>  </custom-component></body>"
      },
      {
        "type": "heading",
        "depth": 4,
        "children": [
          {
            "type": "text",
            "value": "Elements shown in UI Coverage"
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "#my-button (from root document)Custom Component Button (from shadow DOM)"
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "Only the button inside the shadow DOM is identified using the custom name, while the button in the root document uses the default identification."
          }
        ]
      },
      {
        "type": "thematicBreak"
      },
      {
        "type": "heading",
        "depth": 3,
        "children": [
          {
            "type": "text",
            "value": "Scoping element identification to iframes"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "You can also scope element identification to elements within specific iframes using `documentScope`."
          }
        ]
      },
      {
        "type": "heading",
        "depth": 4,
        "children": [
          {
            "type": "text",
            "value": "Config"
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "{  \"uiCoverage\": {    \"elements\": [      {        \"selector\": \"#submit\",        \"name\": \"Embedded Form Submit\",        \"documentScope\": [\"#embedded-form\"]      }    ]  }}"
      },
      {
        "type": "heading",
        "depth": 4,
        "children": [
          {
            "type": "text",
            "value": "HTML"
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "<body>  <button id=\"submit\">Submit (Root)</button>  <iframe id=\"embedded-form\" src=\"http://www.foo.com\">    <html>      <body>        <button id=\"submit\">Submit (Embedded)</button>      </body>    </html>  </iframe></body>"
      },
      {
        "type": "heading",
        "depth": 4,
        "children": [
          {
            "type": "text",
            "value": "Elements shown in UI Coverage"
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "#submit (from root document)Embedded Form Submit (from iframe)"
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "Only the button inside the iframe is identified using the custom name."
          }
        ]
      }
    ]
  },
  "token_estimate": 908
}