---
id: ui-coverage/configuration/profiles
title: 'profiles: apply config overrides by run tag'
description: >-
  Use the profiles property to apply UI Coverage configuration overrides based
  on run tags.
section: ui-coverage
source_path: docs/ui-coverage/configuration/profiles.mdx
version: fbc9225067c51c52ee13224e3b702cf8a025ec12
updated_at: '2026-08-14T12:36:26.878Z'
---
# 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](/llm/markdown/app/references/command-line.md#cypress-run-tag-lt-tag-gt) 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`](/llm/markdown/app/references/command-line.md#cypress-run-tag-lt-tag-gt) 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

| Option | Required | Description |
| --- | --- | --- |
| `name` | Required | Identifies 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. |
| `config` | Required | An object containing any App Quality configuration options, except a nested `profiles` array. These values override the root configuration. |
| `comment` | Optional | A 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](/llm/markdown/ui-coverage/core-concepts/views.md) 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 runscypress run --record --tag "aq-config-reporting-audit"# Localization audit runscypress 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](/llm/markdown/ui-coverage/configuration/elementgroups.md) 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

*   [Cypress run `--tag`](/llm/markdown/app/references/command-line.md#cypress-run-tag-lt-tag-gt) is the flag that selects which profile a run uses.
*   [Configuration overview](/llm/markdown/ui-coverage/configuration/overview.md) lists every option a profile's `config` can override and how to regenerate reports after changing configuration.
*   [`viewFilters`](/llm/markdown/ui-coverage/configuration/viewfilters.md) and [`elementFilters`](/llm/markdown/ui-coverage/configuration/elementfilters.md) are common properties to scope a profile's report.
*   [UI Coverage FAQ](/llm/markdown/ui-coverage/faq.md#Profiles) answers common questions about profiles, including merge behavior and tag matching.