Skip to content

Commit 86570c0

Browse files
tbiethmanmarktnoonan
tbiethman
and
marktnoonan
authored
Adding pages for new UI Coverage configuration properties (#6213)
* WIP files for new configuration properties. * Fixing lint errors. Adding 'assert' example. * More formatting * make minor updates and add intro --------- Co-authored-by: marktnoonan <mark@cypress.io>
1 parent bef31f3 commit 86570c0

File tree

4 files changed

+291
-0
lines changed

4 files changed

+291
-0
lines changed

‎docs/ui-coverage/changelog.mdx

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,13 @@ sidebar_position: 200
99

1010
# Changelog
1111

12+
## Week of 6/23/25
13+
14+
UI Coverage now supports defining custom commands that will count towards coverage scores, restricting which kinds of interactions are allowed for certain elements, and including assertions in the UI Coverage calculations. See the following new properties for more details:
15+
16+
- [`additionalInteractionCommands`](/ui-coverage/configuration/additionalinteractioncommands)
17+
- [`allowedInteractionCommands`](/ui-coverage/configuration/allowedinteractioncommands)
18+
1219
## Week of 5/26/2025
1320

1421
- Launched AI-powered Test Generation in Cypress Cloud, to help you quickly add tests for the untested elements detected in UI Coverage reports, in a way that follows your existing practices and conventions. For more details, read [our blog post](https://www.cypress.io/blog/add-your-missing-tests-faster-with-test-generation-in-ui-coverage).

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

Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
---
2+
title: 'Additional Interaction Commands | Cypress UI Coverage'
3+
description: 'The `additionalInteractionCommands` configuration property allows users to extend the default set of interaction command types recognized by UI Coverage.'
4+
sidebar_label: additionalInteractionCommands
5+
sidebar_position: 90
6+
---
7+
8+
<ProductHeading product="ui-coverage" />
9+
10+
# additionalInteractionCommands
11+
12+
UI Coverage automatically tracks how elements are used in tests using a predefined set of [Cypress interaction commands](/ui-coverage/core-concepts/interactivity#Interaction-Commands) such as `click`, `type`, `dblclick`, and more.
13+
14+
The `additionalInteractionCommands` configuration allows you to extend this default set. You can specify custom command types that should also be recognized as interactions, which can increase the range of actions that are counted towards UI Coverage
15+
16+
## Why use additionalInteractionCommands?
17+
18+
- **Custom command support**: Track interactions from custom Cypress commands that aren't included in the default set.
19+
- **Third-party library support**: Ensure interactions from third-party testing libraries (such as [`cypress-real-events`](#Adding-third-party-library-commands)) are properly recognized and tracked.
20+
- **Enhanced reporting**: Improve the accuracy of your UI Coverage reports by including all relevant interaction types.
21+
22+
## Syntax
23+
24+
```json
25+
{
26+
"uiCoverage": {
27+
"additionalInteractionCommands": [
28+
string
29+
]
30+
}
31+
}
32+
```
33+
34+
### Options
35+
36+
The `additionalInteractionCommands` property accepts an array of strings, where each string represents a command name that should be treated as an interaction command by UI Coverage.
37+
38+
| Option | Required | Default | Description |
39+
| ------------------------------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------ |
40+
| `additionalInteractionCommands` | Optional | `[]` | An array of command names (strings) that should be recognized as interaction commands in addition to the defaults. |
41+
42+
## Examples
43+
44+
### Adding custom interaction commands
45+
46+
#### Config
47+
48+
```json
49+
{
50+
"uiCoverage": {
51+
"additionalInteractionCommands": ["customClick", "dragAndDrop", "swipeLeft"]
52+
}
53+
}
54+
```
55+
56+
#### Usage in tests
57+
58+
```javascript
59+
// These custom commands will now be tracked as interactions
60+
cy.get('[data-testid="submit-button"]').customClick()
61+
cy.get('[data-testid="draggable"]').dragAndDrop()
62+
cy.get('[data-testid="carousel"]').swipeLeft()
63+
```
64+
65+
### Adding third-party library commands
66+
67+
#### Config
68+
69+
```json
70+
{
71+
"uiCoverage": {
72+
"additionalInteractionCommands": ["realClick", "realType", "realHover"]
73+
}
74+
}
75+
```
76+
77+
#### Usage in tests
78+
79+
```javascript
80+
// Commands from cypress-real-events plugin will be tracked
81+
cy.get('[data-cy="button"]').realClick()
82+
cy.get('[data-cy="input"]).realType('Hello World')
83+
cy.get('[data-cy="tooltip-trigger"]').realHover()
84+
```
85+
86+
## Notes
87+
88+
- Command names are case-sensitive and must match exactly as they appear in your test code.
89+
- The additional commands are merged with the default interaction commands, the default commands are not replaced.
90+
- Only commands that actually interact with DOM elements should be included in this configuration.
91+
- Custom commands must log a snapshot that references the subject element. This ensures that the command renders element highlights in Cypress open mode/Test Replay, and also ensures that UI Coverage can properly attribute the interaction to the expected element. More information regarding Custom Commands can be found [here](/api/cypress-api/custom-commands).

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

Lines changed: 176 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,176 @@
1+
---
2+
title: 'Allowed Interaction Commands | Cypress UI Coverage'
3+
description: 'The `allowedInteractionCommands` configuration property allows users to limit the interaction commands that are tracked for specific elements in UI Coverage.'
4+
sidebar_label: allowedInteractionCommands
5+
sidebar_position: 100
6+
---
7+
8+
<ProductHeading product="ui-coverage" />
9+
10+
# allowedInteractionCommands
11+
12+
UI Coverage tracks all interaction commands by default for comprehensive coverage reporting. The `allowedInteractionCommands` configuration allows you to limit which interaction commands are tracked for specific elements by defining rules based on CSS selectors.
13+
14+
This is particularly useful for filtering out irrelevant interactions or focusing coverage tracking on specific interaction patterns for different types of elements.
15+
16+
## Why use allowedInteractionCommands?
17+
18+
- **Focused tracking**: Limit coverage tracking to relevant interaction types for specific elements or components to reduce noise in reports.
19+
- **Component-specific rules**: Apply different interaction tracking rules based on element types or component categories. For example, you may require specific kinds of interactions on complex data-visualization components that are not required in regular interactive elements.
20+
21+
## Syntax
22+
23+
```json
24+
{
25+
"uiCoverage": {
26+
"allowedInteractionCommands": [
27+
{
28+
"selector": string,
29+
"commands": [string]
30+
}
31+
]
32+
}
33+
}
34+
```
35+
36+
### Options
37+
38+
The `allowedInteractionCommands` property accepts an array of objects, where each object defines a rule for limiting interaction commands for elements matching a specific selector.
39+
40+
| Option | Required | Default | Description |
41+
| ---------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
42+
| `selector` | Required | | A CSS selector to identify elements. Supports standard CSS selector syntax, including IDs, classes, attributes, and combinators. |
43+
| `commands` | Required | | An array of command names (strings) that should be tracked as interactions for elements matching the selector. All other interaction commands will be ignored for these elements. |
44+
45+
## Examples
46+
47+
### Limiting button interactions to clicks only
48+
49+
#### Config
50+
51+
```json
52+
{
53+
"uiCoverage": {
54+
"allowedInteractionCommands": [
55+
{
56+
"selector": "button, [role='button']",
57+
"commands": ["click", "realClick"]
58+
}
59+
]
60+
}
61+
}
62+
```
63+
64+
#### Usage in tests
65+
66+
```javascript
67+
// Only click and realClick will be tracked for buttons
68+
cy.get('[data-cy="submit-button"]').click() // ✓ Tracked
69+
cy.get('[data-cy="submit-button"]').realClick() // ✓ Tracked
70+
cy.get('[data-cy="submit-button"]').hover() // ✗ Not tracked
71+
cy.get('[data-cy="submit-button"]').focus() // ✗ Not tracked
72+
```
73+
74+
### Different rules for form elements
75+
76+
#### Config
77+
78+
```json
79+
{
80+
"uiCoverage": {
81+
"allowedInteractionCommands": [
82+
{
83+
"selector": "input[type='text'], textarea",
84+
"commands": ["type", "clear", "realType"]
85+
},
86+
{
87+
"selector": "select",
88+
"commands": ["select", "click"]
89+
},
90+
{
91+
"selector": "input[type='checkbox'], input[type='radio']",
92+
"commands": ["check", "uncheck", "click"]
93+
}
94+
]
95+
}
96+
}
97+
```
98+
99+
#### Usage in tests
100+
101+
```javascript
102+
// Text inputs: only type, clear, and realType are tracked
103+
cy.get('[data-cy="username"]').type('john_doe') // ✓ Tracked
104+
cy.get('[data-cy="username"]').clear() // ✓ Tracked
105+
cy.get('[data-cy="username"]').focus() // ✗ Not tracked
106+
107+
// Select elements: only select and click are tracked
108+
cy.get('[data-cy="country"]').select('US') // ✓ Tracked
109+
cy.get('[data-cy="country"]').click() // ✓ Tracked
110+
cy.get('[data-cy="country"]').hover() // ✗ Not tracked
111+
112+
// Checkboxes/Radio buttons: check, uncheck, and click are tracked
113+
cy.get('[data-cy="agree-terms"]').check() // ✓ Tracked
114+
cy.get('[data-cy="agree-terms"]').click() // ✓ Tracked
115+
```
116+
117+
### Excluding hover interactions for mobile components
118+
119+
#### Config
120+
121+
```json
122+
{
123+
"uiCoverage": {
124+
"allowedInteractionCommands": [
125+
{
126+
"selector": "[data-mobile='true']",
127+
"commands": ["click", "tap", "swipe", "type"]
128+
}
129+
]
130+
}
131+
}
132+
```
133+
134+
#### Usage in tests
135+
136+
```javascript
137+
// Mobile components: hover interactions are excluded
138+
cy.get('[data-mobile="true"][data-cy="menu-item"]').click() // ✓ Tracked
139+
cy.get('[data-mobile="true"][data-cy="menu-item"]').tap() // ✓ Tracked
140+
cy.get('[data-mobile="true"][data-cy="menu-item"]').hover() // ✗ Not tracked
141+
```
142+
143+
### Allowing assertions as interactions
144+
145+
Note that because `allowedInteractionCommands` replaces the allowed interactions, if you add `assert` as an interaction, remember to also add any other acceptable interactions to the list.
146+
147+
#### Config
148+
149+
```json
150+
{
151+
"uiCoverage": {
152+
"additionalInteractionCommands": [
153+
{
154+
"selector": "button[data-no-explicit-interaction='true']",
155+
"commands": ["assert"]
156+
}
157+
]
158+
}
159+
}
160+
```
161+
162+
#### Usage in tests
163+
164+
```javascript
165+
// Any assertions on matching elements are tracked
166+
cy.get('button[data-no-explicit-interaction="true"]').should('exist) // ✓ Tracked
167+
cy.get('button[data-no-explicit-interaction="true"]').should('be.visible) // ✓ Tracked
168+
cy.get('button[data-no-explicit-interaction="true"]').click() // ✗ Not tracked
169+
```
170+
171+
## Notes
172+
173+
- Elements that don't match any selector will have all interaction commands tracked (default behavior).
174+
- If an element matches multiple selectors, commands from all matching rules will be allowed. A high degree of specificity for these selectors is recommended.
175+
- Command names are case-sensitive and must match exactly as they appear in your test code.
176+
- This configuration works separately from `additionalInteractionCommands`. Custom commands do **not** need to be globally defined as `additionalInteractionCommands` in order to be declared here.

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

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,17 @@ Configuration enables you to customize and fine-tune UI Coverage in Cypress to s
1313

1414
**Note**: By default, setting configuration is limited to Admin users. At your request, this can be changed to allow setting config by all users. Reach out to your Cypress point-of-contact if you would like to change this.
1515

16+
:::success
17+
18+
## New configuration options
19+
20+
UI Coverage now supports defining custom commands that will count towards coverage scores, restricting which kinds of interactions are allowed for certain elements, and including assertions in the UI Coverage calculations. See the following new properties for more details:
21+
22+
- [`additionalInteractionCommands`](/ui-coverage/configuration/additionalinteractioncommands)
23+
- [`allowedInteractionCommands`](/ui-coverage/configuration/allowedinteractioncommands)
24+
25+
:::
26+
1627
## Setting configuration
1728

1829
To add or modify the configuration for your project:
@@ -27,6 +38,12 @@ To add or modify the configuration for your project:
2738

2839
## Configuration options
2940

41+
:::info
42+
43+
For a quick overview of the practical application of the most common UI Coverage confiuration properties, you can read [this blog post](https://www.cypress.io/blog/making-the-most-of-ui-coverage).
44+
45+
:::
46+
3047
A complete configuration with all available options looks as follows:
3148

3249
```json

0 commit comments

Comments
 (0)