Skip to main content
Cypress AccessibilityPremium Solution

Exclude views - viewFilters

The viewFilters configuration excludes URLs from Cypress Accessibility. By default, every URL your tests visit is included. A viewFilters rule with include: false removes matching URLs before any analysis happens: their snapshots are not scanned for accessibility violations and don't appear in your report. The result is a report and accessibility score that reflect the parts of your application you own and can remediate.

Why use viewFilters?​

  • Exclude third-party pages: Your tests may pass through pages you don't control, such as an OAuth provider's login page or a payment processor's checkout. Violations on those pages aren't yours to fix, so excluding them keeps your report actionable.
  • Exclude pages outside your remediation scope: Remove sections that aren't part of your accessibility goals yet, such as internal admin tools or legacy areas, so your score tracks the pages you're actively improving.
  • Reduce noise: URLs that tests visit incidentally, such as error pages or intermediate redirect URLs, don't represent meaningful user flows. Excluding them keeps reports clean.

To remove individual elements from scans rather than whole pages, use elementFilters instead. To organize URLs into views rather than removing them, use views.

Scope​

info

A root-level viewFilters property applies to both Cypress Accessibility and UI Coverage. To configure Cypress Accessibility separately, nest viewFilters under an accessibility key. A nested viewFilters completely replaces the root-level one for Cypress Accessibility; the two lists are not merged.

Syntax​

App Quality Config
{
  "viewFilters": [
    {
      "pattern": string,
      "include": boolean,
      "comment": string
    }
  ]
}

To add or edit viewFilters, open the App Quality tab in your project settings in Cypress Cloud. After saving, regenerate a recent run to see the effect of your filters without rerunning your tests. See Setting configuration for details.

Options​

OptionRequiredDescription
patternRequiredA URL pattern in URL Pattern API syntax, matched against the full URL.
includeRequiredWhether matching URLs are included (true) or excluded (false). There is no default; every rule must state it explicitly.
commentOptionalA note about why this rule exists, for your team's benefit. Comments have no effect on filtering and appear only where the configuration itself is shown: the App Quality configuration editor and a run's Properties tab.

How are viewFilters rules applied?​

  • Every URL visited during a run is compared against your rules in order. The first rule whose pattern matches decides whether that URL is included or excluded, so place specific rules before broad ones.
  • URLs that match no rule are included by default. To include only specific URLs, list include: true rules for them followed by a catch-all { "pattern": "*", "include": false } rule.

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/admin matches https://www.my-app.com/admin?tab=users.
  • Trailing slashes are optional by default: https://www.my-app.com/admin matches both /admin and /admin/. If your pattern ends with a /, only URLs with a trailing slash match it.
  • A pattern without a protocol and hostname, such as /admin/*, matches that path on any protocol, hostname, and port. This is useful when tests run against multiple environments.
  • A hostname must match exactly unless it contains a wildcard: https://my-app.com/* does not match https://www.my-app.com/home, but https://*.my-app.com/* does.
  • The pattern * on its own matches every URL.

Validation rules​

Cypress Cloud rejects a configuration when:

  • A rule is missing pattern or include.
  • A pattern isn't valid URL Pattern syntax.
  • Two rules have the same pattern. Duplicates can never both apply, because the first matching rule wins.
  • A rule contains a property other than the three listed above.

Examples​

Exclude a third-party page​

Tests that sign in through an external identity provider capture snapshots of its pages, and any violations found there appear in your report even though you can't fix them. One rule removes those pages, while every other URL stays included by default.

Config​

App Quality Config
{
  "viewFilters": [
    {
      "pattern": "https://app.okta.com/*",
      "include": false,
      "comment": "Exclude the Okta login flow"
    }
  ]
}

Visited URLs​

https://app.okta.com/login
https://www.my-app.com/home
https://www.my-app.com/about

Views shown in UI​

https://www.my-app.com/home
https://www.my-app.com/about

Include only your application's URLs​

An allowlist inverts the default. The first rule includes your application, and the catch-all * rule excludes everything else. Rules are applied in order, so the catch-all must come last.

Config​

App Quality Config
{
  "viewFilters": [
    {
      "pattern": "https://www.my-app.com/*",
      "include": true
    },
    {
      "pattern": "*",
      "include": false,
      "comment": "Exclude everything that isn't the app itself"
    }
  ]
}

Visited URLs​

https://www.my-app.com/dashboards
https://www.my-app.com/dashboards/1
https://www.my-app.com/dashboards/2
https://auth.example.com/login
https://checkout.stripe.com/pay

Views shown in UI​

/dashboards
/dashboards/*

The two numbered dashboard URLs group into a single /dashboards/* view through the automatic view creation rules, which apply to included URLs as usual.

Exclude error pages in every environment​

Patterns without a protocol and hostname match on any environment your tests run against, whether that's localhost, a staging domain, or production.

Config​

App Quality Config
{
  "viewFilters": [
    {
      "pattern": "/404",
      "include": false
    },
    {
      "pattern": "/error/*",
      "include": false
    }
  ]
}

Visited URLs​

http://localhost:3000/home
http://localhost:3000/404
https://staging.my-app.com/error/500

Views shown in UI​

http://localhost:3000/home

Exclude URLs from Cypress Accessibility only​

Nesting viewFilters under accessibility applies the rules to Cypress Accessibility alone. Here, a legacy admin area that isn't in remediation scope yet is excluded from accessibility scans while UI Coverage continues to track it.

Config​

App Quality Config
{
  "accessibility": {
    "viewFilters": [
      {
        "pattern": "https://admin.my-app.com/*",
        "include": false,
        "comment": "Legacy admin area, not yet in accessibility remediation scope"
      }
    ]
  }
}

A nested viewFilters replaces any root-level viewFilters for Cypress Accessibility, so include every rule the product needs in the nested list.

Troubleshooting​

A URL you excluded still appears in the report​

  • Rules apply in order, and the first match wins. Check whether an earlier rule with include: true matches the URL.
  • A pattern that starts with a hostname, like my-app.com/admin, is interpreted as a path rather than a hostname and never matches the URLs you intend. Include the protocol, as in https://my-app.com/admin/*, or use the path-only form /admin/*.
  • Hostnames must match exactly. https://my-app.com/* doesn't match URLs on www.my-app.com; add a wildcard such as https://*.my-app.com/* to span subdomains.
  • Reports use the configuration saved at the time they were processed. Regenerate the run to apply your current configuration. See Setting configuration.

Error: Missing include boolean​

Every rule must set include explicitly; there is no default value. Add "include": false to exclude matching URLs, or "include": true to include them.

Error: No duplicate patterns allowed​

Each pattern in viewFilters must be unique. Because the first matching rule wins, a second rule with the same pattern can never apply; remove it or merge the two rules.

See also​

Contents