👍

Covered in this doc

• Introduction
• Approval types
• Auto-approve branches
• Approval carry forward workflow

Introduction

Percy approval workflow is an important part of the visual review process. By following this guide, you can understand the different approval types and the request change feature provided by Percy, the concept of auto-approved branches, and how Percy effectively handles the approval workflow.

Approval types

Percy provides you granular control over the approval process. You can manage approvals in different ways:

• Approve build
• Approve groups of matching visual changes
• Approve individual snapshots

Note: You can only approve snapshots, and not individual screenshots. This means that you can approve snapshots, which has screenshots captured across all browsers and width combination. However, it is not possible to approve individual screenshots taken on a specific browser for a specific width.

You can request changes if a snapshot is not yet ready for approval. By doing this, the build status will be changed to "Changes requested."

Note: Once all snapshots in a build are approved, the whole build will be approved. If you have a source code integration installed, only marking a complete build as approved will mark your Percy check as "passed."

Auto-approve branches

Auto-approve branches in Percy refer to a feature that enables specific branches in a version control system to skip manual approval and automatically pass visual reviews in Percy. Such branches will always be marked in green color, reducing false positives and saving your team time.

Note:

• By default commits on "main" branch are marked as auto-approve branch.
• This project setting enables teams to filter and auto-approve specific branches via regex.

How approvals are carried forward

Approved snapshots that were previously accepted will retain their approval status across builds throughout the lifespan of the branch. Essentially, identical snapshots will only require approval once per branch, as they are "carried forward." For further information, refer to base build selection logic.

Note: This is only applicable for multi-branch or Git style workflow. If you are working on approval required branches workflow, you can refer to our Base snapshots selection.

An example

Scenario 1: Snapshot exists in the main branch

Percy always compares first with the main branch, if there are differences, then it will check if the same differences were approved in the immediate previous build in same branch.

1. Let's consider a scenario in which you have a snapshot A in the main branch. The snapshot has a button which is blue in color.
2. Create a feature branch (F1) from the main branch.
3. Create Build 1 in F1. In this build, the color of button in snapshot A is changed from blue to green. In this case the build gets compared with the base build in the main branch and you approve the changes in Build.
   1. Pre state - 1 Changed, 1 Unreviewed, and 0: Approved.
   2. Post state - 1 Changed, 0 Unreviewed, and 1: Approved.
4. Next, create another build Build 2, in F1 . The snapshot in Build 2 remains exactly the same as the one in Build 1. In this case, the approval from Build 1 is carried forward to Build 2.
   1. Pre state - 1 Changed, 0 Unreviewed, and 1: Approved.
   2. Post state - 1 Changed, 0 Unreviewed, and 1: Approved.
5. Now, let's say you create another build, Build 3 in which the button color changes from green to red. This snapshot has a change that is not approved in Build 2 in F1 and in the base build in the main branch. In this case, the approval is not carried forward.
6. Now, a user requests changes in Build 3 to change the color red.
   1. Pre state - 1 Changed, 1 Unreviewed, and 0: Approved.
   2. Post state - 1 Changed, 1 Changed Requested, and 1: Approved.
7. In the next build Build 4, the user changes the color from red to green, so the new Build 4 is submitted for review again. In this case also, the approval is not carried forward.
   1. Pre state - 1 Changed, 1 Unreviewed, and 0: Approved.
   2. Post state - 1 Changed, 0 Changed Requested, and 1: Approved.

Scenario 2: Snapshot does not exist in the main branch

1. Let's consider a snapshot B which is not present in the base build in the main branch, you create a new feature branch (F2) and add a new feature on this branch in Build 1.
2. This snapshot will be identified as a new snapshot in Build 1 and it will never be compared with main branch as the snapshot does not exist in the main branch.
3. This new snapshot has a green color button and you have approved this snapshot.
   1. Pre state - 1 Changed, 1 Unreviewed, and 0: Approved.
   2. Post state - 1 Changed, 0 Unreviewed, and 1: Approved.
4. You create another build in the feature branch Build 2. The snapshot in Build 2 remains exactly the same as the one in Build 1. In this case, the approval from Build 1 is carried forward to Build 2.
   1. Pre state - 1 Changed, 0 Unreviewed, and 1: Approved.
   2. Post state - 1 Changed, 0 Unreviewed, and 1: Approved.
5. Now, let's say you create another build, Build 3 in which the button color changes from green to red. This snapshot has a change that is not approved in Build 2 in F2. In this case, the approval is not carried forward.
6. Now, a user requests changes in Build 3 to change the color.
   1. Pre state - 1 Changed, 1 Unreviewed, and 0: Approved.
   2. Post state - 1 Changed, 1 Changed Requested, and 1: Approved.
7. In the next build Build 4, the user changes the color from red to green, so the new Build 4 is submitted for review again. In this case also, the approval is not carried forward.

1. Pre state - 1 Changed, 1 Unreviewed, and 0: Approved.
2. Post state - 1 Changed, 0 Changed Requested, and 1: Approved.

Approval is carried forward similarly for future builds.