{ "doc": { "id": "accessibility/configuration/views", "title": "views: group URLs with URL patterns in Cypress Accessibility", "description": "The views configuration groups related URLs into a single view in Cypress Accessibility using URL patterns, so accessibility reports and scores are organized around the real pages of your application instead of the shape of your test data.", "section": "accessibility", "source_path": "/llm/markdown/accessibility/configuration/views.md", "version": "fbc9225067c51c52ee13224e3b702cf8a025ec12", "updated_at": "2026-08-14T12:36:26.878Z", "headings": [ { "id": "accessibility/configuration/views#group-name-views-views", "text": "Group & name views - views", "level": 1 }, { "id": "accessibility/configuration/views#why-use-views", "text": "Why use views?", "level": 2 }, { "id": "accessibility/configuration/views#scope", "text": "Scope", "level": 2 }, { "id": "accessibility/configuration/views#syntax", "text": "Syntax", "level": 2 }, { "id": "accessibility/configuration/views#options", "text": "Options", "level": 3 }, { "id": "accessibility/configuration/views#how-are-urls-matched-to-views", "text": "How are URLs matched to views?", "level": 2 }, { "id": "accessibility/configuration/views#using-groupby", "text": "Using groupBy", "level": 2 }, { "id": "accessibility/configuration/views#how-views-are-named", "text": "How views are named", "level": 2 }, { "id": "accessibility/configuration/views#examples", "text": "Examples", "level": 2 }, { "id": "accessibility/configuration/views#grouping-dynamic-path-parameters", "text": "Grouping dynamic path parameters", "level": 3 }, { "id": "accessibility/configuration/views#config", "text": "Config", "level": 4 }, { "id": "accessibility/configuration/views#visited-urls", "text": "Visited URLs", "level": 4 }, { "id": "accessibility/configuration/views#views-shown-in-ui", "text": "Views shown in UI", "level": 4 }, { "id": "accessibility/configuration/views#grouping-with-a-named-path-parameter", "text": "Grouping with a named path parameter", "level": 3 }, { "id": "accessibility/configuration/views#config", "text": "Config", "level": 4 }, { "id": "accessibility/configuration/views#visited-urls", "text": "Visited URLs", "level": 4 }, { "id": "accessibility/configuration/views#views-shown-in-ui", "text": "Views shown in UI", "level": 4 }, { "id": "accessibility/configuration/views#grouping-by-a-path-parameter", "text": "Grouping by a path parameter", "level": 3 }, { "id": "accessibility/configuration/views#config", "text": "Config", "level": 4 }, { "id": "accessibility/configuration/views#visited-urls", "text": "Visited URLs", "level": 4 }, { "id": "accessibility/configuration/views#views-shown-in-ui", "text": "Views shown in UI", "level": 4 }, { "id": "accessibility/configuration/views#grouping-by-a-query-parameter", "text": "Grouping by a query parameter", "level": 3 }, { "id": "accessibility/configuration/views#config", "text": "Config", "level": 4 }, { "id": "accessibility/configuration/views#visited-urls", "text": "Visited URLs", "level": 4 }, { "id": "accessibility/configuration/views#views-shown-in-ui", "text": "Views shown in UI", "level": 4 }, { "id": "accessibility/configuration/views#grouping-urls-across-subdomains", "text": "Grouping URLs across subdomains", "level": 3 }, { "id": "accessibility/configuration/views#config", "text": "Config", "level": 4 }, { "id": "accessibility/configuration/views#visited-urls", "text": "Visited URLs", "level": 4 }, { "id": "accessibility/configuration/views#views-shown-in-ui", "text": "Views shown in UI", "level": 4 }, { "id": "accessibility/configuration/views#troubleshooting", "text": "Troubleshooting", "level": 2 }, { "id": "accessibility/configuration/views#a-pattern-you-configured-doesnt-appear-in-the-report", "text": "A pattern you configured doesn't appear in the report", "level": 3 }, { "id": "accessibility/configuration/views#error-value-was-not-found-in-the-pattern", "text": "Error: Value \"...\" was not found in the pattern", "level": 3 }, { "id": "accessibility/configuration/views#error-no-duplicate-values-allowed-was-added-multiple-times", "text": "Error: No duplicate values allowed - \"...\" was added multiple times", "level": 3 }, { "id": "accessibility/configuration/views#see-also", "text": "See also", "level": 2 } ] }, "content": { "type": "root", "children": [ { "type": "heading", "depth": 1, "children": [ { "type": "text", "value": "Group & name views - `views`" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Cypress Accessibility organizes every report around views, the distinct pages and components of your application. Each view collects the " }, { "type": "link", "title": null, "url": "/llm/markdown/accessibility/guides/run-level-reports.md#Snapshots", "children": [ { "type": "text", "value": "snapshots" } ] }, { "type": "text", "value": " captured on that page and reports the accessibility violations found there, so you review, score, and track each part of your app as a unit." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "The `views` configuration controls that grouping. Without it, URLs that differ only by a username, slug, or other non-numeric value each become their own view, so a single violation on a shared page template is reported once per URL and one issue is split across many rows. A `views` pattern rolls those URLs into one view, so you triage the violation once for the whole page and your report reflects the structure of your application, not the shape of your test data." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "The reference below covers the full `views` syntax, including how URLs are matched, the `groupBy` option, and worked examples." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "The `views` configuration groups the URLs your tests visit into views using URL patterns. Views are the distinct pages of your application that your reports are organized around. URLs that differ only by numeric IDs or UUIDs are grouped automatically (`/users/123` and `/users/456` become a single `/users/*` view), but other dynamic values are not: `/users/alice` and `/users/bob` appear as two separate views unless a `views` pattern groups them." } ] }, { "type": "heading", "depth": 2, "children": [ { "type": "text", "value": "Why use views?" } ] }, { "type": "list", "ordered": false, "start": null, "spread": false, "children": [ { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "Group dynamic URLs: Combine URLs with dynamic values that the automatic rules don't recognize, such as usernames or slugs, into a single view." } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "Split views by query parameters: By default, query strings are ignored when views are created, so `/home?status=done` and `/home?status=new` group into a single `/home` view. A pattern that captures a query parameter lets you report on them separately." } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "Create distinct view groups: Use `groupBy` to create a separate view for each value of a meaningful URL parameter, while still grouping the parts that are dynamic." } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "Consolidate environments: Patterns can span subdomains, or omit the protocol and hostname entirely, so the same page visited on different environments rolls up into one view." } ] } ] } ] }, { "type": "heading", "depth": 2, "children": [ { "type": "text", "value": "Scope" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Note: setting `views` impacts both Accessibility and UI Coverage reports. It is defined at the root of your configuration and, unlike `viewFilters` and `elementFilters`, it cannot be nested under an `accessibility` or `uiCoverage` key to configure each product separately." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "The `views` configuration applies to URLs visited in end-to-end tests. Views for component tests are created from the path of the spec file, and are not affected by this configuration." } ] }, { "type": "heading", "depth": 2, "children": [ { "type": "text", "value": "Syntax" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "App Quality Config" } ] }, { "type": "code", "lang": null, "meta": null, "value": "{ \"views\": [ { \"pattern\": string, \"groupBy\": string | [string], \"comment\": string } ]}" }, { "type": "paragraph", "children": [ { "type": "text", "value": "A view can also be defined as just a pattern string when no other options are needed:" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "App Quality Config" } ] }, { "type": "code", "lang": null, "meta": null, "value": "{ \"views\": [\"https://www.my-app.com/users/*\"]}" }, { "type": "heading", "depth": 3, "children": [ { "type": "text", "value": "Options" } ] }, { "type": "table", "align": [ null, null, null, null ], "children": [ { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "Option" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "Required" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "Default" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "Description" } ] } ] }, { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "`pattern`" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "Required" } ] }, { "type": "tableCell", "children": [] }, { "type": "tableCell", "children": [ { "type": "text", "value": "A URL pattern to group matching URLs into a single view. Uses " }, { "type": "link", "title": null, "url": "https://developer.mozilla.org/en-US/docs/Web/API/URL_Pattern_API", "children": [ { "type": "text", "value": "URL Pattern API" } ] }, { "type": "text", "value": " syntax." } ] } ] }, { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "`groupBy`" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "Optional" } ] }, { "type": "tableCell", "children": [] }, { "type": "tableCell", "children": [ { "type": "text", "value": "One or more named parameters from the pattern that should create separate views. Accepts a single string or an array of strings. Each name must appear in `pattern` as a named parameter (for example, `:type`), in the path, query string, or hash." } ] } ] }, { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "`comment`" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "Optional" } ] }, { "type": "tableCell", "children": [] }, { "type": "tableCell", "children": [ { "type": "text", "value": "A description of the purpose of this view configuration. Has no effect on behavior." } ] } ] } ] }, { "type": "heading", "depth": 2, "children": [ { "type": "text", "value": "How are URLs matched to views?" } ] }, { "type": "list", "ordered": false, "start": null, "spread": false, "children": [ { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "Patterns are evaluated in the order they are defined, and each URL is grouped into the view of the first pattern it matches. A URL only ever belongs to one view." } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "URLs that don't match any pattern are grouped by the " }, { "type": "link", "title": null, "url": "/llm/markdown/ui-coverage/core-concepts/views.md#How-views-are-created", "children": [ { "type": "text", "value": "automatic view grouping rules" } ] }, { "type": "text", "value": ", where possible." } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "A pattern that doesn't match any URLs in the run does not appear in the report." } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "URLs excluded by a `viewFilters` rule are excluded before `views` patterns are applied. A `views` pattern cannot bring an excluded URL back into the report." } ] } ] } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Pattern matching follows " }, { "type": "link", "title": null, "url": "https://developer.mozilla.org/en-US/docs/Web/API/URL_Pattern_API", "children": [ { "type": "text", "value": "URL Pattern API" } ] }, { "type": "text", "value": " semantics, with a few behaviors worth knowing:" } ] }, { "type": "list", "ordered": false, "start": null, "spread": false, "children": [ { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "A pattern that omits the query string and hash matches URLs with any query string or hash. For example, `https://www.my-app.com/users/*` matches `https://www.my-app.com/users/bob#settings`." } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "Trailing slashes are optional by default: `/users/bob` and `/users/bob/` both match a pattern ending in `/users/:name`. If your pattern ends with a `/`, only URLs with a trailing slash match it." } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "A pattern without a protocol and hostname, such as `/users/*`, matches that path on any protocol, hostname, and port." } ] } ] } ] }, { "type": "heading", "depth": 2, "children": [ { "type": "text", "value": "Using groupBy" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "The `groupBy` property creates distinct views based on named parameters in your URL pattern. For example, if your pattern is `/analytics/:type/:id`, using `groupBy: [\"type\"]` creates a separate view for each unique value of `type` (like `/analytics/performance/:id` and `/analytics/usage/:id`)." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "This is particularly useful when:" } ] }, { "type": "list", "ordered": false, "start": null, "spread": false, "children": [ { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "Different parameter values represent distinct functional areas" } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "You want to track coverage separately for different categories of content" } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "URL parameters determine significant UI changes" } ] } ] } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "URLs with the same values for the specified parameters are grouped together, while different values create distinct views. Values can be captured from named parameters in the path, the query string, or the hash of the pattern." } ] }, { "type": "heading", "depth": 2, "children": [ { "type": "text", "value": "How views are named" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "A view created from your configuration is named by the pattern you wrote. When `groupBy` is used, the grouped parameters are replaced with their matched values, and any remaining named parameters and wildcards stay in the name, as the examples below show." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "When every view in a report shares the same protocol and hostname, view names are displayed without them. The examples below show the names as they appear in this most common case." } ] }, { "type": "heading", "depth": 2, "children": [ { "type": "text", "value": "Examples" } ] }, { "type": "heading", "depth": 3, "children": [ { "type": "text", "value": "Grouping dynamic path parameters" } ] }, { "type": "heading", "depth": 4, "children": [ { "type": "text", "value": "Config" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "App Quality Config" } ] }, { "type": "code", "lang": null, "meta": null, "value": "{ \"views\": [ { \"pattern\": \"https://www.my-app.com/users/*\" } ]}" }, { "type": "heading", "depth": 4, "children": [ { "type": "text", "value": "Visited URLs" } ] }, { "type": "code", "lang": null, "meta": null, "value": "https://www.my-app.com/users/alicehttps://www.my-app.com/users/bobhttps://www.my-app.com/users/bob#settingshttps://www.my-app.com/users?assigned=true" }, { "type": "heading", "depth": 4, "children": [ { "type": "text", "value": "Views shown in UI" } ] }, { "type": "code", "lang": null, "meta": null, "value": "/users/*/users" }, { "type": "paragraph", "children": [ { "type": "text", "value": "The first three URLs match the pattern and group into `/users/*`. The last URL doesn't match (its path is `/users`, not `/users/` followed by more), so the automatic grouping rules create a `/users` view for it, with its query string ignored." } ] }, { "type": "thematicBreak" }, { "type": "heading", "depth": 3, "children": [ { "type": "text", "value": "Grouping with a named path parameter" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "A named parameter like `:name` matches a single path segment, just like `*`, but keeps a readable placeholder in the view name and can be referenced by `groupBy`." } ] }, { "type": "heading", "depth": 4, "children": [ { "type": "text", "value": "Config" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "App Quality Config" } ] }, { "type": "code", "lang": null, "meta": null, "value": "{ \"views\": [ { \"pattern\": \"https://www.my-app.com/users/:name\" } ]}" }, { "type": "heading", "depth": 4, "children": [ { "type": "text", "value": "Visited URLs" } ] }, { "type": "code", "lang": null, "meta": null, "value": "https://www.my-app.com/users/alicehttps://www.my-app.com/users/bobhttps://www.my-app.com/users/bob#settingshttps://www.my-app.com/users?assigned=true" }, { "type": "heading", "depth": 4, "children": [ { "type": "text", "value": "Views shown in UI" } ] }, { "type": "code", "lang": null, "meta": null, "value": "/users/:name/users" }, { "type": "thematicBreak" }, { "type": "heading", "depth": 3, "children": [ { "type": "text", "value": "Grouping by a path parameter" } ] }, { "type": "heading", "depth": 4, "children": [ { "type": "text", "value": "Config" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "App Quality Config" } ] }, { "type": "code", "lang": null, "meta": null, "value": "{ \"views\": [ { \"pattern\": \"https://www.my-app.com/analytics/:type/:id\", \"groupBy\": [\"type\"] } ]}" }, { "type": "heading", "depth": 4, "children": [ { "type": "text", "value": "Visited URLs" } ] }, { "type": "code", "lang": null, "meta": null, "value": "https://www.my-app.com/analytics/performance/amarahttps://www.my-app.com/analytics/performance/harperhttps://www.my-app.com/analytics/usage/amarahttps://www.my-app.com/analytics/usage/harper" }, { "type": "heading", "depth": 4, "children": [ { "type": "text", "value": "Views shown in UI" } ] }, { "type": "code", "lang": null, "meta": null, "value": "/analytics/performance/:id/analytics/usage/:id" }, { "type": "thematicBreak" }, { "type": "heading", "depth": 3, "children": [ { "type": "text", "value": "Grouping by a query parameter" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "The `?*status=:status{&*}?` syntax captures the `status` query parameter wherever it appears in the query string, regardless of what other parameters surround it, and `#*` allows any hash." } ] }, { "type": "heading", "depth": 4, "children": [ { "type": "text", "value": "Config" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "App Quality Config" } ] }, { "type": "code", "lang": null, "meta": null, "value": "{ \"views\": [ { \"pattern\": \"https://www.my-app.com/home?*status=:status{&*}?#*\", \"groupBy\": [\"status\"] } ]}" }, { "type": "heading", "depth": 4, "children": [ { "type": "text", "value": "Visited URLs" } ] }, { "type": "code", "lang": null, "meta": null, "value": "https://www.my-app.com/home?page=1&status=donehttps://www.my-app.com/home?status=done&group=2https://www.my-app.com/home?tag=trip&status=new&group=4https://www.my-app.com/home?tag=trip&status=new#statusView" }, { "type": "heading", "depth": 4, "children": [ { "type": "text", "value": "Views shown in UI" } ] }, { "type": "code", "lang": null, "meta": null, "value": "/home?*status=done{&*}?/home?*status=new{&*}?" }, { "type": "paragraph", "children": [ { "type": "text", "value": "View names keep the query string portion of the pattern as you wrote it, with the grouped parameter replaced by its matched values." } ] }, { "type": "thematicBreak" }, { "type": "heading", "depth": 3, "children": [ { "type": "text", "value": "Grouping URLs across subdomains" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Each unique value of `:path*` creates a view, and the same path visited on different subdomains is grouped into a single view. All of the views share the `*.my-app.com` hostname pattern, so it is omitted from the view names." } ] }, { "type": "heading", "depth": 4, "children": [ { "type": "text", "value": "Config" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "App Quality Config" } ] }, { "type": "code", "lang": null, "meta": null, "value": "{ \"views\": [ { \"pattern\": \"https://*.my-app.com/:path*\", \"groupBy\": [\"path\"] } ]}" }, { "type": "heading", "depth": 4, "children": [ { "type": "text", "value": "Visited URLs" } ] }, { "type": "code", "lang": null, "meta": null, "value": "https://staging1.my-app.com/homehttps://staging2.my-app.com/homehttps://www.my-app.com/homehttps://staging1.my-app.com/profilehttps://www.my-app.com/profile/edit" }, { "type": "heading", "depth": 4, "children": [ { "type": "text", "value": "Views shown in UI" } ] }, { "type": "code", "lang": null, "meta": null, "value": "/home/profile/profile/edit" }, { "type": "heading", "depth": 2, "children": [ { "type": "text", "value": "Troubleshooting" } ] }, { "type": "heading", "depth": 3, "children": [ { "type": "text", "value": "A pattern you configured doesn't appear in the report" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "A pattern that doesn't match any URLs in the run is dropped from the report. Confirm that the pattern matches the full URL, including the protocol and hostname, or omit them so the pattern matches any origin. Also check that a `viewFilters` rule isn't excluding the URLs before `views` patterns are applied." } ] }, { "type": "heading", "depth": 3, "children": [ { "type": "text", "value": "Error: `Value \"...\" was not found in the pattern`" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Each name in `groupBy` must appear in `pattern` as a named parameter. For example, `groupBy: [\"type\"]` requires `:type` somewhere in the pattern's path, query string, or hash." } ] }, { "type": "heading", "depth": 3, "children": [ { "type": "text", "value": "Error: `No duplicate values allowed - \"...\" was added multiple times`" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Each pattern in `views` must be unique. Named parameters are compared as wildcards, so `/users/:name` and `/users/*` count as the same pattern and trigger this error." } ] }, { "type": "heading", "depth": 2, "children": [ { "type": "text", "value": "See also" } ] }, { "type": "list", "ordered": false, "start": null, "spread": false, "children": [ { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "link", "title": null, "url": "/llm/markdown/accessibility/guides/run-level-reports.md#Views", "children": [ { "type": "text", "value": "Views in accessibility reports" } ] }, { "type": "text", "value": ": how views organize your report and per-view score" } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "link", "title": null, "url": "/llm/markdown/accessibility/configuration/viewfilters.md", "children": [ { "type": "text", "value": "`viewFilters` configuration" } ] }, { "type": "text", "value": ": exclude URLs from your reports instead of grouping them" } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "link", "title": null, "url": "/llm/markdown/accessibility/configuration/overview.md", "children": [ { "type": "text", "value": "Configuration overview" } ] }, { "type": "text", "value": ": how to set configuration for your project" } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "link", "title": null, "url": "/llm/markdown/accessibility/faq.md#Grouping-and-naming-views", "children": [ { "type": "text", "value": "Cypress Accessibility FAQ" } ] }, { "type": "text", "value": ": common questions about grouping and naming views" } ] } ] } ] } ] }, "token_estimate": 1985 }