Skip to content

Commit e590bbf

Browse files
marktnoonanmarktnoonan
authored
Update UI Coverage documenation (#6236)
* update docs * fix typos and clarify example * lint fix * remove unsupported example * docs: update significant attributes docs
1 parent 8628816 commit e590bbf

File tree

4 files changed

+33
-96
lines changed

4 files changed

+33
-96
lines changed

‎docs/accessibility/configuration/significantattributes.mdx‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,4 +9,6 @@ sidebar_position: 40
99

1010
# significantAttributes
1111

12+
The `significantAttributes` property allows you to specify which attributes should be considered significant when identifying elements in Cypress Accessibility.
13+
1214
<SignificantAttributes />

‎docs/partials/_significantattributes.mdx‎

Lines changed: 12 additions & 95 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,10 @@
1-
The `significantAttributes` property allows you to specify which attributes should be considered significant for UI Coverage analysis.
2-
31
## Why use significant attributes?
42

5-
- **Focus on Important Changes**: Track attributes that are most relevant to user interaction and functionality
6-
- **Reduce False Positives**: Avoid flagging changes in non-essential attributes as coverage issues
7-
- **Improve Report Clarity**: Make coverage reports more meaningful by focusing on attributes that matter
3+
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.
4+
5+
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.
6+
7+
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.
88

99
## Scope
1010

@@ -16,48 +16,33 @@ supported, if you need to split them up.
1616

1717
## Syntax
1818

19+
`significantAttributes` is an array of strings, with each string being the name of a HTML attribute.
20+
1921
```json
2022
{
2123
"significantAttributes": [
22-
{
23-
"selector": string,
24-
"attributes": string[]
25-
}
24+
string
2625
]
2726
}
2827
```
2928

30-
### Options
31-
32-
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.
33-
34-
| Option | Required | Default | Description |
35-
| ------------ | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------------- |
36-
| `selector` | Required | | A CSS selector to identify elements. Supports standard CSS selector syntax, including IDs, classes, attributes, and combinators. |
37-
| `attributes` | Required | | An array of attribute names that should be considered significant for coverage analysis. |
38-
3929
## Examples
4030

41-
### Marking specific attributes as significant for all elements
31+
### Marking specific attributes as significant
4232

4333
#### Config
4434

4535
```json
4636
{
47-
"significantAttributes": [
48-
{
49-
"selector": "*",
50-
"attributes": ["class", "id", "role"]
51-
}
52-
]
37+
"significantAttributes": ["class", "id", "data-context"]
5338
}
5439
```
5540

5641
#### HTML
5742

5843
```xml
5944
<body>
60-
<button class="primary" id="submit" role="button" data-testid="submit">
45+
<button class="primary" id="submit" data-testid="submit" data-context="user-signup">
6146
Submit
6247
</button>
6348
</body>
@@ -66,73 +51,5 @@ The first `significantAttributes` rule for which the selector property matches t
6651
#### Significant attributes tracked
6752

6853
```
69-
class="primary", id="submit", role="button"
70-
```
71-
72-
---
73-
74-
### Marking different attributes as significant for different elements
75-
76-
#### Config
77-
78-
```json
79-
{
80-
"significantAttributes": [
81-
{
82-
"selector": "input",
83-
"attributes": ["type", "name", "required"]
84-
},
85-
{
86-
"selector": "button",
87-
"attributes": ["type", "disabled"]
88-
}
89-
]
90-
}
91-
```
92-
93-
#### HTML
94-
95-
```xml
96-
<body>
97-
<input type="text" name="username" required class="form-control" />
98-
<button type="submit" disabled class="btn">Submit</button>
99-
</body>
100-
```
101-
102-
#### Significant attributes tracked
103-
104-
```
105-
input: type="text", name="username", required="required"
106-
button: type="submit", disabled="disabled"
107-
```
108-
109-
### Using attribute patterns
110-
111-
#### Config
112-
113-
```json
114-
{
115-
"significantAttributes": [
116-
{
117-
"selector": "*",
118-
"attributes": ["aria-*"]
119-
}
120-
]
121-
}
122-
```
123-
124-
#### HTML
125-
126-
```xml
127-
<body>
128-
<div aria-label="Main content" aria-hidden="false" class="container">
129-
Content
130-
</div>
131-
</body>
132-
```
133-
134-
#### Significant attributes tracked
135-
136-
```
137-
aria-label="Main content", aria-hidden="false"
54+
class="primary", id="submit", data-context="user-signup"
13855
```

‎docs/ui-coverage/configuration/significantattributes.mdx‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,4 +9,6 @@ sidebar_position: 50
99

1010
# significantAttributes
1111

12+
The `significantAttributes` property allows you to specify which attributes should be considered significant when identifying elements in UI Coverage.
13+
1214
<SignificantAttributes />

‎docs/ui-coverage/core-concepts/interactivity.mdx‎

Lines changed: 17 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,16 @@ UI Coverage determines interactivity based on a combination of HTML semantics, [
1919

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

22+
### Customizing interactive elements
23+
24+
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:
25+
26+
```html
27+
<div data-cy-ui-interactive="include">Custom interactive widget</div>
28+
```
29+
30+
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.
31+
2232
## Interaction Commands
2333

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

42-
By ensuring these commands interact with the appropriate elements, UI Coverage accurately reflects your test coverage.
52+
By ensuring that at least one of these commands is used on every interactive element, UI Coverage accurately reflects your test coverage.
53+
54+
### Customizing interaction commands
55+
56+
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.
57+
58+
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.
4359

4460
## Untested Links
4561

0 commit comments

Comments
 (0)