Percy Developer Hub

Welcome to the Percy Developer Hub. You'll find comprehensive guides and documentation to help you start working with Percy as quickly as possible, as well as support if you get stuck. Let's jump right in!

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 either use a username/password combination or log in with GitHub.

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.

Projects


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.

Builds


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-browser testing, you can toggle all snapshots between each browser.
  • 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 generating snapshots.
  • Builds can be marked as failed if all assets are not uploaded correctly, no snapshots were received, or rendering the snapshot 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 snapshots were generated, 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.

Snapshots and diffs


A Percy snapshot is a rendering of a web page or component.

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

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

What you should know about 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 snapshots, you can view each snapshot comparison across each width.
  • You can expand into a full-screen snapshot mode and use the arrows or keyboard arrows to navigate through original, new, and diff for each snapshot comparison.

Snapshot rendering and asset discovery


Percy is not designed to accept screenshots or 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 snapshot rendering and asset discovery:

  • We have lots of built-in and configurable functionality to make snapshots 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, grouped changes, 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.

What's next

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

Getting started
SDKs overview

Percy basics


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.