Skip to main content
UI CoveragePremium Solution

elementGroups

UI Coverage provides logic to automatically group elements based on their structure in the DOM. However, there are scenarios where you may want to customize these groups to better align with your application's functionality or testing requirements. The elementGroups configuration allows you to define custom logic for grouping elements, improving coverage clarity and simplifying analysis.

Why use element groups?​

  • Improve Grouping Accuracy: Ensure elements with shared attributes but different roles are correctly grouped, avoiding misclassification.
  • Simplify Test Coverage Reports: Grouping similar elements, like navigation buttons or list items, reduces clutter in reports and provides a more concise view of test coverage.
  • Highlight Key Areas: Use meaningful group names to draw attention to critical application areas, such as form controls.
  • Streamline Dynamic Elements: Consolidate dynamic or repeated elements, such as items in a carousel or list, into a single logical group.

Syntax​

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

Options​

For every element considered by UI Coverage, the first elementGroup rule for which the selector property matches the element is used to group the element. Elements that do not match any rules are grouped by the default UI Coverage element grouping rules.

OptionRequiredDefaultDescription
selectorRequiredA CSS selector to identify elements. Supports standard CSS selector syntax, including IDs, classes, attributes, and combinators.
nameOptionalselectorA human-readable name for the group, 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 group configuration.

Examples​

Groups elements by selector​

Config​

{
  "uiCoverage": {
    "elementGroups": [
      {
        "selector": "[data-cy^='item-']"
      }
    ]
  }
}

HTML​

<body>
  <button data-cy="item-1"></button> <!-- Group: [data-cy^='item-'] -->
  <button data-cy="item-2"></button> <!-- Group: [data-cy^='item-'] -->
  <button data-cy="item-3"></button> <!-- Group: [data-cy^='item-'] -->
</body>

Elements shown in UI​

[data-cy^='item-'] (3 instances)

Groups all elements in a container​

Config​

{
  "uiCoverage": {
    "elementGroups": [
      {
        "selector": "#calendar button"
      }
    ]
  }
}

HTML​

<body>
  <div id="calendar">
    <button id="jan"></button>
    <button id="feb"></button>
    <button id="mar"></button>
  </div>
</body>

Elements shown in UI​

#calendar button (3 instances)

Groups form controls with labels​

Config​

{
  "uiCoverage": {
    "elementGroups": [
      {
        "selector": "input[name='animal'], label:has(input[name='animal'])",
        "name": "Animal Option"
      }
    ]
  }
}

HTML​

<body>
  <label>
    <input id="bear" name="animal"></input>
  </label>
  <label>
    <input id="lion" name="animal"></input>
  </label>
</body>

Elements shown in UI​

Animal Option (4 instances)

Groups dynamic elements​

Config​

{
  "uiCoverage": {
    "elementGroups": [
      {
        "selector": "[id^='product']"
      }
    ]
  }
}

HTML​

<body>
  <button id="product125">Product 1</button>
  <button id="product514">Product 2</button>
  <button id="product256">Product 3</button>
</body>

Elements shown in UI​

[id^='product'] (3 instances)

Giving groups custom names​

Sometimes you may want to group elements by a common attribute but give the group a more descriptive name. In the following example, we group buttons with IDs starting with listbox-button- and name the group Add Button.

Config​

{
  "uiCoverage": {
    "elementGroups": [
      {
        "selector": "[id^='listbox-button-']",
        "name": "Add Button"
      }
    ]
  }
}

HTML​

<body>
  <button id='listbox-button-1'>+</button>
  <button id='listbox-button-2'>+</button>
  <button id='listbox-button-3'>+</button>
  <button id='listbox-button-4'>+</button>
</body>

Elements shown in UI​

Add Button (4 instances)

Grouping elements within shadow DOM​

When you need to group elements within a specific shadow DOM host, use the documentScope property to scope your selector to that document context.

Config​

{
  "uiCoverage": {
    "elementGroups": [
      {
        "selector": "button",
        "name": "Shadow DOM Buttons",
        "documentScope": ["custom-component"]
      }
    ]
  }
}

HTML​

<body>
  <button id="root-button">Root Button</button>
  <custom-component>
    #shadow-dom
      <button id="shadow-button-1">Shadow Button 1</button>
      <button id="shadow-button-2">Shadow Button 2</button>
  </custom-component>
</body>

Elements shown in UI​

#root-button
Shadow DOM Buttons (2 instances)

Only the buttons inside the shadow DOM are grouped together, while the root button remains separate.

Grouping elements within iframes​

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

Config​

{
  "uiCoverage": {
    "elementGroups": [
      {
        "selector": "[data-action]",
        "name": "Embedded Actions",
        "documentScope": ["#embedded-widget"]
      }
    ]
  }
}

HTML​

<body>
  <button data-action="save">Save (Root)</button>
  <iframe id="embedded-widget" src="http://www.foo.com">
    <html>
      <body>
        <button data-action="save">Save (Embedded)</button>
        <button data-action="cancel">Cancel (Embedded)</button>
      </body>
    </html>
  </iframe>
</body>

Elements shown in UI​

[data-action="save"] (from root document)
Embedded Actions (2 instances)

Only the buttons inside the iframe are grouped together.

Contents