Percy basics


Covered in this doc

  • The ins-and-outs of Percy—from creating an account to approving builds
  • What you should know about each part of the Percy platform

Accounts and organizations

If you haven’t already, sign up for a free Percy account! You can login with a username/password combination.

Once you’ve created an account, you will be asked to create a new organization.


What you should know about organizations:

  • The organization slug is a unique identifier that shows up in the URL.
  • Organizations can have multiple user accounts attached to them.
  • You can create more than one organization, but we recommend keeping all related applications grouped together in single organizations—use projects for different databases, applications, or environments.
  • Plans and billing are done at the organization level.


After you’ve created an organization you will be taken to create a new project.


Projects are how Percy builds are organized. We recommend that you name and treat your Percy projects as one-to-one with each unique application you’ll be testing with Percy. For example, create separate projects for your web app, component library, marketing website, etc..

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 will break if the slug is changed.
  • You cannot delete projects but can archive them at any time.
  • All users in the organization in which your project lives will have access to the projects in that organization.
  • API keys are project-specific and write-only.
  • When integrating with pull requests, each project will have to be linked with the relevant repository.
  • Each project’s settings allow you to configure browsers, visibility settings, automatic branch approvals, and more.


Once you’ve installed a Percy SDK and start running tests, Percy will populate builds.


Percy builds usually run on each commit or each change to a pull request so that you can continuously review visual changes.

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-device testing, you can toggle all snapshots between each device.
  • If your build status is "Receiving," we are likely waiting to receive assets.
  • Your build status will be “Processing” after 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 were rendered, git information (if available), and more.
  • If you've linked a repository to a Percy project, your builds will also have associated metadata such as pull request and commit details.

Screenshots, snapshots, and diffs

A Percy snapshot is a rendering of a web page or component. 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 would result in twelve screenshots but would show up in Percy's UI as two snapshots.

For each snapshot comparison, you will 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.



You can click the area on the right to toggle between the diff and the screenshot or use your d key.

What you should know about screenshots, snapshots, and diffs:

  • New snapshots that have not had a baseline yet are considered “New snapshots”—in your first Percy build you will see that there are no baseline snapshots to compare to yet.
  • 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.
  • If you’ve configured responsive screenshots, you can view each screenshot across each width.
  • You can expand into a full-screen screenshot mode and use the arrows or keyboard arrows to navigate through original, new, and diff for each screenshot.
  • If there are several matching visual changes within a build, they get grouped in Percy's UI. Read more about automatic diff matching.

Screenshot rendering and asset discovery

Percy is not designed to accept images but instead captures DOM snapshots and page assets (CSS, images, etc.). We do all reconstruction and rendering in our own infrastructure designed specifically for visual testing at scale.

Percy is designed to keep all the computationally expensive screenshot rendering and visual diffing completely out of your systems. By accepting DOM snapshots and assets alone, we can highly optimize Percy to have lightweight clients in numerous languages and environments with little performance impact on your side.


The first build may also be slower than usual while assets are first uploaded, then assets are only uploaded again when they change.

What you should know about screenshot rendering and asset discovery:

  • 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, snapshot groups, or entire builds.

If you have a source code integration set up, approving a build will also update your pull request or commit status to "All visual changes have been approved.”

What you should know about approvals:

  • Your build will be auto-approved by default on all changes on master. You can customize which branches get auto-approved in your project settings.
  • Previously approved snapshots will get 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. Taking this action will mark the snapshot(s) and the entire build as “Changes requested.”

Once a snapshot or snapshot group is marked as "Changes requested," a pop-up dialog will appear when approvals are attempted.

If you have a source code integration set up, approving a build will also update 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 will get carried forward to subsequent builds as long as the diff matches the original snapshot comparison. Once the diff no longer matches it will be reverted to “Unreviewed”

What's next

Learn how to get started with Percy and how to install and configure one of our SDKs.