{
  "doc": {
    "id": "ui-coverage/configuration/elementgroups",
    "title": "Element Groups | Cypress UI Coverage",
    "description": "The `elementGroups` configuration allows you to group elements in UI Coverage using custom logic.",
    "section": "ui-coverage",
    "source_path": "/llm/markdown/ui-coverage/configuration/elementgroups.md",
    "version": "3cf5b86b3403f604bdf7f3e35025c3bc3865e02c",
    "updated_at": "2026-05-07T17:44:31.931Z",
    "headings": [
      {
        "id": "ui-coverage/configuration/elementgroups#elementgroups",
        "text": "elementGroups",
        "level": 1
      },
      {
        "id": "ui-coverage/configuration/elementgroups#why-use-element-groups",
        "text": "Why use element groups?",
        "level": 2
      },
      {
        "id": "ui-coverage/configuration/elementgroups#syntax",
        "text": "Syntax",
        "level": 2
      },
      {
        "id": "ui-coverage/configuration/elementgroups#options",
        "text": "Options",
        "level": 3
      },
      {
        "id": "ui-coverage/configuration/elementgroups#examples",
        "text": "Examples",
        "level": 2
      },
      {
        "id": "ui-coverage/configuration/elementgroups#groups-elements-by-selector",
        "text": "Groups elements by selector",
        "level": 3
      },
      {
        "id": "ui-coverage/configuration/elementgroups#config",
        "text": "Config",
        "level": 4
      },
      {
        "id": "ui-coverage/configuration/elementgroups#html",
        "text": "HTML",
        "level": 4
      },
      {
        "id": "ui-coverage/configuration/elementgroups#elements-shown-in-ui",
        "text": "Elements shown in UI",
        "level": 4
      },
      {
        "id": "ui-coverage/configuration/elementgroups#groups-all-elements-in-a-container",
        "text": "Groups all elements in a container",
        "level": 3
      },
      {
        "id": "ui-coverage/configuration/elementgroups#config",
        "text": "Config",
        "level": 4
      },
      {
        "id": "ui-coverage/configuration/elementgroups#html",
        "text": "HTML",
        "level": 4
      },
      {
        "id": "ui-coverage/configuration/elementgroups#elements-shown-in-ui",
        "text": "Elements shown in UI",
        "level": 4
      },
      {
        "id": "ui-coverage/configuration/elementgroups#groups-form-controls-with-labels",
        "text": "Groups form controls with labels",
        "level": 3
      },
      {
        "id": "ui-coverage/configuration/elementgroups#config",
        "text": "Config",
        "level": 4
      },
      {
        "id": "ui-coverage/configuration/elementgroups#html",
        "text": "HTML",
        "level": 4
      },
      {
        "id": "ui-coverage/configuration/elementgroups#elements-shown-in-ui",
        "text": "Elements shown in UI",
        "level": 4
      },
      {
        "id": "ui-coverage/configuration/elementgroups#groups-dynamic-elements",
        "text": "Groups dynamic elements",
        "level": 3
      },
      {
        "id": "ui-coverage/configuration/elementgroups#config",
        "text": "Config",
        "level": 4
      },
      {
        "id": "ui-coverage/configuration/elementgroups#html",
        "text": "HTML",
        "level": 4
      },
      {
        "id": "ui-coverage/configuration/elementgroups#elements-shown-in-ui",
        "text": "Elements shown in UI",
        "level": 4
      },
      {
        "id": "ui-coverage/configuration/elementgroups#giving-groups-custom-names",
        "text": "Giving groups custom names",
        "level": 3
      },
      {
        "id": "ui-coverage/configuration/elementgroups#config",
        "text": "Config",
        "level": 4
      },
      {
        "id": "ui-coverage/configuration/elementgroups#html",
        "text": "HTML",
        "level": 4
      },
      {
        "id": "ui-coverage/configuration/elementgroups#elements-shown-in-ui",
        "text": "Elements shown in UI",
        "level": 4
      },
      {
        "id": "ui-coverage/configuration/elementgroups#grouping-elements-within-shadow-dom",
        "text": "Grouping elements within shadow DOM",
        "level": 3
      },
      {
        "id": "ui-coverage/configuration/elementgroups#config",
        "text": "Config",
        "level": 4
      },
      {
        "id": "ui-coverage/configuration/elementgroups#html",
        "text": "HTML",
        "level": 4
      },
      {
        "id": "ui-coverage/configuration/elementgroups#elements-shown-in-ui",
        "text": "Elements shown in UI",
        "level": 4
      },
      {
        "id": "ui-coverage/configuration/elementgroups#grouping-elements-within-iframes",
        "text": "Grouping elements within iframes",
        "level": 3
      },
      {
        "id": "ui-coverage/configuration/elementgroups#config",
        "text": "Config",
        "level": 4
      },
      {
        "id": "ui-coverage/configuration/elementgroups#html",
        "text": "HTML",
        "level": 4
      },
      {
        "id": "ui-coverage/configuration/elementgroups#elements-shown-in-ui",
        "text": "Elements shown in UI",
        "level": 4
      }
    ]
  },
  "chunks": [
    {
      "id": "ui-coverage/configuration/elementgroups#why-use-element-groups",
      "doc_id": "ui-coverage/configuration/elementgroups",
      "heading": "Why use element groups?",
      "heading_level": 2,
      "content_markdown": "## Why use element groups?\n\n*   **Improve Grouping Accuracy**: Ensure elements with shared attributes but different roles are correctly grouped, avoiding misclassification.\n*   **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.\n*   **Highlight Key Areas**: Use meaningful group names to draw attention to critical application areas, such as form controls.\n*   **Streamline Dynamic Elements**: Consolidate dynamic or repeated elements, such as items in a carousel or list, into a single logical group.\n",
      "section": "ui-coverage",
      "anchors": [
        "why-use-element-groups"
      ],
      "path": "/llm/json/chunked/ui-coverage/configuration/elementgroups.json",
      "token_estimate": 120
    },
    {
      "id": "ui-coverage/configuration/elementgroups#syntax",
      "doc_id": "ui-coverage/configuration/elementgroups",
      "heading": "Syntax",
      "heading_level": 2,
      "content_markdown": "## Syntax\n\n```\n{  \"uiCoverage\": {    \"elementGroups\": [      {        \"selector\": string,        \"name\": string,        \"documentScope\": [string],        \"comment\": string      }    ]  }}\n```\n\n### Options\n\nFor 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](/llm/markdown/ui-coverage/core-concepts/element-grouping.md).\n\n| Option | Required | Default | Description |\n| --- | --- | --- | --- |\n| `selector` | Required |  | A CSS selector to identify elements. Supports standard CSS selector syntax, including IDs, classes, attributes, and combinators. |\n| `name` | Optional | `selector` | A human-readable name for the group, displayed in UI Coverage reports. |\n| `documentScope` | Optional |  | 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. |\n| `comment` | Optional |  | A comment describing the purpose of this element group configuration. |\n",
      "section": "ui-coverage",
      "anchors": [
        "syntax"
      ],
      "path": "/llm/json/chunked/ui-coverage/configuration/elementgroups.json",
      "token_estimate": 252
    },
    {
      "id": "ui-coverage/configuration/elementgroups#options",
      "doc_id": "ui-coverage/configuration/elementgroups",
      "heading": "Options",
      "heading_level": 3,
      "content_markdown": "### Options\n\nFor 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](/llm/markdown/ui-coverage/core-concepts/element-grouping.md).\n\n| Option | Required | Default | Description |\n| --- | --- | --- | --- |\n| `selector` | Required |  | A CSS selector to identify elements. Supports standard CSS selector syntax, including IDs, classes, attributes, and combinators. |\n| `name` | Optional | `selector` | A human-readable name for the group, displayed in UI Coverage reports. |\n| `documentScope` | Optional |  | 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. |\n| `comment` | Optional |  | A comment describing the purpose of this element group configuration. |\n",
      "section": "ui-coverage",
      "anchors": [
        "options"
      ],
      "path": "/llm/json/chunked/ui-coverage/configuration/elementgroups.json",
      "token_estimate": 224
    },
    {
      "id": "ui-coverage/configuration/elementgroups#examples",
      "doc_id": "ui-coverage/configuration/elementgroups",
      "heading": "Examples",
      "heading_level": 2,
      "content_markdown": "## Examples\n\n### Groups elements by selector\n\n#### Config\n\n```\n{  \"uiCoverage\": {    \"elementGroups\": [      {        \"selector\": \"[data-cy^='item-']\"      }    ]  }}\n```\n\n#### HTML\n\n```\n<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>\n```\n\n#### Elements shown in UI\n\n```\n[data-cy^='item-'] (3 instances)\n```\n\n* * *\n\n### Groups all elements in a container\n\n#### Config\n\n```\n{  \"uiCoverage\": {    \"elementGroups\": [      {        \"selector\": \"#calendar button\"      }    ]  }}\n```\n\n#### HTML\n\n```\n<body>  <div id=\"calendar\">    <button id=\"jan\"></button>    <button id=\"feb\"></button>    <button id=\"mar\"></button>  </div></body>\n```\n\n#### Elements shown in UI\n\n```\n#calendar button (3 instances)\n```\n\n* * *\n\n### Groups form controls with labels\n\n#### Config\n\n```\n{  \"uiCoverage\": {    \"elementGroups\": [      {        \"selector\": \"input[name='animal'], label:has(input[name='animal'])\",        \"name\": \"Animal Option\"      }    ]  }}\n```\n\n#### HTML\n\n```\n<body>  <label>    <input id=\"bear\" name=\"animal\"></input>  </label>  <label>    <input id=\"lion\" name=\"animal\"></input>  </label></body>\n```\n\n#### Elements shown in UI\n\n```\nAnimal Option (4 instances)\n```\n\n### Groups dynamic elements\n\n#### Config\n\n```\n{  \"uiCoverage\": {    \"elementGroups\": [      {        \"selector\": \"[id^='product']\"      }    ]  }}\n```\n\n#### HTML\n\n```\n<body>  <button id=\"product125\">Product 1</button>  <button id=\"product514\">Product 2</button>  <button id=\"product256\">Product 3</button></body>\n```\n\n#### Elements shown in UI\n\n```\n[id^='product'] (3 instances)\n```\n\n### Giving groups custom names\n\nSometimes 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`.\n\n#### Config\n\n```\n{  \"uiCoverage\": {    \"elementGroups\": [      {        \"selector\": \"[id^='listbox-button-']\",        \"name\": \"Add Button\"      }    ]  }}\n```\n\n#### HTML\n\n```\n<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>\n```\n\n#### Elements shown in UI\n\n```\nAdd Button (4 instances)\n```\n\n* * *\n\n### Grouping elements within shadow DOM\n\nWhen you need to group elements within a specific shadow DOM host, use the `documentScope` property to scope your selector to that document context.\n\n#### Config\n\n```\n{  \"uiCoverage\": {    \"elementGroups\": [      {        \"selector\": \"button\",        \"name\": \"Shadow DOM Buttons\",        \"documentScope\": [\"custom-component\"]      }    ]  }}\n```\n\n#### HTML\n\n```\n<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>\n```\n\n#### Elements shown in UI\n\n```\n#root-buttonShadow DOM Buttons (2 instances)\n```\n\nOnly the buttons inside the shadow DOM are grouped together, while the root button remains separate.\n\n* * *\n\n### Grouping elements within iframes\n\nYou can also scope element grouping to elements within specific iframes using `documentScope`.\n\n#### Config\n\n```\n{  \"uiCoverage\": {    \"elementGroups\": [      {        \"selector\": \"[data-action]\",        \"name\": \"Embedded Actions\",        \"documentScope\": [\"#embedded-widget\"]      }    ]  }}\n```\n\n#### HTML\n\n```\n<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>\n```\n\n#### Elements shown in UI\n\n```\n[data-action=\"save\"] (from root document)Embedded Actions (2 instances)\n```\n\nOnly the buttons inside the iframe are grouped together.\n",
      "section": "ui-coverage",
      "anchors": [
        "examples"
      ],
      "path": "/llm/json/chunked/ui-coverage/configuration/elementgroups.json",
      "token_estimate": 632
    },
    {
      "id": "ui-coverage/configuration/elementgroups#groups-elements-by-selector",
      "doc_id": "ui-coverage/configuration/elementgroups",
      "heading": "Groups elements by selector",
      "heading_level": 3,
      "content_markdown": "### Groups elements by selector\n\n#### Config\n\n```\n{  \"uiCoverage\": {    \"elementGroups\": [      {        \"selector\": \"[data-cy^='item-']\"      }    ]  }}\n```\n\n#### HTML\n\n```\n<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>\n```\n\n#### Elements shown in UI\n\n```\n[data-cy^='item-'] (3 instances)\n```\n\n* * *\n",
      "section": "ui-coverage",
      "anchors": [
        "groups-elements-by-selector"
      ],
      "path": "/llm/json/chunked/ui-coverage/configuration/elementgroups.json",
      "token_estimate": 75
    },
    {
      "id": "ui-coverage/configuration/elementgroups#groups-all-elements-in-a-container",
      "doc_id": "ui-coverage/configuration/elementgroups",
      "heading": "Groups all elements in a container",
      "heading_level": 3,
      "content_markdown": "### Groups all elements in a container\n\n#### Config\n\n```\n{  \"uiCoverage\": {    \"elementGroups\": [      {        \"selector\": \"#calendar button\"      }    ]  }}\n```\n\n#### HTML\n\n```\n<body>  <div id=\"calendar\">    <button id=\"jan\"></button>    <button id=\"feb\"></button>    <button id=\"mar\"></button>  </div></body>\n```\n\n#### Elements shown in UI\n\n```\n#calendar button (3 instances)\n```\n\n* * *\n",
      "section": "ui-coverage",
      "anchors": [
        "groups-all-elements-in-a-container"
      ],
      "path": "/llm/json/chunked/ui-coverage/configuration/elementgroups.json",
      "token_estimate": 68
    },
    {
      "id": "ui-coverage/configuration/elementgroups#groups-form-controls-with-labels",
      "doc_id": "ui-coverage/configuration/elementgroups",
      "heading": "Groups form controls with labels",
      "heading_level": 3,
      "content_markdown": "### Groups form controls with labels\n\n#### Config\n\n```\n{  \"uiCoverage\": {    \"elementGroups\": [      {        \"selector\": \"input[name='animal'], label:has(input[name='animal'])\",        \"name\": \"Animal Option\"      }    ]  }}\n```\n\n#### HTML\n\n```\n<body>  <label>    <input id=\"bear\" name=\"animal\"></input>  </label>  <label>    <input id=\"lion\" name=\"animal\"></input>  </label></body>\n```\n\n#### Elements shown in UI\n\n```\nAnimal Option (4 instances)\n```\n",
      "section": "ui-coverage",
      "anchors": [
        "groups-form-controls-with-labels"
      ],
      "path": "/llm/json/chunked/ui-coverage/configuration/elementgroups.json",
      "token_estimate": 68
    },
    {
      "id": "ui-coverage/configuration/elementgroups#groups-dynamic-elements",
      "doc_id": "ui-coverage/configuration/elementgroups",
      "heading": "Groups dynamic elements",
      "heading_level": 3,
      "content_markdown": "### Groups dynamic elements\n\n#### Config\n\n```\n{  \"uiCoverage\": {    \"elementGroups\": [      {        \"selector\": \"[id^='product']\"      }    ]  }}\n```\n\n#### HTML\n\n```\n<body>  <button id=\"product125\">Product 1</button>  <button id=\"product514\">Product 2</button>  <button id=\"product256\">Product 3</button></body>\n```\n\n#### Elements shown in UI\n\n```\n[id^='product'] (3 instances)\n```\n",
      "section": "ui-coverage",
      "anchors": [
        "groups-dynamic-elements"
      ],
      "path": "/llm/json/chunked/ui-coverage/configuration/elementgroups.json",
      "token_estimate": 57
    },
    {
      "id": "ui-coverage/configuration/elementgroups#giving-groups-custom-names",
      "doc_id": "ui-coverage/configuration/elementgroups",
      "heading": "Giving groups custom names",
      "heading_level": 3,
      "content_markdown": "### Giving groups custom names\n\nSometimes 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`.\n\n#### Config\n\n```\n{  \"uiCoverage\": {    \"elementGroups\": [      {        \"selector\": \"[id^='listbox-button-']\",        \"name\": \"Add Button\"      }    ]  }}\n```\n\n#### HTML\n\n```\n<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>\n```\n\n#### Elements shown in UI\n\n```\nAdd Button (4 instances)\n```\n\n* * *\n",
      "section": "ui-coverage",
      "anchors": [
        "giving-groups-custom-names"
      ],
      "path": "/llm/json/chunked/ui-coverage/configuration/elementgroups.json",
      "token_estimate": 116
    },
    {
      "id": "ui-coverage/configuration/elementgroups#grouping-elements-within-shadow-dom",
      "doc_id": "ui-coverage/configuration/elementgroups",
      "heading": "Grouping elements within shadow DOM",
      "heading_level": 3,
      "content_markdown": "### Grouping elements within shadow DOM\n\nWhen you need to group elements within a specific shadow DOM host, use the `documentScope` property to scope your selector to that document context.\n\n#### Config\n\n```\n{  \"uiCoverage\": {    \"elementGroups\": [      {        \"selector\": \"button\",        \"name\": \"Shadow DOM Buttons\",        \"documentScope\": [\"custom-component\"]      }    ]  }}\n```\n\n#### HTML\n\n```\n<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>\n```\n\n#### Elements shown in UI\n\n```\n#root-buttonShadow DOM Buttons (2 instances)\n```\n\nOnly the buttons inside the shadow DOM are grouped together, while the root button remains separate.\n\n* * *\n",
      "section": "ui-coverage",
      "anchors": [
        "grouping-elements-within-shadow-dom"
      ],
      "path": "/llm/json/chunked/ui-coverage/configuration/elementgroups.json",
      "token_estimate": 135
    },
    {
      "id": "ui-coverage/configuration/elementgroups#elements-shown-in-ui",
      "doc_id": "ui-coverage/configuration/elementgroups",
      "heading": "Elements shown in UI",
      "heading_level": 4,
      "content_markdown": "#### Elements shown in UI\n\n```\n#root-buttonShadow DOM Buttons (2 instances)\n```\n\nOnly the buttons inside the shadow DOM are grouped together, while the root button remains separate.\n\n* * *\n",
      "section": "ui-coverage",
      "anchors": [
        "elements-shown-in-ui"
      ],
      "path": "/llm/json/chunked/ui-coverage/configuration/elementgroups.json",
      "token_estimate": 41
    },
    {
      "id": "ui-coverage/configuration/elementgroups#grouping-elements-within-iframes",
      "doc_id": "ui-coverage/configuration/elementgroups",
      "heading": "Grouping elements within iframes",
      "heading_level": 3,
      "content_markdown": "### Grouping elements within iframes\n\nYou can also scope element grouping to elements within specific iframes using `documentScope`.\n\n#### Config\n\n```\n{  \"uiCoverage\": {    \"elementGroups\": [      {        \"selector\": \"[data-action]\",        \"name\": \"Embedded Actions\",        \"documentScope\": [\"#embedded-widget\"]      }    ]  }}\n```\n\n#### HTML\n\n```\n<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>\n```\n\n#### Elements shown in UI\n\n```\n[data-action=\"save\"] (from root document)Embedded Actions (2 instances)\n```\n\nOnly the buttons inside the iframe are grouped together.\n",
      "section": "ui-coverage",
      "anchors": [
        "grouping-elements-within-iframes"
      ],
      "path": "/llm/json/chunked/ui-coverage/configuration/elementgroups.json",
      "token_estimate": 111
    }
  ]
}