Getting started with visual testing in 5 minutes

Published on December 12, 2019
    Default avatar

    By Mike Fotinakis

    Getting started with visual testing in 5 minutes

    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.


    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?

    screenshot of a signup page with a button missing text

    In the example above, the button still works, and the text is actually still there, but the link 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 (or in addition to) 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 a new way to have 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 can save you time reviewing code and ensuring no visual bugs make their way to production.

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

    Step 1 — Integrating Percy

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

    screenshot of the Percy project interface

    Note: Signing up for a Percy account will kick off a 14-day trial, but once that expires, you’ll be transferred to a free plan that includes 5,000 free snapshots each month.

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

    Some popular examples are:

    The 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 the official PercyScript documentation.

    For this tutorial, we’re going to use a TodoMVC example app. You can adapt the PercyScript below to work for your own application.

    First, let’s set up the example app. This will require Node.js and npm to be installed. For more information about installing Node, please see How To Install Node.js on Ubuntu 18.04:

    1. git clone https://github.com/percy/example-todomvc.git
    2. cd example-todomvc/
    3. npm install
    4. 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, open a new terminal, and run:

    1. 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] });

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

    Step 2 — Running Visual Tests

    To run your PercyScript locally, copy PERCY_TOKEN from the new project screen, then run:

    1. export PERCY_TOKEN=your_token_here
    2. npx percy exec -- node snapshots.js

    Note: Be sure to replace your_token_here with your project-specific PERCY_TOKEN.

    You should see output like:

    [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, sending snapshots up to Percy for rendering and processing:

    screenshot of the Percy snapshot comparison UI

    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 Percy assumes that master builds are production-ready.

    Percy works by capturing the DOM snapshot everywhere the Percy snapshot command is called. The page or component is then rendered in a custom rendering environment. New snapshots are compared against baseline snapshots to determine which pixels have changed.

    Now that you’ve integrated your project and have pushed your first build to establish your baseline, let’s make a change and review the differences.

    Step 3 — Reviewing Visual Changes

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

    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:

    1. npx percy exec -- node snapshots.js

    Open up the resulting link, and you can now see the visual changes highlighted.

    Side-by-side Comparison

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

    screenshot of Percy's visual diff UI, showing changed pixels highlighted in red

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

    Note: 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 down keys.

    Responsive Diffs

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

    screenshot of Percy visual diff UI, showing a selector for different width images

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

    Cross-browser Visual Testing

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

    screenshot of Percy visual diff UI, showing a selector for Chrome and Firefox rendering

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

    If you’re happy with your changes, hit Approve All. You’ve completed your first visual review.

    Step 4 — Integrating Visual Testing with Code Workflows

    To get the most value out of automated visual testing, it may make sense to add visual reviews to you continuous integration and testing workflows.

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

    You can also add Percy to your pull/merge requests to be notified when visual changes are detected, and when those changes are approved and ready to merge.

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

    screenshot of Github UI showing pull request testing status with some tests failing

    Clicking Details will take you right to the Percy UI where you can review visual changes. After snapshots are approved, your commit status will change to green and the PR can be merged:

    screenshot of Github UI showing pull request testing status with all tests passing

    At this point you’re ready to merge.


    In this tutorial we have reviewed a visual testing workflow using Percy’s visual review platform. To continue learning about how Percy works, take a look at some more of the official documentation:

    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
    Mike Fotinakis


    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!

    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