Cypress AccessibilityPremium Solution

Group & name views - views

Cypress Accessibility organizes every report around views, the distinct pages and components of your application. Each view collects the snapshots 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.

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.

The reference below covers the full views syntax, including how URLs are matched, the groupBy option, and worked examples.

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.

Why use views?

• Group dynamic URLs: Combine URLs with dynamic values that the automatic rules don't recognize, such as usernames or slugs, into a single view.
• 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.
• 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.
• 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.

Scope

info

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.

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.

Syntax

App Quality Config

{
  "views": [
    {
      "pattern": string,
      "groupBy": string | [string],
      "comment": string
    }
  ]
}

A view can also be defined as just a pattern string when no other options are needed:

App Quality Config

{
  "views": ["https://www.my-app.com/users/*"]
}

Options

Option	Required	Default	Description
pattern	Required		A URL pattern to group matching URLs into a single view. Uses URL Pattern API syntax.
groupBy	Optional		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.
comment	Optional		A description of the purpose of this view configuration. Has no effect on behavior.

How are URLs matched to views?

• 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.
• URLs that don't match any pattern are grouped by the automatic view grouping rules, where possible.
• A pattern that doesn't match any URLs in the run does not appear in the report.
• 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.

Pattern matching follows URL Pattern API semantics, with a few behaviors worth knowing:

• 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.
• 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.
• A pattern without a protocol and hostname, such as /users/*, matches that path on any protocol, hostname, and port.

Using groupBy

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).

This is particularly useful when:

• Different parameter values represent distinct functional areas
• You want to track coverage separately for different categories of content
• URL parameters determine significant UI changes

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.

How views are named

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.

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.

Examples

Grouping dynamic path parameters

Config

App Quality Config

{
  "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

/users/*
/users

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.

---

Grouping with a named path parameter

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.

Config

App Quality Config

{
  "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

/users/:name
/users

---

Grouping by a path parameter

Config

App Quality Config

{
  "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

/analytics/performance/:id
/analytics/usage/:id

---

Grouping by a query parameter

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.

Config

App Quality Config

{
  "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

/home?*status=done{&*}?
/home?*status=new{&*}?

View names keep the query string portion of the pattern as you wrote it, with the grouped parameter replaced by its matched values.

---

Grouping URLs across subdomains

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.

Config

App Quality Config

{
  "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

/home
/profile
/profile/edit

Troubleshooting

A pattern you configured doesn't appear in the report

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.

Error: Value "..." was not found in the pattern

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.

Error: No duplicate values allowed - "..." was added multiple times

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.

See also

• Views in accessibility reports: how views organize your report and per-view score
• viewFilters configuration: exclude URLs from your reports instead of grouping them
• Configuration overview: how to set configuration for your project
• Cypress Accessibility FAQ: common questions about grouping and naming views