Git

When Percy generates screenshots, it organizes the screenshots into snapshots, and the snapshots into a build. Subsequently, new screenshots undergo comparison with baseline screenshots from a prior build.

By default, Percy uses “master” as the default base branch. You can configure a branch to serve as the default base for comparisons. If your Git project’s main branch has a different name, it’s important to update your Percy settings to match. This ensures smooth integration and accurate visual reviews. Configuring the default base branch ensures that all subsequent branches derive their baseline for comparisons from the specified default base branch.

If the default branch is not set as ‘master’ and no branch is specified, Percy comparisons are not possible in that scenario.

Setting the projects default base branch

If git projects default branch is different from master, you will want to update your projects settings to mirror that. By default, uses master as the default branch, but it’s not uncommon for teams to use a branch like develop as the main development branch.

To update this setting, you will need to go to your projects settings page. Once you’re on the settings page, look for a “Default base branch” heading under “Project Details”and update the “Default base branch” input.

Overriding the default base branch

Sometimes you will want to override the default baseline for certain builds. To do this, you will need to set a PERCY_TARGET_BRANCH environment variable. The value of PERCY_TARGET_BRANCH will be the branch that has a build which you want to use as a baseline.

For example, if you want to compare your current checked out branch to the staging branch, you would set to PERCY_TARGET_BRANCH=staging. That will use the last build on staging as the baseline to generate comparisons.

Note that if you have an SCM integration, PERCY_TARGET_BRANCH will only be used for builds NOT associated with a pull request. A pull request’s target branch will take priority over the branch specified by PERCY_TARGET_BRANCH. To override a base build set with a PR, you will also need to set PERCY_TARGET_COMMIT to a specific commit SHA.

Overriding the default base commit

If you want to specify a specific commit to be used to selecting the base build, you can set the PERCY_TARGET_COMMIT environment variable to the full commit SHA. This will only work if there is a finished build for that commit.

Auto-approve branches in Percy refer to a feature that enables builds generated on specific branches in a version control system to skip manual approval and automatically pass visual reviews in Percy.

When you designate a branch for auto approval, builds on these branches automatically become “auto-approved” regardless of changes detected. This eliminates manual intervention, resulting in fewer false positives and saving time.

Approval required branches typically refer to branches where changes must be approved before they can be merged into another branch. Configuring the “Approval required branches” option means that builds on these branches will exclusively use the most recently approved build within the specified branch as their baseline. Once this configuration is in place, Percy’s intelligent base build selection logic will be disabled on these branches.

This setting should only be used in special circumstances, such as for isolated branches used by a QA team who has a test suite in a disconnected repository.

You can set approved snapshots as the baseline by utilizing the “Approval required branches” setting

Base snapshot selection

Percy’s snapshot-based approval feature enables you to review and make decisions on the visual changes detected in your application. By comparing the before and after snapshots in a build, you can validate and approve individual snapshots or the build as a whole. This means you can either approve or reject changes on a granular level, evaluating each snapshot separately, or choose to approve all the snapshots in the build collectively. This flexibility gives you control over the approval process, ensuring that only the desired and intentional visual changes are accepted.

This approach is particularly beneficial for branches that are dedicated to Quality Assurance (QA) activities. Such isolated branches provide a dedicated environment for QA teams to conduct their testing activities without interfering with ongoing development work. It enables them to perform thorough and comprehensive testing without the risk of impacting the main development branch.

By using the snapshot-based approval feature, QA teams can meticulously review and validate visual changes introduced in a specific branch or environment.

Set approved snapshots as baseline

To set approved snapshots as the baseline for comparison:

1. Login to Percy & navigate to your created Percy project.
2. Go to Project Settings » Advanced Options» Approval required branches.
3. In the Approval required branches field, specify the name of your testing branch. If you work with multiple branches, specify multiple branches with space and use a “*” as a wildcard match.

These branches are subject to a formal approval process before changes can become baseline for future builds.

Check more details about how do build and snapshot approvals work

The following workflow outlines Percy’s systematic approach to reviewing and approving changes, encompassing both the evaluation of the entire set of snapshots at the overall build level, the individual approval of each snapshot, and the decision-making process for new and missing snapshots.

Build approval workflow

Percy offers two approaches to capture and compare visual snapshots: Normal builds and partial builds.

A normal build involves rendering and capturing the entire application or page as a visual snapshot, encompassing all elements and components present in the interface, whereas a partial build focuses on rendering and capturing specific elements or components of the application’s interface as visual snapshots.

Based on the build type, Percy follows the below workflow:

• Normal Build: If a normal build is approved, it becomes the base build for subsequent builds. However, if it is not approved, it cannot serve as the base build but any approved snapshots within the build can still become the base snapshots for future builds.
• Partial Build: If a partial build is detected, it cannot be designated as the base build. However, approved snapshots from the partial build can still be considered as base snapshots. Note that in the case of partial builds, missing snapshots will not trigger notifications. For more information, see Partial builds.

Snapshot approval workflow

For Snapshot approval, Percy checks if the approved version of each snapshot is available on the same branch. If it is, Percy compares the snapshots to see if there are any differences. If yes, the user is asked to review the snapshot and decide whether to approve or request changes. If there are no differences, the snapshots are automatically approved.

On the other hand, if the approved version of a snapshot is not present on the branch, Percy treats the snapshot in the current build as a new snapshot and notifies the same.

Snapshot is missing in the build

If a snapshot is not found in the current build, Percy verifies whether the snapshot exists in the base build. If it is present in the base build, Percy notifies the user that the snapshot is missing. However, if the snapshot is not found in the base build, the workflow comes to an end.

Working with approval required branches - An example

1. Let’s consider a scenario where a user has generated the first build, called Build 1, which has been approved.
   1. Build 1 consists of three snapshots, namely A, B, and C.
   2. Since the build is in an approved state, all the snapshots within this build are also considered approved.
2. Now, the user proceeds to generate the second build, known as Build 2. Build 2 includes snapshots A, B, and D.
   1. At this point, Percy will perform a snapshot-level comparison between snapshots A and B from Build 1, as these snapshots were approved in the previous build.
   2. Also, during the comparison, Percy will notify that snapshot C is missing in Build 2, and it will recognize snapshot D as a new snapshot in this build.
   3. There are two possible outcomes of this comparison. First, if snapshot D is approved and there are no differences found between snapshots A and B, then Build 2 is considered approved. On the other hand, if snapshot D is either approved or unapproved and there are differences detected between snapshots A and B, then Build 2 is not approved and cannot serve as the baseline.
3. Let’s break down the scenario where a user introduces a third build, Build 3, with snapshots A, C, and D. The next comparison depends on whether Build 2 is approved or not.
   1. If Build 2 is not approved, then snapshots A and C are compared with the snapshots from Build 1.
   2. In this case, snapshot B from Build 1 will be notified as missing, and if snapshot D was approved in Build 2, it will be compared; otherwise, it will be notified as new snapshot.
4. Moving forward, the user introduces Build 4, which is marked as a partial build, containing only snapshot A.
   1. In this case, Build 4 won’t complain for missing snapshot, and if this build is approved than only that snapshot A will be approved. However, now Build 4 cannot become a base build.
5. Next, the user generates Build 5, with snapshots A, B, C and D and all snapshots in this build are approved, hence Build 5 now becomes the base build.

The process of comparison continues in a similar manner for further builds.

Identifying Whether a Snapshot is Not Derived from the Base Build

Check the below example of Percy’s build, where in the left panel, Build 22 is specified as the baseline build, but during the comparison, it takes the base snapshot from Build 28. This means that this particular snapshot present in Build 28 is being used as the baseline for comparison instead of the snapshot from base Build 22.