Skip to content

Commit 04ccaa4

Browse files
marktnoonanmarktnoonan
committed
initial pass at docs for config profiles
1 parent 7400f99 commit 04ccaa4

File tree

13 files changed

+382
-22
lines changed

13 files changed

+382
-22
lines changed

‎docs/accessibility/configuration/overview.mdx‎

Lines changed: 43 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -22,45 +22,79 @@ To add or modify the configuration for your project, navigate to the "App Qualit
2222
alt="The Cypress Cloud UI showing the configuration editor"
2323
/>
2424

25-
You can use the provided editor to write configuration in JSON format. A complete configuration with all available options looks as follows:
25+
You can use the provided editor to write configuration in JSON format.
2626

27-
```typescript
27+
### Comments
28+
29+
All configuration objects support an optional `comment` property that you can use to provide context and explanations for why certain values are set. This helps make your configuration easier to understand and maintain, especially when working in teams or revisiting configuration after some time.
30+
31+
```json
32+
{
33+
"elementFilters": [
34+
{
35+
"selector": "[data-testid*='temp']",
36+
"include": false,
37+
"comment": "Exclude temporary test elements from accessibility reports"
38+
}
39+
]
40+
}
41+
```
42+
43+
### Profiles
44+
45+
The `profiles` property allows you to use different configuration settings for different runs based on [run tags](/app/references/command-line#cypress-run-tag-lt-tag-gt). See the [Profiles](/accessibility/configuration/profiles) guide for more details.
46+
47+
### Complete configuration example
48+
49+
A complete configuration with all available options looks as follows:
50+
51+
```json
2852
{
2953
"views": [
3054
{
3155
"pattern": string,
3256
"groupBy": [
3357
string
34-
]
58+
],
59+
"comment": string
3560
}
3661
],
3762
"viewFilters": [
3863
{
3964
"pattern": string,
40-
"include": boolean
65+
"include": boolean,
66+
"comment": string
4167
}
4268
],
4369
"elementFilters": [
4470
{
4571
"selector": string,
46-
"include": boolean
72+
"include": boolean,
73+
"comment": string
4774
}
4875
],
4976
"significantAttributes": [
5077
string
51-
]
78+
],
5279
"attributeFilters": [
5380
{
5481
"attribute": string,
5582
"value": string,
56-
"include": boolean
83+
"include": boolean,
84+
"comment": string
85+
}
86+
],
87+
"profiles": [
88+
{
89+
"name": string,
90+
"config": {
91+
// Any App Quality configuration options
92+
}
5793
}
5894
]
5995
}
6096
```
6197

62-
Note that these root-level App Quality configuration properties (`elementFilters`, `views`, and `viewFilters`) impact both UI Coverage and Accessibility.
63-
6498
### Viewing Configuration for a Run
6599

66100
You can view configuration information for each run in the Properties tab, as shown below. This is the configuration set for the project at the start of the run.

‎docs/accessibility/configuration/profiles.mdx‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
---
2+
sidebar_label: profiles
3+
title: 'Profiles | Cypress Accessibility'
4+
description: 'The `profiles` configuration property allows you to create configuration overrides that are applied based on run tags.'
5+
sidebar_position: 100
6+
---
7+
8+
<ProductHeading product="accessibility" />
9+
10+
# profiles
11+
12+
<Profiles />

‎docs/partials/_attributefilters.mdx‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,8 @@ supported, if you need to split them up.
2424
{
2525
"attribute": string,
2626
"value": string,
27-
"include": boolean
27+
"include": boolean,
28+
"comment": string
2829
}
2930
]
3031
}
@@ -39,6 +40,7 @@ For every attribute that an element has, the first `attributeFilters` rule for w
3940
| `attribute` | Required | | A regex string to match attribute names |
4041
| `value` | Optional | `.*` | A regex string to match attribute values |
4142
| `include` | Optional | `true` | A boolean to specify whether the matched attribute should be included. |
43+
| `comment` | Optional | | A comment describing the purpose of this filter rule. |
4244

4345
## Examples
4446

‎docs/partials/_elementfilters.mdx‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,8 @@ supported, if you need to split them up.
1818
"elementFilters": [
1919
{
2020
"selector": string,
21-
"include": boolean
21+
"include": boolean,
22+
"comment": string
2223
}
2324
]
2425
}
@@ -32,6 +33,7 @@ The first `elementFilters` rule for which the selector property matches the elem
3233
| ---------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------------- |
3334
| `selector` | Required | | A CSS selector to identify elements. Supports standard CSS selector syntax, including IDs, classes, attributes, and combinators. |
3435
| `include` | Optional | `true` | A boolean indicating whether the matched elements should be included in the report. |
36+
| `comment` | Optional | | A comment describing the purpose of this filter rule. |
3537

3638
## Examples
3739

@@ -44,7 +46,8 @@ The first `elementFilters` rule for which the selector property matches the elem
4446
"elementFilters": [
4547
{
4648
"selector": "#button-2",
47-
"include": false
49+
"include": false,
50+
"comment": "Exclude test-only button from reports"
4851
}
4952
]
5053
}

‎docs/partials/_profiles.mdx‎

Lines changed: 249 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,249 @@
1+
The `profiles` property allows you to create configuration overrides that are applied based on run tags. This enables you to use different configuration settings for different types of runs, such as regression tests compared to smoke tests environments, or providing scoped results relevant to specific teams.
2+
3+
## Why use profiles?
4+
5+
- **Team specific reporting**: If multiple teams use the same Cypress Cloud project, they may have completely different areas of concern for which pages or DOM elements are included in reports about accessibility or UI Coverage. Profiles allow each team to see and track against only the results that matter to them, and remove all other findings.
6+
- **Run-type customization**: Use different filters or settings for regression runs versus pull requests. It can be useful to have a narrow config for blocking a merge, optimized for the most critical areas of your app -- while still running a wide config on a full regression suite to manage on a difference cadence.
7+
- **Skip runs when needed**: If you know that certain kinds of runs are not going to be valuable for App Quality reporting, you can ignore all view on these runs so that no report is created. In some situations this can improve clarity about when to look at a report and which reports are considered significant.
8+
9+
## How profiles work
10+
11+
Profiles are selected by matching run tags to profile names. When you run Cypress with the [`--tag`](/app/references/command-line#cypress-run-tag-lt-tag-gt) flag, Cypress Cloud looks for a profile whose `name` matches one of the tags. If a match is found, properties defined in profile's `config` properties override the root configuration. Properties defined in the root that are not referenced in the profile will be inherited, meaning you do not need to repeat config values that you want to keep the same.
12+
13+
If more than one tag provided to a run matches a profile in your App Quality profiles array, the first matching profile in the array will be used. The order in which the tags are passed to the run doesn't matter.
14+
15+
## Best practices
16+
17+
Use a naming convention like `aq-config-x` (e.g., `aq-config-regression`, `aq-config-staging`) to make it clear that a tag is used for configuration lookup purposes.
18+
19+
While relying on existing tags works just fine, but being explicit will help avoid accidental removal or changes of important tags.
20+
21+
## Syntax
22+
23+
```json
24+
{
25+
"profiles": [
26+
{
27+
"name": string,
28+
"config": {
29+
// Any App Quality configuration options
30+
},
31+
"comment": string
32+
}
33+
]
34+
}
35+
```
36+
37+
### Options
38+
39+
| Option | Required | Description |
40+
| --------- | -------- | --------------------------------------------------------------------------------------------------------- |
41+
| `name` | Required | The profile name that must match a run tag to activate this profile. |
42+
| `config` | Required | An object containing any App Quality configuration options. These values override the root configuration. |
43+
| `comment` | Optional | A comment describing the purpose of this profile. |
44+
45+
## Examples
46+
47+
### Basic profile structure
48+
49+
#### Config
50+
51+
```json
52+
{
53+
"elementFilters": [
54+
{
55+
"selector": "[data-testid*='temp']",
56+
"include": false,
57+
"comment": "Exclude temporary test elements"
58+
}
59+
],
60+
"profiles": [
61+
{
62+
"name": "aq-config-regression",
63+
"config": {
64+
"elementFilters": [
65+
{
66+
"selector": "[data-testid*='temp']",
67+
"include": false,
68+
"comment": "Exclude temporary test elements in regression runs"
69+
},
70+
{
71+
"selector": "[data-role='debug']",
72+
"include": false,
73+
"comment": "Exclude debug elements in regression runs"
74+
}
75+
]
76+
}
77+
}
78+
]
79+
}
80+
```
81+
82+
#### Usage
83+
84+
To use this profile, run Cypress with a matching tag:
85+
86+
```shell
87+
cypress run --record --tag "aq-config-regression"
88+
```
89+
90+
When this tag is used, the profile's `elementFilters` configuration will override the base `elementFilters`, excluding both temporary test elements and debug elements.
91+
92+
---
93+
94+
### Multiple profiles
95+
96+
You can define multiple profiles for different scenarios:
97+
98+
#### Config
99+
100+
```json
101+
{
102+
"elementFilters": [
103+
{
104+
"selector": "[data-testid*='temp']",
105+
"include": false
106+
}
107+
],
108+
"profiles": [
109+
{
110+
"name": "aq-config-regression",
111+
"config": {
112+
"elementFilters": [
113+
{
114+
"selector": "[data-testid*='temp']",
115+
"include": false
116+
},
117+
{
118+
"selector": "[data-role='debug']",
119+
"include": false,
120+
"comment": "Exclude debug elements in regression runs"
121+
}
122+
]
123+
}
124+
},
125+
{
126+
"name": "aq-config-staging",
127+
"config": {
128+
"viewFilters": [
129+
{
130+
"pattern": "https://staging.example.com/admin/*",
131+
"include": false,
132+
"comment": "Exclude admin pages in staging runs"
133+
}
134+
]
135+
}
136+
}
137+
]
138+
}
139+
```
140+
141+
#### Usage
142+
143+
Use different tags to activate different profiles:
144+
145+
```shell
146+
# For regression runs
147+
cypress run --record --tag "aq-config-regression"
148+
149+
# For staging runs
150+
cypress run --record --tag "aq-config-staging"
151+
```
152+
153+
---
154+
155+
### Profile with nested configuration
156+
157+
Profiles can override configuration at any level, including nested configuration specific to Cypress Accessibility or UI Coverage, if your project has both projects enabled. For example:
158+
159+
#### Config
160+
161+
```json
162+
{
163+
"elementFilters": [
164+
{
165+
"selector": "[data-testid*='temp']",
166+
"include": false
167+
}
168+
],
169+
"uiCoverage": {
170+
"attributeFilters": [
171+
{
172+
"attribute": "id",
173+
"value": ":r.*:",
174+
"include": false,
175+
"comment": "Filter out React auto-generated IDs"
176+
}
177+
]
178+
},
179+
"profiles": [
180+
{
181+
"name": "aq-config-feature-branch",
182+
"config": {
183+
"uiCoverage": {
184+
"elementGroups": [
185+
{
186+
"selector": "[data-feature='new-checkout']",
187+
"name": "New Checkout Flow",
188+
"comment": "Group new checkout elements for feature branch testing"
189+
}
190+
]
191+
}
192+
}
193+
}
194+
]
195+
}
196+
```
197+
198+
#### Usage
199+
200+
```shell
201+
cypress run --record --tag "aq-config-feature-branch"
202+
```
203+
204+
This profile adds element grouping for the new checkout flow while keeping the base configuration for element filters and attribute filters.
205+
206+
---
207+
208+
### Profile selection with multiple matching tags
209+
210+
If you pass multiple tags and more than one matches a profile name, the first matching profile in the `profiles` array is used:
211+
212+
#### Config
213+
214+
```json
215+
{
216+
"profiles": [
217+
{
218+
"name": "aq-config-regression",
219+
"config": {
220+
"elementFilters": [
221+
{
222+
"selector": "[data-role='debug']",
223+
"include": false
224+
}
225+
]
226+
}
227+
},
228+
{
229+
"name": "aq-config-staging",
230+
"config": {
231+
"viewFilters": [
232+
{
233+
"pattern": "https://staging.example.com/admin/*",
234+
"include": false
235+
}
236+
]
237+
}
238+
}
239+
]
240+
}
241+
```
242+
243+
#### Usage
244+
245+
```shell
246+
cypress run --record --tag "aq-config-regression,aq-config-staging"
247+
```
248+
249+
In this case, the `aq-config-regression` profile will be used because it appears first in the `profiles` array, even though both tags match profile names.

0 commit comments

Comments
 (0)