Percy Developer Hub

Welcome to the Percy Developer Hub. You'll find comprehensive guides and documentation to help you start working with Percy as quickly as possible, as well as support if you get stuck. Let's jump right in!

Base build selection

Visual testing workflow and base build selection logic

When you push changes to your codebase, Percy generates snapshots and compares them to snapshots generated from a previous build. This previous build is also known as the base build, and this page documents how Percy determines what build to use when generating comparisons.

Why did Percy choose a particular base build?

Percy uses a variety of strategies to determine the optimal base build for comparison on every build you create. The particular strategy used depends on several factors, including any installed SCM integrations, the default branch of the project, and which commits have previously finished builds.

The chart below demonstrates a simplified view of Percy's base build selection logic. Click the thumbnail below to view the full-size diagram.

(a) Is the build attached to a pull request?
(c) Is there a merge base commit present, and a Percy build for the merge base commit?
If your project has an active source control management integration, like GitHub or GitLab, then Percy will always try to compare builds created in conjunction with pull (or merge) requests to the base branch for the pull request. This ensures that only the changes relevant to the pull request are visible in the Percy diff. If there have been changes on the base branch (e.g. master) since the pull request was opened, the visual diff will not reflect those changes.

(b) Has Percy attempted to find a build on the "master" branch?
(d) Is there any previous Percy build on this branch?
Percy's fallback behavior, when no merge base commit build is present, is to compare a build to the latest build on the default base branch. This is the "master" branch by default, but you can override it when creating new builds (see "Overriding the default base branch"). If there are no builds present on the default base branch, then Percy will fall back to using any previous build on the same branch as the build's commit.

(e) Has Percy tried every branch strategy?
If Percy has exhausted all the prior options and has not found a viable candidate for the base build, then no base build will be chosen and all snapshots will be treated as new. This generally only happens on the first build for a new project, but can also occur when the default base branch is misconfigured (see "Overriding the default base branch" below).

Why does Percy show changes unrelated to my commits?

In most cases, this is because the base build that you would intuit does not have a Percy build, or in projects with high commit volume, because the Percy build for the expected commit did not finish before the head build was created. In these cases, you can wait until the base build is finished, and issue a rebuild for your head commit.

Why do all of my snapshots show "no previous snapshot"?

This can happen when Percy was unable to find any suitable base for comparison for your build. This generally means that no previous build has completed on either your branch or the default base branch. Percy will never compare the results of one branch to another branch, other than the default base branch or the base branch of a pull request.

Overriding the default base branch

Some projects use a different base or integration branch than master, like develop. If you want to configure the base branch, you can set the PERCY_TARGET_BRANCH environment variable to set the default base branch for your build.

Note that if you have a SCM integration, this will not override the target branch for builds that are attached to pull requests or merge requests. In such cases, the target branch for the pull request will always be used as the base branch, assuming a build is available from that branch.

Overriding the base build selection logic

If you want to completely customize the base build for a Percy comparison, you can set the PERCY_TARGET_COMMIT environment variable to the commit SHA that you would like to use as the base. This will only work if there is a finished Percy build for that commit.