CircleCI-Percy

Our goal at Percy is to help teams deploy with the confidence that their applications look exactly like they should.

Instead of manually checking your UI across browsers and screens, our visual testing and review solution automates it for you. Integrate Percy with your tests and our custom-built rendering infrastructure generates snapshots of your UI every time you push a change.

That workflow fits seamlessly into your existing CI/CD suite, helping you eliminate the risk of visual regressions on every single commit. With Percy, you can also run visual tests in tandem with parallelized CI builds–and our CircleCI orb makes it easier than ever.

Percy CircleCI Orb

Because Percy runs downstream from your CI service, it needs a clear signal of when the build has finished, so it knows when it has the full set of snapshots. Our orb ensures that there isn’t one late-starting test runner that hasn’t finished.

This is what a typical workflow with the Percy Orb looks like:

parallel builds on circleci

Your test suite kicks off, dividing the work of running the tests into multiple test runners. Once they have all finished, the percy/finalize_all command is called, triggering finalizing a build and treating all snapshots in the build as received.

Environment variables

Once you’ve created a Percy project to integrate with CircleCI, retrieve your PERCY_TOKEN under your project settings.

Set PERCY_PARALLEL_TOTAL to -1. This tells Percy that we don’t know how parallelized this run is, but we’ll consider our Percy build fully wrapped up when we hear the percy/finalize_all command from the orb.

Workflow configuration

Your CircleCI workflow configuration imports the percy/agent orb and once all tests have finished, it executes the percy/finalize_all command.

At a high level, this is what the .circleci/config.yml file should look like:

version: 2.1

orbs:
 percy: percy/agent@volatile

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

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

Running tests

Once you’ve added the Percy CircleCI Orb to your config file (.circleci/config.yml), snapshots will be rendered across browsers and screen sizes whenever your tests run.

In the example above, pixels that have changed are highlighted in red “visual diffs.” Percy’s SDKs make it easy to add visual tests to any front-end framework, test framework, component library, or style guide. For more information about integrating our orb into your CircleCI config file, visit the Percy docs.

We’re so excited to be a CircleCI Technology Partner, making visual testing even more efficient and scalable and we look forward to evolving our Orb for future use cases.

Learn more about CircleCI and Percy during our webinar, Visual testing in your CI/CD workflow with Percy and CircleCI orbs, on Tuesday, January 22, 2019, at 10:00am PST/18:00 UTC


David Jones is the Director of Engineering at Percy. He loves working with engineers and building tools to give them more confidence when shipping software. You can follow him @d_jones.