diff --git a/docs/accessibility/configuration/elementfilters.mdx b/docs/accessibility/configuration/elementfilters.mdx index 99fc3d1c50..c3ba856877 100644 --- a/docs/accessibility/configuration/elementfilters.mdx +++ b/docs/accessibility/configuration/elementfilters.mdx @@ -9,169 +9,4 @@ sidebar_position: 20 # elementFilters -:::info - -**Note:** setting `elementFilters` impacts both Accessibility and UI Coverage -reports if set at the root of the configuration. Nesting this property under an `accessibility` or `uiCoverage` key is -supported, if you need to split them up. -::: - -The `elementFilters` property allows you to specify selectors for elements that should be excluded from Cypress Accessibility. - -The first `elementFilters` rule to match the `selector` property determines whether or not an element is included or excluded from the report. Elements that do not match any rules are included by default. - -## Syntax - globally applied to both UI Coverage and Cypress Accessibility - -```typescript -{ - "elementFilters": [ - { - "selector": string, - "include": boolean - } - ] -} -``` - -## Syntax - accessibility-specific - -```typescript -{ - "accessibility": { - "elementFilters": [ - { - "selector": string, - "include": boolean - } - ] - } -} -``` - -### elementFilters - -_Optional._ Object\[] - -An array of objects specifying the elements to exclude from Cypress Accessibility. _**Each object can have the following properties:**_ - -### selector - -_Required._ String (CSS Selector) - -Used to match elements. - -### include - -_Optional._ Boolean - -_Default:_ `true` - -A boolean that represents whether or not a matched element should be included in Cypress Accessibility. - -## Examples - -### Excluding a specific element - -#### Config - -```json -{ - "elementFilters": [ - { - "selector": "#button-2", - "include": false - } - ] -} -``` - -#### HTML - -```xml - - - - -``` - -#### Elements shown in UI - -``` -#button-1 -``` - ---- - -### Excluding all elements in a container - -#### Config - -```json -{ - "elementFilters": [ - { - "selector": "footer *", - "include": false - } - ] -} -``` - -#### HTML - -```xml - -
- -
- - -``` - -#### Elements shown in UI - -``` -#start -``` - ---- - -### Including only elements in a container - -#### Config - -```json -{ - "elementFilters": [ - { - "selector": "#form *", - "include": true - }, - { - "selector": "*", - "include": false - } - ] -} -``` - -#### HTML - -```xml - -
- -
- - -``` - -#### Elements shown in UI - -``` -#name -``` + diff --git a/docs/accessibility/configuration/viewfilters.mdx b/docs/accessibility/configuration/viewfilters.mdx index 530f3ee6eb..45b45648c5 100644 --- a/docs/accessibility/configuration/viewfilters.mdx +++ b/docs/accessibility/configuration/viewfilters.mdx @@ -9,112 +9,4 @@ sidebar_position: 30 # viewFilters -:::info -Note: setting `viewFilters` impacts both Accessibility and UI Coverage reports. -This cannot be nested. -::: - -By default, every URL that is visited within a run is included in the Accessibility report. The `viewFilters` property allows you to specify URL patterns for URLs that should be excluded from Accessibility. Excluding a URL also excludes all links to that URL. - -For every URL visited by Cypress in a run and every link element found, the first `viewFilters` rule for which the `pattern` property matches the URL is used to either include or exclude the URL based on the `include` value. URLs that do not match any rules are included by default. - -## Syntax - -```typescript -{ - "viewFilters": [ - { - "pattern": string, - "include": boolean - } - ] -} -``` - -### viewFilters - -_Optional._ Object\[] - -An array of objects used to specify URLs to exclude from Accessibility. _**Each object can have the following properties:**_ - -### pattern - -_Required._ String (URL Pattern) - -Used to match URLs. Uses [URL Pattern API](https://developer.mozilla.org/en-US/docs/Web/API/URL_Pattern_API) syntax. - -### include - -_Optional._ Boolean - -_Default:_ `true` - -A boolean that represents whether or not a matched URL should be included in Accessibility. - -## Examples - -### Excluding URLs by hostname - -**Config** - -```json -{ - "viewFilters": [ - { - "pattern": "https://app.okta.com/*", - "include": false - } - ] -} -``` - -**Visited URLs** - -``` -https://app.okta.com/login -https://cypress.io/home -https://cypress.io/about -``` - -**Views shown in UI** - -``` -https://cypress.io/home -https://cypress.io/about -``` - -### Including only specific URLs - -**Config** - -```json -{ - "viewFilters": [ - { - "pattern": "https://cypress.io/dashboards*", - "include": true - }, - { - "pattern": "*", - "include": false - } - ] -} -``` - -**Visited URLs** - -``` -https://cypress.io/dashboards -https://cypress.io/dashboards/1 -https://cypress.io/dashboards/2 -https://cypress.io/home -https://cypress.io/login -``` - -**Views shown in UI** - -``` -https://cypress.io/dashboards -https://cypress.io/dashboards/* -``` + diff --git a/docs/accessibility/configuration/views.mdx b/docs/accessibility/configuration/views.mdx index 2aaef430a2..a20b30059b 100644 --- a/docs/accessibility/configuration/views.mdx +++ b/docs/accessibility/configuration/views.mdx @@ -9,204 +9,4 @@ sidebar_position: 40 # views -:::info -Note: setting views impacts both Accessibility and UI Coverage reports. -Nesting this property under an `accessibility` or `uiCoverage` key is -supported, if you need to split them up. -::: - -Cypress Accessibility automatically groups certain URL patterns to create [views](/ui-coverage/core-concepts/views). For URLs that are not automatically grouped (e.g. `/users/alice` and `/users/bob` are not automatically grouped into `/users/*`), the `views` property allows you to specify your own URL patterns that represent views. - -Each URL pattern provided defines a view that is made up of all URLs that match the pattern. The first pattern that a given URL matches is used as its view. If a URL doesn't match any of the patterns, it is grouped by the default Accessibility grouping rules, if possible. - -The `groupBy` property of a view definition allows you to create multiple views with a single URL pattern, grouping URLs by the specified named parameter(s). - -## Syntax - -```typescript -{ - "views": [ - { - "pattern": string, - "groupBy": [ - string - ] - } - ] -} -``` - -### views - -_Optional._ Object\[] - -An array of objects used to define views within Accessibility. _**Each object can have the following properties:**_ - -### pattern - -_Required._ String (URL Pattern) - -A URL pattern that is used to group matching URLs into a view. Uses [URL Pattern API](https://developer.mozilla.org/en-US/docs/Web/API/URL_Pattern_API) syntax. - -### groupBy - -_Optional._ String\[] - -The URL parameters that should be used to subdivide the URLs into multiple views, rather than being grouped into a single view. - -## Examples - -### Grouping dynamic path parameters - -**Config** - -```json -{ - "views": [ - { - "pattern": "https://cypress.io/users/*" - } - ] -} -``` - -**Visited URLs** - -``` -https://cypress.io/users/alice -https://cypress.io/users/alice?foo=bar -https://cypress.io/users/bob -https://cypress.io/users/bob#baz -``` - -**Views shown in UI** - -``` -https://cypress.io/users/* -``` - -### Using named path parameters - -**Config** - -Copy - -```json -{ - "views": [ - { - "pattern": "https://cypress.io/users/:name\\?*#*" - } - ] -} -``` - -**Visited URLs** - -``` -https://cypress.io/users/alice -https://cypress.io/users/alice?foo=bar -https://cypress.io/users/bob -https://cypress.io/users/bob#baz -``` - -**Views shown in UI** - -``` -https://cypress.io/users/:name -``` - -### Grouping URLs by named path parameters - -**Config** - -``` -{ - "views": [ - { - "pattern": "https://cypress.io/analytics/:type/:id\\?*#*", - "groupBy": [ - "type" - ] - } - ] -} -``` - -**Visited URLs** - -``` -https://cypress.io/analytics/performance/foo -https://cypress.io/analytics/performance/bar -https://cypress.io/analytics/usage/foo -https://cypress.io/analytics/usage/bar -``` - -**Views shown in UI** - -``` -https://cypress.io/analytics/performance/:id -https://cypress.io/analytics/usage/:id -``` - -### Grouping URLs by named query parameters - -**Config** - -```json -{ - "views": [ - { - "pattern": "https://cypress.io/app?*name=:name{&*}?#*", - "groupBy": ["name"] - } - ] -} -``` - -**Visited URLs** - -``` -https://cypress.io/app?foo=1&name=hello -https://cypress.io/app?name=hello&bar=2 -https://cypress.io/app?foo=3&name=world&bar=4 -https://cypress.io/app?foo=5&name=world#baz -``` - -**Views shown in UI** - -``` -https://cypress.io/app?name=hello -https://cypress.io/app?name=world -``` - -### Grouping URLs by path parameters to ignore dynamic hosts - -**Config** - -```json -{ - "views": [ - { - "pattern": "https://*.cypress.io/:rest*\\?*#*", - "groupBy": ["rest"] - } - ] -} -``` - -**Visited URLs** - -```url -https://sub1.cypress.io/foo -https://sub2.cypress.io/bar -https://sub3.cypress.io/foo -https://sub4.cypress.io/bar -``` - -**Views shown in UI** - -``` -https://*.cypress.io/foo -https://*.cypress.io/bar -``` + diff --git a/docs/partials/_elementfilters.mdx b/docs/partials/_elementfilters.mdx new file mode 100644 index 0000000000..ab84b9e918 --- /dev/null +++ b/docs/partials/_elementfilters.mdx @@ -0,0 +1,204 @@ +The `elementFilters` property allows you to specify selectors for elements that should be excluded from reports. + +## Why use element filters? + +:::info +**Note:** setting `elementFilters` impacts both Accessibility and UI Coverage +reports if set at the root of the configuration. Nesting this property under an `accessibility` or `uiCoverage` key is +supported, if you need to split them up. +::: + +- **Ignoring 3rd Party Components**: Libraries or widgets that are not part of your application logic may be excluded from reports. +- **Streamlining Reports**: Reducing noise by filtering out non-essential elements makes reports more actionable. + +## Syntax + +```json +{ + "elementFilters": [ + { + "selector": string, + "include": boolean + } + ] +} +``` + +### Options + +The first `elementFilters` rule for which the selector property matches the element is used to either include or exclude the element based on the `include` value. Elements that do not match any rules are included 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. | +| `include` | Optional | `true` | A boolean indicating whether the matched elements should be included in the report. | + +## Examples + +### Excluding a specific element + +#### Config + +```json +{ + "elementFilters": [ + { + "selector": "#button-2", + "include": false + } + ] +} +``` + +#### HTML + +```xml + + + + +``` + +#### Elements shown in UI + +``` +#button-1 +``` + +--- + +### Excluding all elements in a container + +#### Config + +```json +{ + "elementFilters": [ + { + "selector": "footer *", + "include": false + } + ] +} +``` + +#### HTML + +```xml + +
+ +
+ + +``` + +#### Elements shown in UI + +``` +#start +``` + +--- + +### Including only elements in a specific container + +#### Config + +```json +{ + "elementFilters": [ + { + "selector": "#form *", + "include": true + }, + { + "selector": "*", + "include": false + } + ] +} +``` + +#### HTML + +```xml + +
+ +
+ + +``` + +#### Elements shown in UI + +``` +#name +``` + +### Excluding Elements by Attribute + +#### Config + +```json +{ + "elementFilters": [ + { + "selector": "[data-role='decorative']", + "include": false + } + ] +} +``` + +```xml + + + + +``` + +#### Elements shown in UI + +``` +[data-role="primary"] +``` + +### Excluding dynamic elements by pattern + +#### Config + +```json +{ + "elementFilters": [ + { + "selector": "[class^='auth']", + "include": false + } + ] +} +``` + +#### HTML + +```xml + + + + +``` + +#### Elements shown in UI + +``` +.cancel +``` diff --git a/docs/partials/_viewfilters.mdx b/docs/partials/_viewfilters.mdx new file mode 100644 index 0000000000..94db332116 --- /dev/null +++ b/docs/partials/_viewfilters.mdx @@ -0,0 +1,138 @@ +By default, every URL visited within a test run is included in reports. However, not all URLs are relevant for your analysis. The `viewFilters` property allows you to specify patterns for URLs that should be excluded, ensuring your reports focus on meaningful parts of your application. Excluding a URL also excludes all links pointing to that URL. + +## Why use view filters? + +:::info +Note: setting `viewFilters` impacts both Accessibility and UI Coverage reports. +This cannot be nested. +::: + +- **Exclude Third-Party URLs**: If your application integrates with third-party services, you might want to exclude their URLs from analysis. +- **Exclude Admin Pages**: URLs that are not part of the user-facing application, such as admin pages, could be excluded from reports. +- **Reduce Noise**: Certain URLs visited during tests (e.g., error pages or redirects) may not represent meaningful user flows. Exclude these to clean up your reports. +- **Optimize Performance**: Filtering out irrelevant URLs reduces the amount of data processed, speeding up analysis and improving report readability. + +## Syntax + +```json +{ + "viewFilters": [ + { + "pattern": string, + "include": boolean + } + ] +} +``` + +### Options + +For every URL visited and link element found, the first `viewFilters` rule for which the `pattern` matches the URL is used to either include or exclude the URL based on the `include` value. URLs that do not match any rules are included by default. + +| Option | Required | Default | Description | +| --------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------- | +| `pattern` | Required | | A string that matches URLs using [URL Pattern API](https://developer.mozilla.org/en-US/docs/Web/API/URL_Pattern_API) syntax. | +| `include` | Optional | `true` | A boolean that determines whether matching URLs should be included in the report. | + +## Examples + +### Excluding URLs by hostname + +#### Config + +```json +{ + "viewFilters": [ + { + "pattern": "https://app.okta.com/*", + "include": false + } + ] +} +``` + +#### Visited URLs + +``` +https://app.okta.com/login +https://cypress.io/home +https://cypress.io/about +``` + +#### Views shown in UI + +``` +https://cypress.io/home +https://cypress.io/about +``` + +--- + +### Including only specific URLs + +#### Config + +```json +{ + "viewFilters": [ + { + "pattern": "https://cypress.io/dashboards*", + "include": true + }, + { + "pattern": "*", + "include": false + } + ] +} +``` + +#### Visited URLs + +``` +https://cypress.io/dashboards +https://cypress.io/dashboards/1 +https://cypress.io/dashboards/2 +https://cypress.io/home +https://cypress.io/login +``` + +#### Views shown in UI + +``` +https://cypress.io/dashboards +https://cypress.io/dashboards/* +``` + +### Excluding error pages + +#### Config + +```json +{ + "viewFilters": [ + { + "pattern": "http*://*/404", + "include": false + }, + { + "pattern": "http*://*/error/*", + "include": false + } + ] +} +``` + +#### Visited URLs + +``` +https://cypress.io/home +https://cypress.io/404 +https://cypress.io/error/500 +``` + +#### Views shown in UI + +``` +https://cypress.io/home +``` diff --git a/docs/partials/_views.mdx b/docs/partials/_views.mdx new file mode 100644 index 0000000000..d098b42f9b --- /dev/null +++ b/docs/partials/_views.mdx @@ -0,0 +1,203 @@ +Cypress automatically groups certain URL patterns to create views. However, for URLs that are not automatically grouped (e.g., `/users/alice` and `/users/bob` are not automatically grouped into `/users/*`), the `views` property allows you to specify custom URL patterns to define views. This configuration enhances the clarity and organization of your coverage reports. + +The `groupBy` property of a view definition allows you to create multiple views with a single URL pattern, grouping URLs by the specified named parameter(s). + +## Why use views? + +:::info +**Note:** setting `views` impacts both Accessibility and UI Coverage reports. +Nesting this property under an `accessibility` or `uiCoverage` key is +supported, if you need to split them up. +::: + +- **Group Dynamic URLs**: Group URLs with dynamic path parameters (e.g., `/users/alice` and `/users/bob`) that are not ids or uuids into a single view. +- **Organize by Query Parameters**: Create views based on query parameters to group URLs where query strings are important to the context of the page. + +## Syntax + +```json +{ + "views": [ + { + "pattern": string, + "groupBy": [ + string + ] + } + ] +} +``` + +### Options + +The first pattern that a given URL matches is used as its view. If a URL doesn't match any of the patterns, it is grouped by the default view grouping rules, if possible. + +| Option | Required | Default | Description | +| --------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `pattern` | Required | | A URL pattern to group matching URLs into a single view. Uses [URL Pattern API](https://developer.mozilla.org/en-US/docs/Web/API/URL_Pattern_API) syntax. | +| `groupBy` | Optional | | An array of named URL parameters used to further subdivide the URLs into multiple views within the same pattern. This is useful for dynamic applications where URLs represent different user interactions or data segments. | + +## Examples + +### Grouping dynamic path parameters + +#### Config + +```typescript +{ + "views": [ + { + "pattern": "https://www.my-app.com/users/*" + } + ] +} +``` + +#### Visited URLs + +``` +https://www.my-app.com/users/alice +https://www.my-app.com/users/bob +https://www.my-app.com/users/bob#settings +https://www.my-app.com/users?assigned=true +``` + +#### Views shown in UI + +``` +www.my-app.com/users +www.my-app.com/users/* +``` + +--- + +### Using named path parameters + +#### Config + +```json +{ + "views": [ + { + "pattern": "https://www.my-app.com/users/:name" + } + ] +} +``` + +#### Visited URLs + +``` +https://www.my-app.com/users/alice +https://www.my-app.com/users/bob +https://www.my-app.com/users/bob#settings +https://www.my-app.com/users?assigned=true +``` + +#### Views shown in UI + +``` +www.my-app.com/users +www.my-app.com/users/:name +``` + +--- + +### Group URLs by named parameters + +#### Config + +```json +{ + "views": [ + { + "pattern": "https://www.my-app.com/analytics/:type/:id", + "groupBy": ["type"] + } + ] +} +``` + +#### Visited URLs + +``` +https://www.my-app.com/analytics/performance/amara +https://www.my-app.com/analytics/performance/harper +https://www.my-app.com/analytics/usage/amara +https://www.my-app.com/analytics/usage/harper +``` + +#### Views shown in UI + +``` +www.my-app.com/analytics/performance/:id +www.my-app.com/analytics/usage/:id +``` + +--- + +### Group URLs by named query parameters + +#### Config + +```json +{ + "views": [ + { + "pattern": "https://www.my-app.com/home?*status=:status{&*}?#*", + "groupBy": ["status"] + } + ] +} +``` + +#### Visited URLs + +``` +https://www.my-app.com/home?page=1&status=done +https://www.my-app.com/home?status=done&group=2 +https://www.my-app.com/home?tag=trip&status=new&group=4 +https://www.my-app.com/home?tag=trip&status=new#statusView +``` + +#### Views shown in UI + +``` +www.my-app.com/home?status=done +www.my-app.com/home?status=new +``` + +--- + +### Grouping URLs across subdomains + +#### Config + +```json +{ + "views": [ + { + "pattern": "https://*.my-app.com/:path*", + "groupBy": ["path"] + } + ] +} +``` + +#### Visited URLs + +``` +https://staging1.my-app.com/home +https://staging2.my-app.com/home +https://www.my-app.com/home +https://staging1.my-app.com/profile +https://www.my-app.com/profile/edit +``` + +#### Views shown in UI + +``` +https://*.my-app.com/home +https://*.my-app.com/profile +https://*.my-app.com/profile/edit +``` diff --git a/docs/ui-coverage/configuration/elementfilters.mdx b/docs/ui-coverage/configuration/elementfilters.mdx index 349124c9ef..3f0fc4f454 100644 --- a/docs/ui-coverage/configuration/elementfilters.mdx +++ b/docs/ui-coverage/configuration/elementfilters.mdx @@ -8,210 +8,4 @@ sidebar_label: elementFilters # elementFilters -By default, every interactive and visible element is included in UI Coverage. The `elementFilters` property allows you to specify selectors for elements that should be excluded from these reports. This configuration is particularly useful for removing irrelevant or non-actionable elements to streamline coverage analysis. - -## Why use element filters? - -:::info -**Note:** setting `elementFilters` impacts both Accessibility and UI Coverage -reports if set at the root of the configuration. Nesting this property under an `accessibility` or `uiCoverage` key is -supported, if you need to split them up. -::: - -- **Excluding Irrelevant Elements**: Decorative icons, marketing banners, or tooltips that do not require testing can clutter reports. Use elementFilters to exclude them. -- **Ignoring 3rd Party Components**: Libraries or widgets that are not part of your application logic can be excluded from coverage reports. -- **Streamlining Reports**: Reducing noise by filtering out non-essential elements makes coverage reports more actionable. - -## Syntax - -```json -{ - "elementFilters": [ - { - "selector": string, - "include": boolean - } - ] -} -``` - -### Options - -For every element considered interactive and visible by UI Coverage, the first `elementFilters` rule for which the selector property matches the element is used to either include or exclude the element based on the `include` value. Elements that do not match any rules are included 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. | -| `include` | Optional | `true` | A boolean indicating whether the matched elements should be included in UI Coverage. | - -## Examples - -### Excluding a specific element - -#### Config - -```json -{ - "elementFilters": [ - { - "selector": "#button-2", - "include": false - } - ] -} -``` - -#### HTML - -```xml - - - - -``` - -#### Elements shown in UI Coverage - -``` -#button-1 -``` - ---- - -### Excluding all elements in a container - -#### Config - -```json -{ - "elementFilters": [ - { - "selector": "footer *", - "include": false - } - ] -} -``` - -#### HTML - -```xml - -
- -
- - -``` - -#### Elements shown in UI Coverage - -``` -#start -``` - ---- - -### Including only elements in a specific container - -#### Config - -```json -{ - "elementFilters": [ - { - "selector": "#form *", - "include": true - }, - { - "selector": "*", - "include": false - } - ] -} -``` - -#### HTML - -```xml - -
- -
- - -``` - -#### Elements shown in UI - -``` -#name -``` - ---- - -### Excluding Elements by Attribute - -#### Config - -```json -{ - "elementFilters": [ - { - "selector": "[data-role='decorative']", - "include": false - } - ] -} -``` - -```xml - - - - -``` - -#### Elements shown in UI Coverage - -``` -[data-role="primary"] -``` - -### Excluding dynamic elements by pattern - -#### Config - -```json -{ - "elementFilters": [ - { - "selector": "[class^='auth']", - "include": false - } - ] -} -``` - -#### HTML - -```xml - - - - -``` - -#### Elements shown in UI Coverage - -``` -.cancel -``` + diff --git a/docs/ui-coverage/configuration/viewfilters.mdx b/docs/ui-coverage/configuration/viewfilters.mdx index 7cae39e5f4..37ad9576ec 100644 --- a/docs/ui-coverage/configuration/viewfilters.mdx +++ b/docs/ui-coverage/configuration/viewfilters.mdx @@ -8,140 +8,4 @@ sidebar_label: viewFilters # viewFilters -By default, every URL visited within a test run is included in UI Coverage. However, not all URLs are relevant for your coverage analysis. The `viewFilters` property allows you to specify patterns for URLs that should be excluded, ensuring your coverage reports focus on meaningful parts of your application. Excluding a URL also excludes all links pointing to that URL. - -## Why use view filters? - -:::info -**Note:** setting `viewFilters` impacts both Accessibility and UI Coverage reports. This cannot be nested. -::: - -- **Exclude Third-Party URLs**: If your application integrates with third-party services, you might want to exclude their URLs from coverage analysis. -- **Exclude Admin Pages**: URLs that are not part of the user-facing application, such as admin pages, could be excluded from coverage reports. -- **Reduce Noise**: Certain URLs visited during tests (e.g., error pages or redirects) may not represent meaningful user flows. Exclude these to clean up your reports. -- **Optimize Performance**: Filtering out irrelevant URLs reduces the amount of data processed, speeding up analysis and improving report readability. - -## Syntax - -```json -{ - "viewFilters": [ - { - "pattern": string, - "include": boolean - } - ] -} -``` - -### Options - -For every URL visited and link element found, the first `viewFilters` rule for which the `pattern` matches the URL is used to either include or exclude the URL based on the `include` value. URLs that do not match any rules are included by default. - -| Option | Required | Default | Description | -| --------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------- | -| `pattern` | Required | | A string that matches URLs using [URL Pattern API](https://developer.mozilla.org/en-US/docs/Web/API/URL_Pattern_API) syntax. | -| `include` | Optional | `true` | A boolean that determines whether matching URLs should be included in coverage. | - -## Examples - -### Excluding URLs by hostname - -#### Config - -```json -{ - "viewFilters": [ - { - "pattern": "https://app.okta.com/*", - "include": false - } - ] -} -``` - -#### Visited URLs - -``` -https://app.okta.com/login -https://cypress.io/home -https://cypress.io/about -``` - -#### Views shown in UI Coverage - -``` -https://cypress.io/home -https://cypress.io/about -``` - ---- - -### Including only specific URLs - -#### Config - -```json -{ - "viewFilters": [ - { - "pattern": "https://cypress.io/dashboards*", - "include": true - }, - { - "pattern": "*", - "include": false - } - ] -} -``` - -#### Visited URLs - -``` -https://cypress.io/dashboards -https://cypress.io/dashboards/1 -https://cypress.io/dashboards/2 -https://cypress.io/home -https://cypress.io/login -``` - -#### Views shown in UI - -``` -https://cypress.io/dashboards -https://cypress.io/dashboards/* -``` - -### Excluding error pages - -#### Config - -```json -{ - "viewFilters": [ - { - "pattern": "http*://*/404", - "include": false - }, - { - "pattern": "http*://*/error/*", - "include": false - } - ] -} -``` - -#### Visited URLs - -``` -https://cypress.io/home -https://cypress.io/404 -https://cypress.io/error/500 -``` - -#### Views shown in UI Coverage - -``` -https://cypress.io/home -``` + diff --git a/docs/ui-coverage/configuration/views.mdx b/docs/ui-coverage/configuration/views.mdx index b973bbdfc2..7beada406d 100644 --- a/docs/ui-coverage/configuration/views.mdx +++ b/docs/ui-coverage/configuration/views.mdx @@ -8,206 +8,4 @@ sidebar_label: views # views -UI Coverage automatically groups certain URL patterns to create [views](/ui-coverage/core-concepts/views). However, for URLs that are not automatically grouped (e.g., `/users/alice` and `/users/bob` are not automatically grouped into `/users/*`), the `views` property allows you to specify custom URL patterns to define views. This configuration enhances the clarity and organization of your coverage reports. - -The `groupBy` property of a view definition allows you to create multiple views with a single URL pattern, grouping URLs by the specified named parameter(s). - -## Why use views? - -:::info -**Note:** setting `views` impacts both Accessibility and UI Coverage reports. -Nesting this property under an `accessibility` or `uiCoverage` key is -supported, if you need to split them up. -::: - -- **Group Dynamic URLs**: Group URLs with dynamic path parameters (e.g., `/users/alice` and `/users/bob`) that are not ids or uuids into a single view. -- **Organize by Query Parameters**: Create views based on query parameters to group URLs where query strings are important to the context of the page. - -## Syntax - -```json -{ - "views": [ - { - "pattern": string, - "groupBy": [ - string - ] - } - ] -} -``` - -### Options - -The first pattern that a given URL matches is used as its view. If a URL doesn't match any of the patterns, it is grouped by the default [view grouping rules](/ui-coverage/core-concepts/views), if possible. - -| Option | Required | Default | Description | -| --------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `pattern` | Required | | A URL pattern to group matching URLs into a single view. Uses [URL Pattern API](https://developer.mozilla.org/en-US/docs/Web/API/URL_Pattern_API) syntax. | -| `groupBy` | Optional | | An array of named URL parameters used to further subdivide the URLs into multiple views within the same pattern. This is useful for dynamic applications where URLs represent different user interactions or data segments. | - -## Examples - -### Grouping dynamic path parameters - -#### Config - -```typescript -{ - "views": [ - { - "pattern": "https://www.my-app.com/users/*" - } - ] -} -``` - -#### Visited URLs - -``` -https://www.my-app.com/users/alice -https://www.my-app.com/users/bob -https://www.my-app.com/users/bob#settings -https://www.my-app.com/users?assigned=true -``` - -#### Views shown in UI - -``` -www.my-app.com/users -www.my-app.com/users/* -``` - ---- - -### Using named path parameters - -#### Config - -```json -{ - "views": [ - { - "pattern": "https://www.my-app.com/users/:name" - } - ] -} -``` - -#### Visited URLs - -``` -https://www.my-app.com/users/alice -https://www.my-app.com/users/bob -https://www.my-app.com/users/bob#settings -https://www.my-app.com/users?assigned=true -``` - -#### Views shown in UI - -``` -www.my-app.com/users -www.my-app.com/users/:name -``` - ---- - -### Group URLs by named parameters - -#### Config - -```json -{ - "views": [ - { - "pattern": "https://www.my-app.com/analytics/:type/:id", - "groupBy": ["type"] - } - ] -} -``` - -#### Visited URLs - -``` -https://www.my-app.com/analytics/performance/amara -https://www.my-app.com/analytics/performance/harper -https://www.my-app.com/analytics/usage/amara -https://www.my-app.com/analytics/usage/harper -``` - -#### Views shown in UI - -``` -www.my-app.com/analytics/performance/:id -www.my-app.com/analytics/usage/:id -``` - ---- - -### Group URLs by named query parameters - -#### Config - -```json -{ - "views": [ - { - "pattern": "https://www.my-app.com/home?*status=:status{&*}?#*", - "groupBy": ["status"] - } - ] -} -``` - -#### Visited URLs - -``` -https://www.my-app.com/home?page=1&status=done -https://www.my-app.com/home?status=done&group=2 -https://www.my-app.com/home?tag=trip&status=new&group=4 -https://www.my-app.com/home?tag=trip&status=new#statusView -``` - -#### Views shown in UI - -``` -www.my-app.com/home?status=done -www.my-app.com/home?status=new -``` - ---- - -### Grouping URLs across subdomains - -#### Config - -```json -{ - "views": [ - { - "pattern": "https://*.my-app.com/:path*", - "groupBy": ["path"] - } - ] -} -``` - -#### Visited URLs - -``` -https://staging1.my-app.com/home -https://staging2.my-app.com/home -https://www.my-app.com/home -https://staging1.my-app.com/profile -https://www.my-app.com/profile/edit -``` - -#### Views shown in UI - -``` -https://*.my-app.com/home -https://*.my-app.com/profile -https://*.my-app.com/profile/edit -``` + diff --git a/src/theme/MDXComponents.js b/src/theme/MDXComponents.js index 748ebc3ffe..a8641c3acb 100644 --- a/src/theme/MDXComponents.js +++ b/src/theme/MDXComponents.js @@ -16,6 +16,7 @@ import DocsVideo from "@site/src/components/docs-video"; import DocumentDomainWorkaround from "@site/docs/partials/_document-domain-workaround.mdx"; import E2EOnlyBadge from "@site/src/components/e2e-only-badge"; import E2EOrCtTabs from "@site/src/components/e2e-or-ct-tabs"; +import ElementFilters from "@site/docs/partials/_elementfilters.mdx"; import VueSyntaxTabs from "@site/src/components/vue-syntax-tabs"; import HeaderAssertions from "@site/docs/partials/_header-assertions.mdx"; import HeaderRequirements from "@site/docs/partials/_header-requirements.mdx"; @@ -31,6 +32,8 @@ import TabItem from "@theme/TabItem"; import ThenShouldAndDifference from "@site/docs/partials/_then-should-and-difference.mdx"; import WarningSetupNodeEvents from "@site/docs/partials/_warning-setup-node-events.mdx"; import VideoRecordingSupportedBrowsers from "@site/docs/partials/_video-recording-supported-browsers.mdx" +import ViewFilters from "@site/docs/partials/_viewfilters.mdx"; +import Views from "@site/docs/partials/_views.mdx"; import LineBreak from "@site/src/components/line-break"; import Logo from "@site/src/components/logo"; import CloudFreePlan from "@site/docs/partials/_cloud_free_plan.mdx"; @@ -170,6 +173,7 @@ export default { DocumentDomainWorkaround, E2EOnlyBadge, E2EOrCtTabs, + ElementFilters, VueSyntaxTabs, HeaderAssertions, HeaderRequirements, @@ -186,6 +190,8 @@ export default { ThenShouldAndDifference, WarningSetupNodeEvents, VideoRecordingSupportedBrowsers, + ViewFilters, + Views, Logo, LineBreak, CloudFreePlan,