Seamless, parallelized, visual testing with the Percy CircleCI Orb

Published in

Percy Blog

3 min readJan 9, 2019

This post originally appeared on the CircleCI blog.

Percy’s visual testing workflow fits seamlessly into your existing CI/CD suite, helping you eliminate the risk of visual regressions on every single commit. It also supports running 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:

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 to consider our Percy build fully wrapped up when we hear the percy/finalize_allcommand 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.1orbs:
 percy: percy/agent@volatilejobs:
 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.” Our 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.

Want to learn more about our CircleCI orb?

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

Percy is a visual testing platform that gives your team confidence in every visual change before it’s shipped. Learn more at https://percy.io. 💜