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!

Covered in this doc

Integrating Percy with your CircleCI environment
Configuring your CircleCI Orb for parallelized builds

Integrating Percy with your CircleCI environment


Configuring environment variables

In your CircleCI project, go to Project settings > Environment Variables.

Then set PERCY_TOKEN to the write-only token from your Percy project. This token can be found in your Percy project's settings.

Alternative circle.yml setup

A different way is to add the environment variables to your circle.yml. See the CircleCI: Using Environment Variables docs for more info.

Keep your Percy token secret

Anyone with access to your token can add builds to your project, though they cannot read data.

If your code is public, do not add the PERCY_TOKEN to your code and use the above environment setup instead.

Parallelized Tests - Configuring your CircleCI Orb


If you run your tests in parallel, use our CircleCI orb to signal when all parallel tests have completed. Integrating Percy with CircleCI is made easy with our percy/agent CircleCI orb.

The CircleCI orb is only for parallel builds

You will only need to use the CircleCI orb if you're running multiple Percy builds in CI

CircleCI Orbs require CircleCI configuration version 2.1 or higher.

How it works

The workflow you'll be aiming for is the following:

Environment variables

  • PERCY_PARALLEL_TOTAL: this must be set to -1. This tells Percy we don't know how parallelized this run is, but we'll consider your Percy build fully wrapped up when we hear the percy/finalize_all command from the Orb.
  • PERCY_TOKEN: This is the token obtained from your project settings in Percy.

There are a number of different ways you can set these environment variables to be available on each step. See CircleCI's Environment Variable Usage Options documentation for more information.

Workflow configuration

Your CircleCI workflow configuration at a high level should look like this:

version: 2.1

orbs:
 percy: percy/agent@0.1.2

jobs:
 run_tests:
   parallelism: 3
   steps:
     - attach_workspace:
         at: .
     - run: echo "your tests run here"

workflows:
 test:
   jobs:
     - run_tests
     - percy/finalize_all:
         requires:
           - run_tests

We first import the percy/agent orb and then once all tests have finished, execute percy/finalize_all command from the Orb. Make sure you use the latest version of the orb from CircleCI's registry.

Here's a sample of what this looks like integrated into the percy-web project:

Additional resources


We teamed up with the CircleCI team for a live demo of our integrated workflow. Watch the recording of the session below to learn more about our CircleCI orb, and see a live visual testing demo.


What's next

If you haven't installed and configured an SDK or source code integration, those are your next steps to getting started with visual testing.

SDKs overview
Source code integrations

CircleCI


Suggested Edits are limited on API Reference Pages

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