Skip to main content
UI CoveragePremium 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​

Basic profile structure​

Your base configuration excludes the support-chat widget, since another team owns it and it just adds noise to most reports. But one suite exists specifically to test the support-chat flow, and it records under the aq-config-support-chat tag. For that run, and only that run, the widget should count toward coverage.

Config​

App Quality Config
{
  "elementFilters": [
    {
      "selector": "#support-chat-widget",
      "include": false,
      "comment": "Exclude the support-chat widget from most reports"
    }
  ],
  "profiles": [
    {
      "name": "aq-config-support-chat",
      "config": {
        "elementFilters": [
          {
            "selector": "#support-chat-widget",
            "include": true,
            "comment": "The support-chat suite tests this widget, so count it here"
          }
        ]
      }
    }
  ]
}

Usage​

Record the support-chat suite with a matching tag:

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

On every other run the widget stays excluded. On the tagged run, the profile's elementFilters replaces the base list, so the include: true rule wins and the widget counts toward coverage. Because a profile's list replaces the base list rather than adding to it, list every rule the run needs, not only the one that changed.

Multiple profiles​

You can define several profiles, each for a different kind of run. Here, two focused audit suites want the same routes broken down into separate views so they can see coverage per value: a reporting audit splits /reports/:type by report type, and a localization audit splits /:locale/account by locale. You wouldn't want either split applied to every run, since it would fragment your normal reports into many low-traffic views, so each views rule is scoped to its own tag.

Config​

App Quality Config
{
  "profiles": [
    {
      "name": "aq-config-reporting-audit",
      "config": {
        "views": [
          {
            "pattern": "/reports/:type",
            "groupBy": ["type"],
            "comment": "One view per report type for the reporting audit"
          }
        ]
      }
    },
    {
      "name": "aq-config-localization-audit",
      "config": {
        "views": [
          {
            "pattern": "/:locale/account",
            "groupBy": ["locale"],
            "comment": "One view per locale for the localization audit"
          }
        ]
      }
    }
  ]
}

Usage​

Use different tags to activate different profiles:

# Reporting audit runs
cypress run --record --tag "aq-config-reporting-audit"

# Localization audit runs
cypress run --record --tag "aq-config-localization-audit"

Profile with nested configuration​

Profiles can override configuration at any level, including configuration specific to Cypress Accessibility or UI Coverage when your project has both products enabled. Because uiCoverage and accessibility merge one level deep, a profile can add or replace a single nested property while inheriting the rest.

Here the base configuration groups every product card into one element group so the repeated cards count once and don't dominate the score. A suite that specifically exercises each card variant, tagged aq-config-card-variants, needs the opposite: the same cards split into separate groups so featured and standard cards are tracked independently. The two groupings can't both be the base configuration, so the difference lives in a profile.

Config​

App Quality Config
{
  "uiCoverage": {
    "attributeFilters": [
      {
        "attribute": "id",
        "value": ":r.*:",
        "include": false,
        "comment": "Ignore React auto-generated IDs so elements stay stable across renders"
      }
    ],
    "elementGroups": [
      {
        "selector": "[data-cy='product-card']",
        "name": "Product card",
        "comment": "Count the repeated product cards as one group"
      }
    ]
  },
  "profiles": [
    {
      "name": "aq-config-card-variants",
      "config": {
        "uiCoverage": {
          "elementGroups": [
            {
              "selector": "[data-cy='product-card'][data-variant='featured']",
              "name": "Featured product card"
            },
            {
              "selector": "[data-cy='product-card'][data-variant='standard']",
              "name": "Standard product card"
            }
          ]
        }
      }
    }
  ]
}

Usage​

cypress run --record --tag "aq-config-card-variants"

Inside uiCoverage, the profile replaces elementGroups with its own two groups while the sibling attributeFilters is inherited; only the keys the profile names are replaced. On every other run, the single "Product card" group still applies.

Profile selection with multiple matching tags​

Two teams share one Cypress Cloud project, and each has a profile that scopes the report to the views they own. A shared nightly job is tagged for both teams. When more than one tag matches a profile name, Cypress Cloud uses the first matching profile in the profiles array, regardless of the order the tags appear on the run.

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"

Both tags match a profile, but Cypress Cloud applies aq-config-team-checkout because it appears first in the profiles array, even though aq-config-team-account is listed first among the tags. The checkout team's report is produced; tag order on the command line doesn't change the outcome.

See also​

Contents