Tutorial: Visual testing in 5 minutes with PercyScript

Published in

Percy Blog

7 min readSep 12, 2019

This story has been edited from its original appearance on the Scotch.io blog.

There are tons of tools out there that help you make sure your app is functioning perfectly, but how do you catch bugs that are purely visual?

In the example above, the button probably still works, and the text might actually still be there, but it has somehow changed to be the same color as the button.

You could write regression tests to ensure that the text is always white, and the button is always green, but across hundreds of pages and states, that becomes unruly very fast. So in lieu of writing line after line of regression tests, you might manually check all those pages before deploying.

But we all know how time-consuming and imperfect manual QA can be. That’s where visual testing comes in.

Visual testing is the new way to have 100% confidence in your UI.

Instead of manually checking your UI or testing the code underneath, visual testing detects pixel-by-pixel changes on every commit automatically. Visual testing saves you time reviewing code and ensuring no visual bugs make their way to production.

In this 5-minute tutorial, we’ll walk through integrating Percy with an example app, reviewing visual changes, and running visual reviews as part of your day-to-day workflow.

Step 1: Integrate Percy

If you haven’t already, sign up for a Percy account, name your organization, and create your first project.

Note: Signing up for a Percy account is free and includes 5,000 free snapshots each month.

Percy projects correspond with the apps, sites, or component libraries you want to test. With our SDKs, you can add visual testing to virtually anything that renders in a browser.

These are some of our popular SDKs:

Our SDKs work by importing and calling Percy snapshot commands wherever you’d like visual coverage.

For this tutorial, we’ll use PercyScript, which provides a quick and easy way to start doing visual testing in just a couple of lines of JavaScript. PercyScript can fully interact with elements by clicking, typing, and waiting and can also be used to test live URLs. Read more in our PercyScript documentation.

We’re going to use this TodoMVC example app, but you can easily adapt the PercyScript below to work for your own application.

First, let’s set up the example app:

$ git clone https://github.com/percy/example-todomvc.git
$ cd example-todomvc/
$ npm install
$ npm run start

You can now visit http://localhost:8000 and play around with the todos app yourself.

Next, we’re going to install PercyScript and write our first visual tests for this application.

⚠️ Keep the server running and open a new terminal. Then run:

$ cd example-todomvc
$ npm install -D @percy/script

This will add @percy/script to your package.json file.

Next, create a file named snapshots.js and add your first PercyScript to take visual snapshots when we navigate to the main app page, and after we enter a new to-do:

// snapshots.js
const PercyScript = require('@percy/script');// A script to navigate our app and take snapshots with Percy.
PercyScript.run(async (page, percySnapshot) => {
  await page.goto('http://localhost:8000');
  await percySnapshot('TodoMVC home page');// Enter a new to-do.
  await page.type('.new-todo', 'A really important todo');
  await page.keyboard.press('Enter');
  await percySnapshot('TodoMVC with a new todo', { widths: [768, 992, 1200] });
});

The next step is to start running this PercyScript and seeing visual changes.

Step 2: Run visual tests

To get the most value out of automated visual testing, we recommend integrating visual reviews into your workflow.

Configure Percy with your CI service so that visual tests runs every time a CI build is kicked off. Simply add PERCY_TOKEN to your CI environment variables. For more in-depth instructions and to see all of our supported CI services, check out our CI setup documentation.

Here are a few of our most popular supported services:

For this tutorial, we’re going to run our PercyScript locally. Simply copy PERCY_TOKEN from your new project screen and run:

$ export PERCY_TOKEN=aaabbbcccdddeee
$ npx percy exec -- node snapshots.js

Note: Be sure to replace the token with your project-specific and make sure that you’re in PERCY_TOKEN

You should see output like:

$ npx percy exec -- node snapshots.js
[percy] created build #1: https://percy.io/percy-tutorials/percyscript-todomvc/builds/2580697
[percy] percy has started.
[percy] snapshot taken: 'TodoMVC home page'
[percy] snapshot taken: 'TodoMVC with a new todo'
[percy] stopping percy...
[percy] waiting for 2 snapshots to complete...
[percy] done.
[percy] finalized build #1: https://percy.io/percy-tutorials/percyscript-todomvc/builds/2580697

Note: If you haven’t been following along, you can visit the build listed in the above output or here.

The PercyScript has run, sending snapshots up to Percy for rendering and processing:

You’ll see that since this is the first build, there isn’t anything to compare it to. It has also been “Auto-approved” because the commit was on master and we assume that master builds are production-ready.

Percy works by capturing the DOM snapshot everywhere the Percy snapshot command is called. We then recreate the page in our custom rendering environment. New snapshots are compared against baseline snapshots to determine which pixels have changed.

Step 3: Review visual changes

Now that you’re integrated and have pushed your first build establishing your baseline, let’s make a change and review the outcome in Percy!

Let’s make a new branch and introduce a visual change.

Use your text editor to edit index.html and make the h1 text on line 11 blue:

<h1 style="color:blue;">

Save the updated file and run the snapshots again:

$ npx percy exec -- node snapshots.js

Open up the Percy link, and we can now see the visual change highlighted!

Side-by-side comparison

The red areas in the right panel represent pixels that have changed — those changed pixels are called visual diffs.

Clicking that area (or pressing “d”) will toggle between the underlying snapshot and the overlaid diff so you can easily see what exactly has changed.

Pro tip: Click the arrow expansion box for a full-screen view. Cycle through old, new, and diff with your left and right keys, and navigate between snapshots with up and down keys.

Responsive diffs

You’ll notice the widths at which your snapshots have been rendered show up here. In your example, we rendered snapshots for mobile and desktop widths.

Select the various widths to see what has changed across each width.

Cross-browser visual testing

By default, Percy renders all snapshots across both Chrome and Firefox.

Cross-browser snapshots help you detect subtle differences caused by browser rendering.

Step 4: Visual review workflow

Now that you’ve seen your first visual diff, let’s talk about the review workflow.

You can either Approve ✅ or Request changes 🙅‍♀️on snapshots.

If you’re happy with your changes, you can approve individual snapshots or hit “Approve all” to signify that everything looks good. Alternatively, if the detected changes were unintentional or otherwise are not ready to be merged, marking them as “Changes requested” will block the build from being approved. This feature, coupled with snapshot comments, makes it easy for teams to collaborate and stay on the same page throughout visual reviews.

To take the full advantage of our visual review workflow, you can also easily add Percy to your pull/merge requests to be notified when visual changes are detected, and when actions have been taken.

Head to your organization settings to give Percy access to GitHub, GitLab, or Bitbucket. Once you’ve given access, be sure to connect your project to your project’s repository. Then the next time you commit, Percy will show up in your pull/merge request checks:

Clicking “Details” will take you right to the Percy UI where you can review visual changes. Once snapshots are approved, your commit status will change to green, signaling that the PR is ready to be merged:

That’s it! You’re ready to merge with confidence that every part of your app looks exactly like it should.

We hope this tutorial has helped you get acquainted with Percy’s visual review platform and workflow. To continue learning about how Percy works, feel free to check out these additional resources:

Happy testing! 💜