Base Snapshot Selection

Establish approved snapshots as the baseline using the Approval required branches setting

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.

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. Learn more.

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.