Configure custom browser tag

Configure custom browser names (tags) in Percy on Automate to group and compare snapshots across browsers, OS versions, and devices.

Custom browser tags identify a platform capability used for Percy on Automate snapshots with a single, consistent tag. When you apply the same tag to different platform capabilities, Percy compares snapshots captured from those capabilities using the same tag.

Use custom browser tags as a configuration-level setting to control how Percy compares visual tests across different platforms using the same tag name.

Requirements

Ensure you have the following before configuring custom browser tags:

• Percy CLI version: 1.31.6 or later
• Platform: Percy on Automate (POA)

How custom browser tags work

Percy uses the custom browser name you define as the primary identifier for a platform capability. When two different capabilities share the same custom browser tag, Percy uses that identifier to compare snapshots across different OS, OS versions, browser names, or browser versions.

This approach helps you maintain stable baselines while continuing to test across updated platforms and environments.

Configure custom browser tags

You can configure custom browser tags in your .percy.yml file using the platforms array under the percy section.

Each platform entry supports a custom browser name that Percy uses for snapshot grouping and comparison.

Percy evaluates platform configurations in the order they appear in your .percy.yml file. If multiple entries match a snapshot, the first matching entry is used to apply the custom browser tag.

Supported configuration options

The following properties are available when defining platforms in your .percy.yml configuration file:

What you can do with custom browser tags?

By keeping the same custom browser tag across builds, you can compare snapshots even when platform capabilities change.

Compare browser versions

Compare multiple versions of the same browser, such as Chrome 137 and Chrome latest, using a single custom browser name.

In all scenarios, both builds must use the same custom browser tag for Percy to compare snapshots.

Best practices

• Use browserVersion: "latest" to keep baselines stable across browser updates.
• Define one platform configuration per browser and OS combination unless you need version-specific comparisons.
• Keep custom browser tag names consistent and descriptive.
• Validate your .percy.yml configuration in a test environment before using it broadly.

Things to keep in mind

• Percy applies a custom browser tag only when the platform configuration matches the running test environment.
• For iOS and Android platforms, you must specify a deviceName to apply a custom browser tag.