Introduction to Visual Testing for Web Apps

Published on June 11, 2019


Introduction to Visual Testing for Web Apps

While we believe that this content benefits our community, we have not yet thoroughly reviewed it. If you have any suggestions for improvements, please let us know by clicking the “report an issue“ button at the bottom of the tutorial.

Visual testing (sometimes called visual regression testing or UI testing) is the process of reviewing software for purely visual integrity. Unlike the tools you use to make sure your app is behaving as intended, visual testing is all about what your users actually see and interact with.

It works by comparing snapshots of your UI against baselines to see if pixels have changed. By looking at the pixels rather than the code underneath, visual testing makes it easy to see exactly what your UI looks like before deploying and to catch visual regressions.

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 to in tandem with your CI/CD pipeline on every pull request.

Now that you have an overview of how visual testing works, we’re going to walk through a 5-minute tutorial.

This is what we’ll cover:

  1. Integrating Percy with an example web application (or your own)
  2. Running your first visual tests
  3. Making and reviewing visual changes
  4. Adding visual reviews to your day-to-day workflow

Let’s get started!

Step 1: Integrate Percy

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

Setting up your Percy project

Signing up for a Percy account is free and includes 5,000 snapshots each month with upgrades starting at $29 available.

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:

For this tutorial, we’ll use PercyScript—the easiest and fastest way to get started with visual testing for any web app. We’re going to use this TodoMVC example app, although you can easily adapt the PercyScript below to work for your own application.

First, let’s setup 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.

It’s important to keep the server running and open a new terminal to 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: [768, 992, 1200] });

That’s it! The next step is to start running this PercyScript.

Step 2: Run Visual Tests

To run your PercyScript locally, copy the PERCY_TOKEN environment variable from the new project screen or your project settings, then run:

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

Replace the token with your project’s `PERCY_TOKEN`.

You should see output like:

$ 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

What’s happening behind the scenes? 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 which pixels have changed.

If you’re following along, 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.

Step 3: Review Visual Changes

Now that you’re integrated and have pushed your first build establishing your baseline, let’s make a new feature branch and introduce a visual change to review in Percy.

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

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

Now run the snapshots again:

$ npx percy exec -- node snapshots.js

Head back to Percy or click the Percy build link to see the visual changes! On the right, you’ll see the new snapshot, overlaid with red pixels highlighting the areas that have changed.

Percy UI showing a snapshot comparison

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.

Responsive diffs

You can also use Percy to get coverage across all the most important viewport sizes. By default, we render snapshots for mobile and desktop widths. Toggle between widths to see what has changed across each.

Cross-browser visual testing

Cross-browser snapshots help you detect 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. By default, Percy renders all snapshots across both Chrome and Firefox.

Since you wanted to make these changes, hit “Approve All.”

You’ve done your first visual review!

Step 4: CI and Source Code Integrations

To get the most value out of automated visual testing, we recommend integrating with your existing dev tools and processes.

Percy is designed to run alongside your CI builds as part of your code review process. 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:

With a source code integration enabled, you will be notified right in your pull or merge request when visual changes are detected, and when those changes are approved and ready to merge.

GitHub pull request with Percy status update showing visual changes detected

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.

GitHub pull request with Percy status update ready to merge

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:

And if you haven’t already, sign up for a free Percy account. You get 5,000 free monthly snapshots and access to our visual testing platform and integrations.

✨ Happy testing!

Thanks for learning with the DigitalOcean Community. Check out our offerings for compute, storage, networking, and managed databases.

Learn more about us

About the authors
Default avatar


Still looking for an answer?

Ask a questionSearch for more help

Was this helpful?
Leave a comment

This textbox defaults to using Markdown to format your answer.

You can type !ref in this text area to quickly search our full set of tutorials, documentation & marketplace offerings and insert the link!

Try DigitalOcean for free

Click below to sign up and get $200 of credit to try our products over 60 days!

Sign up

Join the Tech Talk
Success! Thank you! Please check your email for further details.

Please complete your information!

Featured on Community

Get our biweekly newsletter

Sign up for Infrastructure as a Newsletter.

Hollie's Hub for Good

Working on improving health and education, reducing inequality, and spurring economic growth? We'd like to help.

Become a contributor

Get paid to write technical tutorials and select a tech-focused charity to receive a matching donation.

Welcome to the developer cloud

DigitalOcean makes it simple to launch in the cloud and scale up as you grow — whether you're running one virtual machine or ten thousand.

Learn more
DigitalOcean Cloud Control Panel