Skip to main content
UI Coverage+ Add-on

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

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.

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)

Contents