Skip to main content
Cypress AccessibilityPremium Solution

Override config by run tag - profiles

One Cypress Cloud project usually records many kinds of runs (pull request checks, nightly regression suites, per-team smoke tests), and each kind is best served by a different App Quality configuration. The profiles property lets you keep a single base configuration and layer targeted overrides on top of it. The right override is selected automatically from the run tags you already pass to cypress run, so a pull request run and a full regression run can each get exactly the configuration that makes their report actionable, with no changes to your test code and no second project to maintain.

Before reaching for profiles, consider whether separate Cypress Cloud projects would be simpler. Distinct projects for different applications or teams usually keep reporting and tracking clearer, and are the recommended first choice. Reach for profiles when the runs belong in one project but need different configuration.

Why use profiles?​

  • Tune pull request checks against regression runs: Gate merges with a narrow configuration focused on your most critical flows, so the report a developer sees on a PR is small, fast to act on, and high in "solvability". Keep a wide configuration on the full regression suite to track everything else on a slower cadence.
  • Team-specific reporting: When multiple teams share one project, each team can tag its runs and see a report scoped to the pages or elements it owns, filtering out everyone else's. Nobody has to read around results they don't care about.
  • Purpose-built audit runs: A one-off audit, such as a localization pass, a design-system sweep, or a deep dive on an area you normally exclude, can use configuration you'd never want applied to every run.

How profiles work​

Selecting a profile​

Profiles are selected by matching run tags to profile names. When you record a run with the --tag flag, Cypress Cloud walks the profiles array in order and applies the first profile whose name exactly matches one of the run's tags. Matching is an exact, case-sensitive string comparison: aq-config-regression matches only the tag aq-config-regression, not AQ-Config-Regression or aq-config-regression-nightly. When several tags match different profiles, the first match in the array wins (so list more specific profiles before broader ones), and the order the tags appear on the run makes no difference. If no tag matches, your base configuration is used unchanged.

Profiles are resolved when a run is processed, not when your tests execute. Reprocessing a past run re-applies the profiles and configuration you have saved now, so you can adjust a profile and see its effect on an existing run without recording again.

How a profile changes your configuration​

When a profile applies, its config is laid over your base configuration one setting at a time. Only the settings you include in the profile change; everything else stays exactly as it is in your base configuration. A few things are worth knowing so the result matches what you expect:

  • A setting in a profile fully replaces the base version of that setting. Lists are not combined. If your base configuration has three elementFilters rules and a profile defines its own elementFilters, the profile's rules are used on their own, so copy over any base rules you still want to apply.
  • Anything you leave out of a profile stays the same. You only need to list what's different for that kind of run; the rest is inherited from your base configuration.
  • The accessibility and uiCoverage objects are merged one level deep. Overriding a single setting inside one of them, such as accessibility.significantAttributes, leaves the sibling settings in that object (like accessibility.elementFilters) untouched, so you can adjust one product-specific setting without restating the rest.

What a profile can and can't change​

A profile's config accepts any App Quality configuration setting your base configuration supports: the same viewFilters, elementFilters, views, and product-specific settings you'd set at the root. Two limits are worth knowing:

  • You can't nest a profiles array inside a profile. Profiles live only at the top level of your configuration; one level of overrides is the maximum.
  • There's no switch to skip a run or turn a product off. A profile can only change configuration values. To suppress a report for a certain kind of run, point its profile at a deliberately narrow configuration (for example, viewFilters that exclude every view) so the run produces an empty or tightly scoped report instead.

Best practices​

Use a naming convention like aq-config-* (for example, aq-config-regression, aq-config-pr) so it's obvious that a tag exists for configuration lookup rather than for filtering or grouping runs in Cypress Cloud.

Being explicit this way helps avoid accidentally changing or removing a tag that a profile depends on. Because names are matched exactly against run tags, keep them stable: renaming a profile or changing a tag silently falls back to the base configuration for those runs.

Syntax​

App Quality Config
{
  "profiles": [
    {
      "name": string,
      "config": {
        // Any App Quality configuration options
      },
      "comment": string
    }
  ]
}

Options​

OptionRequiredDescription
nameRequiredIdentifies the profile so a run can select it. Its only purpose is matching: the profile applies when one of the run's tags is an exact, case-sensitive match for this value. It isn't shown in reports or used anywhere else.
configRequiredAn object containing any App Quality configuration options, except a nested profiles array. These values override the root configuration.
commentOptionalA note about why this profile exists, for your team's benefit. Comments appear only in the configuration itself. They have no effect on behavior and are not displayed in reports.

Examples​

Each example shows the App Quality configuration and the cypress run command that selects the profile. Anything a profile doesn't mention is inherited from your base configuration.

Scope a pull request gate to critical flows​

The highest-value use of profiles in Cypress Accessibility is a fast, focused gate for pull requests. Your base configuration scans every view so regression runs track accessibility everywhere. A pull request run doesn't need that breadth; it needs a small, unambiguous report a developer can act on before merging. The aq-config-pr profile keeps only your most critical flows with viewFilters, so the pull request report covers login and checkout and nothing else.

Config​

App Quality Config
{
  "profiles": [
    {
      "name": "aq-config-pr",
      "comment": "Pull request gate: report only on the flows that block a merge",
      "config": {
        "viewFilters": [
          { "pattern": "/login", "include": true },
          { "pattern": "/checkout/*", "include": true },
          {
            "pattern": "*",
            "include": false,
            "comment": "Ignore every other view on pull request runs"
          }
        ]
      }
    }
  ]
}

Usage​

Tag pull request runs so they pick up the profile:

cypress run --record --tag "aq-config-pr"

viewFilters applies the first matching rule, so the two include: true rules keep login and checkout while the catch-all excludes everything else. Regression runs record without this tag and use the base configuration, scanning every view. Pair the narrow report with the Results API to fail the build when a critical flow regresses.

Re-include a widget for a dedicated audit​

Your base configuration excludes two third-party widgets with elementFilters, a cookie banner and an embedded support chat, because another vendor owns them and their violations only add noise. One suite exists specifically to audit the support-chat integration's accessibility, recorded under the aq-config-support-audit tag. For that run, the chat widget should be scanned while the cookie banner stays excluded.

Config​

App Quality Config
{
  "elementFilters": [
    {
      "selector": "#onetrust-banner-sdk, #onetrust-banner-sdk *",
      "include": false,
      "comment": "Third-party cookie banner, reported upstream to the vendor"
    },
    {
      "selector": "#support-chat, #support-chat *",
      "include": false,
      "comment": "Vendor support-chat widget, excluded from everyday reports"
    }
  ],
  "profiles": [
    {
      "name": "aq-config-support-audit",
      "config": {
        "elementFilters": [
          {
            "selector": "#onetrust-banner-sdk, #onetrust-banner-sdk *",
            "include": false,
            "comment": "Still exclude the cookie banner during the support-chat audit"
          }
        ]
      }
    }
  ]
}

Usage​

cypress run --record --tag "aq-config-support-audit"

A profile's elementFilters replaces the base list rather than adding to it, so the profile repeats the cookie-banner rule it still needs and simply omits the support-chat rule. In Cypress Accessibility an element is scanned unless an include: false rule matches it, so dropping the support-chat exclusion is all it takes to bring the widget back into this run's report; you don't add an include: true rule. On every other run, both widgets stay excluded.

Apply an accessibility-only override for a labels audit​

Profiles can override configuration nested under an accessibility key, and those objects merge one level deep, so a profile can replace a single accessibility setting while inheriting the rest. Here the base configuration identifies violation targets by their components context for everyday reports. A quarterly audit of accessible names, tagged aq-config-label-audit, wants each violation target shown by its aria-label instead, using significantAttributes, so a reviewer can spot a vague label like aria-label="button" at a glance. The audit keeps the same component context.

Config​

App Quality Config
{
  "accessibility": {
    "components": {
      "componentAttributes": [
        { "attributeName": "data-component-name", "includeInSelector": true }
      ]
    },
    "significantAttributes": ["data-cy"]
  },
  "profiles": [
    {
      "name": "aq-config-label-audit",
      "config": {
        "accessibility": {
          "significantAttributes": ["aria-label"]
        }
      }
    }
  ]
}

Usage​

cypress run --record --tag "aq-config-label-audit"

Inside accessibility, the profile replaces only significantAttributes; the sibling components object is inherited, so violation targets still carry their component context and are now identified by their label text. On every other run, elements are identified by data-cy as usual.

Choose between profiles when several tags match​

Two teams share one Cypress Cloud project, and each has a profile that scopes the accessibility report to the views it owns with viewFilters. A shared nightly job is tagged for both teams, so both profiles match and the array order decides which one applies.

Config​

App Quality Config
{
  "profiles": [
    {
      "name": "aq-config-team-checkout",
      "config": {
        "viewFilters": [
          { "pattern": "/checkout/*", "include": true },
          {
            "pattern": "*",
            "include": false,
            "comment": "Checkout team: report only on checkout views"
          }
        ]
      }
    },
    {
      "name": "aq-config-team-account",
      "config": {
        "viewFilters": [
          { "pattern": "/account/*", "include": true },
          {
            "pattern": "*",
            "include": false,
            "comment": "Account team: report only on account views"
          }
        ]
      }
    }
  ]
}

Usage​

cypress run --record --tag "aq-config-team-account,aq-config-team-checkout"

The nightly run gets aq-config-team-checkout, the first of the two in the array, rather than aq-config-team-account, even though its tag is listed first on the command line. Reorder the profiles array to hand the shared run to the other team.

Confirm which profile a run used​

After you tag and record a run, check which configuration was actually applied so you know the profile took effect. Every run permanently records its resolved configuration: your base configuration with any matching profile already merged in.

  • In Cypress Cloud, open the run's Properties tab to see the exact configuration that was applied.
  • In CI, read it from the Accessibility Results API, where config.value is the applied App Quality configuration and config.updatedAt is when it was last saved.

If the applied configuration matches your base rather than the profile you expected, the tag didn't select the profile; see Troubleshooting. For more on reading a run's configuration, see Viewing configuration for a run.

Troubleshooting​

A profile you tagged wasn't applied​

  • The run's tag doesn't exactly match the profile name. Matching is case-sensitive and exact.
  • The tag never reached Cypress Cloud. A run recorded without --record, or without that --tag, uses the base configuration.
  • Another profile earlier in the array also matches one of the run's tags and wins. Reorder the array to change precedence.
  • The report was processed before you saved the configuration. Regenerate the run to apply your current profiles. See Setting configuration.

See also​

Contents