Percy Basics

Quick introduction to the basic terms and concepts of Percy

Percy is an all-in-one visual testing and review platform. Our goal is to assist teams in automating manual QA processes, enabling the detection of visual bugs, and providing valuable insights into UI changes with each commit.

Percy supports visual testing of web applications on desktop and mobile browsers.

Sign in to Percy

Percy is now a part of BrowserStack. Sign up for a free Percy account! You can either use a username/password combination or sign in using BrowserStack credentials.

Projects

After you have signed in to Percy, you can check the demo project by launching the demo project playground or you can directly create a new project.

You can create a new project using Create new project button.

Projects serve as the organizational structure for Percy builds. We recommend that you create a Percy project for each application you intend to run visual tests on. For example, create a project each for your web app, component library, and marketing website.

What you should know about projects:

• With every Percy plan, you can create unlimited projects.
• You can change your project name and slug at any time. Be aware that old build URLs break when you change the slug.
• You cannot delete projects but can archive them at any time.
• All users in an organization in which your projects live have access to the projects in that organization.
• API keys are project-specific and write-only.
• When integrating with pull requests, each project has to be linked with the relevant repository.

• Each project’s settings enable you to configure browsers, visibility settings, automatic branch approvals, and many more.

  

Builds

After you install as SDK and initiate test runs, Percy automatically generate builds. Typically, Percy builds are triggered with each commit or whenever there’s a change in a pull request, ensuring a continuous review of visual alterations.

What you should know about builds:

• Builds expire according to the plan you are on. Builds on the free plan expire in 30 days, and other plans include 1 year of build history.
• If you have enabled cross-browser testing, you can toggle all snapshots between each browser.
• If your build status is “Receiving,” we are likely waiting to receive assets.
• If your build status is “Processing,” we’ve received all builds and are rendering screenshots.
• Builds can be marked as failed if all assets are not uploaded correctly, no screenshots were received, or rendering in our browsers timed out.
• You can click the information icon next to the build number to see additional data such as when it was created, how long it took, what baseline it is comparing it to, how many screenshots are rendered, git information (if available), and more.

• If you’ve linked a repository to a Percy project, your builds also have associated metadata such as pull request and commit details.

  

Screenshots and snapshots

A screenshot is a rendering of a page or component in an individual browser and responsive width combination. Snapshots are made up of screenshots that are permutations of pages or components in a specific browser and at a specific width. For example, two pages rendered across two browsers and three widths, result in twelve screenshots, but Percy’s UI displays it as two snapshots.”

For each snapshot comparison, you see the baseline on the left and the new screenshot on the right. By comparing new and baseline screenshots, we generate a third image—a visual diff—overlayed on top of the new screenshot.

Screenshot rendering and asset discovery

Percy doesn’t accept images. Instead, it captures DOM snapshots and page assets (like CSS and images). Percy handles all reconstruction and rendering on a dedicated infrastructure designed for scalable visual testing.

What you should know about approvals:

• We have lots of built-in and configurable functionality to make screenshots as stable as possible, including freezing animations, handling dynamic data, and rendering third-party fonts.
• We skip assets that are hosted on a different domain from what the snapshot came from.
• We skip redirected assets (like redirecting to a CDN on request)
• We cannot capture authenticated assets.

Approval workflow

In Percy, you can approve individual snapshots with visual changes, entire snapshot groups, or even whole builds. If you’ve integrated your source code, approving a build automatically updates your pull request or commit status to “All visual changes have been approved”.

What you should know about approvals:

• Your build is auto-approved by default on all changes on the main branch. You can customize which branches get auto-approved in your project settings.
• Previously approved snapshots are carried forward to subsequent builds for the life of the branch.
• You can optionally set Percy builds up as a blocker to merge in GitHub repository settings.
• Percy uses a variety of strategies to determine the optimal base build for comparison on every build you create. Read more about our baseline picking logic.

Changes requested workflow

In Percy, you can request changes on snapshots with visual changes or on grouped snapshots. This action labels both the affected snapshot(s) and the entire build as ‘Changes requested.’ When you attempt to approve them, a reminder appears.

When you’ve integrated Percy with your source code, approving a build updates your pull request or commit status to reflect the number of changes requested.

What you should know about approvals:

• Only one snapshot needs to be marked as “Changes requested” for the entire build status to be updated to match.
• Changes previously requested on snapshots are carried forward to subsequent builds as long as the diff matches the original snapshot comparison. When the diff no longer matches, it’s reverted to “Unreviewed”.