Skip to main content
UI CoveragePremium Solution

elements

UI Coverage provides automatic logic to identify 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.

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 identify strategy is used.

Why use elements configuration?​

  • Handle Dynamic Attributes: Ensure elements are consistently identified across snapshots, even when attributes change.
  • Ensure Unique Identification: Use custom selectors to uniquely identify elements across snapshots that lack unique attributes or have dynamic values, avoiding misclassification.
  • Simplify Debugging: Assign human-readable names to elements to make reports more interpretable and debugging easier.

Syntax​

{
  "uiCoverage": {
    "elements": [
      {
        "selector": string,
        "name": string,
        "documentScope": [string],
        "comment": string
      }
    ]
  }
}

Options​

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 element identification rules.

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.

OptionRequiredDefaultDescription
selectorRequiredA CSS selector to identify elements. Supports standard CSS selector syntax, including IDs, classes, attributes, and combinators.
nameOptionalselectorA human-readable name for the element, displayed in UI Coverage reports.
documentScopeOptionalAn 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.
commentOptionalA comment describing the purpose of this element configuration.

Examples​

Identify elements by dynamic selector across snapshots​

Config​

{
  "uiCoverage": {
    "elements": [
      {
        "selector": "#my-form [id^='dropdown']"
      }
    ]
  }
}

HTML​

<!-- 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>

Elements shown in UI Coverage​

#my-form [id^="dropdown"]

Identify elements with human-readable names​

Config​

{
  "uiCoverage": {
    "elements": [
      {
        "selector": "#ui-popover-button",
        "name": "Help Popover"
      }
    ]
  }
}

HTML​

<body>
  <button id="ui-popover-button">Help</button>
</body>

Elements shown in UI Coverage​

Help Popover

Scoping element identification to shadow DOM​

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.

Config​

{
  "uiCoverage": {
    "elements": [
      {
        "selector": "#my-button",
        "name": "Custom Component Button",
        "documentScope": ["custom-component"]
      }
    ]
  }
}

HTML​

<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>

Elements shown in UI Coverage​

#my-button (from root document)
Custom Component Button (from shadow DOM)

Only the button inside the shadow DOM is identified using the custom name, while the button in the root document uses the default identification.

Scoping element identification to iframes​

You can also scope element identification to elements within specific iframes using documentScope.

Config​

{
  "uiCoverage": {
    "elements": [
      {
        "selector": "#submit",
        "name": "Embedded Form Submit",
        "documentScope": ["#embedded-form"]
      }
    ]
  }
}

HTML​

<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>

Elements shown in UI Coverage​

#submit (from root document)
Embedded Form Submit (from iframe)

Only the button inside the iframe is identified using the custom name.

Contents