Getting Started with Visual Testing

There are tons of tools out there that help you make sure your app is functioning correctly. But how do test software from a purely visual standpoint?

Chances are you’re writing functional tests to check visual elements, or manually checking your UI whenever you push a change. If you are doing either of those things, then you know that they’re incredibly time-consuming and bugs still end up slipping through the cracks.

That’s where visual testing comes in.

Unlike the tools you use to make sure your app is functioning as intended, visual testing uses automation to test what your users actually see and interact with.

How it Works

Visual testing works by comparing snapshots of your UI against previously generated baselines to see if anything has visually changed. By looking at the actual UI rather than the code underneath, visual testing makes it easy to catch visual regressions and see exactly what your UI looks like before deploying.

Visual testing is more than snapshot testing—having a visual review workflow to get continuous visual coverage is crucial. With Percy, it’s easy to integrate visual testing into your stack, run in tandem with your CI/CD pipeline, and get visual feedback as part of every code review.

In this 5-minute tutorial, we’re going to walk through how to integrate Percy with an example app, make some visual changes, and review the changes in Percy.

Visual Testing Tutorial

If you haven’t already, sign up for a free Percy account. Once you’ve created an organization and project, you’re ready to install an SDK and add snapshots to your web application, component library, or static site.

These are a few of our popular SDKs:

• Cypress
• Puppeteer
• Ember web apps
• Capybara for Ruby apps
• Storybook for React

For this tutorial, we’re going to PercyScript on the TodoMVC example app, although you can easily adapt the PercyScript below to work for your own application.

First, 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 app yourself.

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

Keep the server running, open a new terminal, and run:

$ 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:

// 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: [375, 1280] });
});

That’s it! The next steps are to start running this PercyScript and review visual changes.

Copy your project-specific PERCY_TOKEN environment variable from the new project screen, then run:

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

The output should look like this:

$ npx percy exec -- node snapshots.js
[percy] created build #1: https://percy.io/test/example-todomvc/builds/1738842
[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/test/example-todomvc/builds/1738842

The PercyScript has run and sent 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 or component in our custom rendering environment. New snapshots are compared against baseline snapshots to determine what has changed visually.

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!

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

<h1 style=”color:#9e66bf;”>

Now rerun the snapshots:

$ npx percy exec -- node snapshots.js

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

A lot is going on here, so let’s review each component.

• 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.
• 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.
• By default, Percy renders all snapshots across both Chrome and Firefox, making it easy to see subtle differences caused by browser rendering.

If you’re happy with your changes, hit “Approve All”—knowing with 100% confidence what visual changes you’ll be deploying.

You’ve done your first visual review.

CI and Source Code Integrations

To get the most value out of automated visual testing, we recommend integrating with your CI service so that Percy runs every time a CI build is kicked off. We support all the popular services including:

• CircleCI
• Buildkite
• Codeship

We also recommend integrating with GitHub, GitLab, or Bitbucket to get notified right in your pull requests when visual changes are detected.

Our source code integrations make it easy to review visual changes as every code review Clicking “Details” will take you right to the Percy build where you can review visual changes.

After snapshots are approved, your commit status will change to green, and the PR can be merged.

Making visual testing part of code review helps you deploy 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:

• Getting started with Percy
• Percy platform basics
• Visual testing basics
• Percy SDKs

This blog article was sponsored by Percy.

Mike Fotinakis

Mike is Co-Founder and CEO of Percy, where he works on challenging problems at the intersection of design, development, and deployment. Mike was previously an engineer at Google and is now enjoying building his first company from the ground up.