Skip to content

Update UI Coverage documenation #6236

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

Merged
merged 7 commits into from
Aug 6, 2025
Merged

Update UI Coverage documenation #6236

Show file tree
Hide file tree
Changes from 3 commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
a0ecae3
update docs
marktnoonan Jul 31, 2025
48dfa1f
fix typos and clarify example
marktnoonan Jul 31, 2025
627f9ca
lint fix
marktnoonan Jul 31, 2025
0cabb78
remove unsupported example
marktnoonan Aug 5, 2025
427c156
Merge branch 'main' into marktnoonan/significant-attributes
marktnoonan Aug 5, 2025
3ec23b6
docs: update significant attributes docs
marktnoonan Aug 5, 2025
8fe848c
Merge branch 'marktnoonan/significant-attributes' of https://github.c…
marktnoonan Aug 5, 2025
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
2 changes: 2 additions & 0 deletions docs/accessibility/configuration/significantattributes.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,4 +9,6 @@ sidebar_position: 40

# significantAttributes

The `significantAttributes` property allows you to specify which attributes should be considered significant when identifying elements in Cypress Accessibility.

<SignificantAttributes />
81 changes: 11 additions & 70 deletions docs/partials/_significantattributes.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,10 +1,10 @@
The `significantAttributes` property allows you to specify which attributes should be considered significant for UI Coverage analysis.

## Why use significant attributes?

- **Focus on Important Changes**: Track attributes that are most relevant to user interaction and functionality
- **Reduce False Positives**: Avoid flagging changes in non-essential attributes as coverage issues
- **Improve Report Clarity**: Make coverage reports more meaningful by focusing on attributes that matter
Cypress uses a [default set of attributes](/accessibility/core-concepts/element-identification) (such as common test ID patterns), in a priority order, as the preferred way to identify elements in reports.

The values of these attributes are used as element identifiers, which helps us recognize the same element in multiple contexts and deduplicate the findings. This helps when reviewing run reports, or comparing reports in Branch Review.

You may have attributes already in place in your application that would help with element organization, such as `data-component-name`. If you would like Cypress to use and prioritize these attributes, or you want to change the default priority order, you can define your own list of significant attributes.

## Scope

Expand All @@ -19,45 +19,28 @@ supported, if you need to split them up.
```json
{
"significantAttributes": [
{
"selector": string,
"attributes": string[]
}
string
]
}
```

### Options

The first `significantAttributes` rule for which the selector property matches the element is used to determine which attributes should be considered significant. Attributes that do not match any rules are not considered significant by default.

| Option | Required | Default | Description |
| ------------ | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `selector` | Required | | A CSS selector to identify elements. Supports standard CSS selector syntax, including IDs, classes, attributes, and combinators. |
| `attributes` | Required | | An array of attribute names that should be considered significant for coverage analysis. |

## Examples

### Marking specific attributes as significant for all elements
### Marking specific attributes as significant

#### Config

```json
{
"significantAttributes": [
{
"selector": "*",
"attributes": ["class", "id", "role"]
}
]
"significantAttributes": ["class", "id", "data-context"]
}
```

#### HTML

```xml
<body>
<button class="primary" id="submit" role="button" data-testid="submit">
<button class="primary" id="submit" data-testid="submit" data-context="user-signup">
Submit
</button>
</body>
Expand All @@ -66,44 +49,7 @@ The first `significantAttributes` rule for which the selector property matches t
#### Significant attributes tracked

```
class="primary", id="submit", role="button"
```

---

### Marking different attributes as significant for different elements

#### Config

```json
{
"significantAttributes": [
{
"selector": "input",
"attributes": ["type", "name", "required"]
},
{
"selector": "button",
"attributes": ["type", "disabled"]
}
]
}
```

#### HTML

```xml
<body>
<input type="text" name="username" required class="form-control" />
<button type="submit" disabled class="btn">Submit</button>
</body>
```

#### Significant attributes tracked

```
input: type="text", name="username", required="required"
button: type="submit", disabled="disabled"
class="primary", id="submit", data-context="user-signup"
```

### Using attribute patterns
Expand All @@ -112,12 +58,7 @@ button: type="submit", disabled="disabled"

```json
{
"significantAttributes": [
{
"selector": "*",
"attributes": ["aria-*"]
}
]
"significantAttributes": ["aria-*"]
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

IIRC this doesn't support wildcarding

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not totally sure if this API exactly matches what unique-selector accepts, but if it does, it would be something like['attribute:aria-label', 'attribute:role', 'id', 'class']

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@jennifer-shehane That's abstracted away by UICov logic here https://github.com/cypress-io/cypress-services/blob/develop/discovery/packages/common/src/elementProcessingUtils.ts#L72

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

yeah I didn't verify on the wildcarding, I'll remove this from the PR

}
```

Expand Down
2 changes: 2 additions & 0 deletions docs/ui-coverage/configuration/significantattributes.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,4 +9,6 @@ sidebar_position: 50

# significantAttributes

The `significantAttributes` property allows you to specify which attributes should be considered significant when identifying elements in UI Coverage.

<SignificantAttributes />
18 changes: 17 additions & 1 deletion docs/ui-coverage/core-concepts/interactivity.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,16 @@ UI Coverage determines interactivity based on a combination of HTML semantics, [

These elements are tracked for interaction to provide actionable insights into test coverage.

### Customizing interactive elements

Custom interactive elements that do not meet the criteria above can also be declared with a `data-cy-ui-interactive="include"` attribute, used as follows:

```html
<div data-cy-ui-interactive="include">Custom interactive widget</div>
```

It most cases we recommend **not** using this override, and instead updating the HTML to be something the browser would already consider to be interactive. This will likely produce better overall behavior, including for accessibility purposes. `data-cy-ui-interactive` is a fallback for situations where that may not be possible.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Personally I would word this a bit more strongly - something like "use of this attribute is a strong signal there is an issue with the HTML structure of your application which likely has real-world impacts for users, particularly those using screen readers or with disabilities. If possible we recommend updating your HTML to better convey the interactive nature of this element; this would improve the functionality of your application for these users as well as automatically detect the element in the report. As a fallback for scenarios where this isn't possible......."

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not so sure about this. Since we can now support requiring custom commands and the "assert" command - you might have a totally valid reason to want to change the definition of what we consider interactive without it implying the elements themselves are broken.

Still might need another pass at this though - the framing of everything in terms of "interactions" might not be the most accurate, long term. Will think on it a bit.


## Interaction Commands

Interactive elements are marked as "tested" when they are interacted with using specific Cypress commands. These include:
Expand All @@ -39,7 +49,13 @@ Interactive elements are marked as "tested" when they are interacted with using
- `type`
- `uncheck`

By ensuring these commands interact with the appropriate elements, UI Coverage accurately reflects your test coverage.
By ensuring that at least one of these commands is used on every interactive element, UI Coverage accurately reflects your test coverage.

### Customizing interaction commands

Configuration is available to support adding [additional interaction commands](/ui-coverage/configuration/additionalinteractioncommands), such as custom commands or ones from third-party libraries, to count towards UI Coverage scores.

It is also possible to adjust the [allowed commands](/ui-coverage/configuration/allowedinteractioncommands) for specific elements, to restrict or expand the commands that are accepted as coverage for specific elements.

## Untested Links

Expand Down