Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[WIP] supplementalElements UI Coverage configuration #6029

Draft
wants to merge 4 commits into
base: main
Choose a base branch
from
Draft

[WIP] supplementalElements UI Coverage configuration #6029

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
3cc5fd0
supplementalElements UI Coverage configuration
pstakoun Dec 5, 2024
f5f5b4b
Fix classes
pstakoun Dec 5, 2024
d934073
Rename file for consistency
pstakoun Dec 5, 2024
8f42d43
Fix description
pstakoun Dec 13, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
145 changes: 145 additions & 0 deletions docs/ui-coverage/configuration/supplementalelements.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,145 @@
---
title: 'Supplemental Elements | Cypress UI Coverage'
description: 'The `supplementalElements` configuration property allows you to specify parent elements that should be used to supply additional information for identifying and grouping elements.'
sidebar_label: supplementalElements
---

# supplementalElements

<UICovAddon />

UI Coverage has logic that automatically [identifies](/ui-coverage/core-concepts/element-identification) and [groups](/ui-coverage/core-concepts/element-grouping) elements based on their appearance and structure in the DOM.

Sometimes, an element may not have enough information for Cypress's UI Coverage algorithm to accurately perform identification and grouping. This can cause the same element to be identified as multiple different elements, or multiple different elements to be identified as the same element.

The `supplementalElements` configuration property allows users to specify selectors for parent elements that should be used to supply additional information for identifying and grouping elements, thereby allowing UI Coverage to find more suitable identifiers for elements nested within these supplemental elements.

For every element considered interactive and visible by UI Coverage, each element above it in the DOM is run through the `supplementalElements` configuration. For each parent element that matches a `supplementalSelector`, its significant attributes will be used to help identify and group elements that match the corresponding `elementSelector`. If no `elementSelector` is specified, the supplemental information will be applied to all descendant elements.

## Syntax

```json
{
"uiCoverage": {
"supplementalElements": [
{
"supplementalSelector": string,
"elementSelector": string
}
]
}
}
```

### supplementalElements

_Optional._ Object\[]

An array of objects used to determine which parent elements should be used to supply additional information for identifying and grouping elements. _**Each object can have the following properties:**_

### supplementalSelector

_Required._ String (CSS Selector)

Used to match the parent elements that should be used to supply additional information for identifying and grouping elements.

### elementSelector

_Optional._ String (CSS Selector)

_Default_: `*` (matches any value).

Used to match elements that should receive supplemental information.

## Examples

### Using a parent element to provide supplemental data for all elements

#### Config

```json
{
"uiCoverage": {
"supplementalElements": [
{
"supplementalSelector": ".page-container",
"elementSelector": "*"
}
]
}
}
```

#### HTML

```xml
<!-- Snapshot 1 -->
<body>
<div id="login-page" class="page-container">
<button id="submit">Login</button>
<button id="cancel">Cancel</button>
</div>
</body>

<!-- Snapshot 2 -->
<body>
<div id="signup-page" class="page-container">
<button id="submit">Signup</button>
<button id="cancel">Cancel</button>
</div>
</body>
```

#### Elements shown in UI

```
#login-page #submit
#login-page #cancel
#signup-page #submit
#signup-page #cancel
```

### Using a parent element to provide supplemental data for specific elements

#### Config

```json
{
"uiCoverage": {
"supplementalElements": [
{
"supplementalSelector": ".page-container",
"elementSelector": "#submit"
}
]
}
}
```

#### HTML

```xml
<!-- Snapshot 1 -->
<body>
<div id="login-page" class="page-container">
<button id="submit">Login</button>
<button id="cancel">Cancel</button>
</div>
</body>

<!-- Snapshot 2 -->
<body>
<div id="signup-page" class="page-container">
<button id="submit">Signup</button>
<button id="cancel">Cancel</button>
</div>
</body>
```

#### Elements shown in UI

```
#login-page #submit
#signup-page #submit
#cancel
```