App & Browser Testing Made Easy

Give your users a seamless experience by testing on 3000+ real devices and browsers. Don't compromise with emulators and simulators

Home Guide How to perform Storybook Visual Testing?

How to perform Storybook Visual Testing?

By Priyanka Bhat & Ganesh Hegde, Community Contributors -

Visual Testing is one of the critical steps in application user interface testing. Visual tests help to catch the bug, which is in font, color, and size contrast. Each time you run the visual tests, it will compare against the base screenshot. This helps to avoid any potential regression while implementing new UI changes.

Within the realm of visual testing, visual regression testing doesn’t require a lot of coding knowledge.

What is Storybook Visual Testing?

Storybook visual testing builds the front-end user interface components in isolation. It streamlines the documentation, development, and testing and makes UI development easier and more efficient. What makes it so handy is that Storybook can be used with many popular frameworks such as React, Angular, Vue, etc.

Now, when it comes to performing visual testing with Storybook or Storybook Visual Regression Testing, the easiest way to go about it, is by using Percy.

Percy by Browserstack is a visual testing and review platform that helps teams automate visual testing. It captures screenshots, compares them against the baseline, and highlights visual changes. Agile teams at Canva are one of the well-known entities that rely on Percy.

This guide will be a tutorial for performing Storybook visual testing with Percy using React App. We assume you are developing a React application with a Storybook you have set up.

How to Perform Storybook Visual Testing with Percy?


Step 1: Install required node packages

Install required Percy Node Packages using the command below.

npm install --save-dev @percy/cli @percy/storybook

Step 2: Get the PERCY_TOKEN

  • Login to Percy (If you don’t have an account, create one by Signing Up)
  • Create a New Project
  • Navigate to Project Settings
  • Copy the PERCY_TOKEN

Step 3:  Set the PERCY_TOKEN environment variable

Based on the command-line tool you are using you can set the environment variable as below

# Unix
$ export PERCY_TOKEN="<your-project-token>"

# Windows
$ set PERCY_TOKEN="<your-project-token>"

# Powershell
$ $Env:PERCY_TOKEN="<your-project-token>"

Step 4: Execute the PERCY test

To execute Percy test use the below command

npx percy storybook:start

Alternatively, if you have already configured the package.json test command you can use the command 

npm run test

Step 5: View the Results

Wait until the execution completes and you will see the results with the build  URL then you can easily navigate to the URL and see the visual differences.

If there is a difference then it will show the difference in Percy Dashboard.

Percy Dashboard

If there is no difference you can see the message “No Changes”

No ChangesPercy Storybook also provides an option to take additional snapshots, using additionalsnapshots options. additonalSnapshot option helps to take a snapshot of various states of your component.

For example, you have ***.stories.js file like below.

import React, { useState, useRef } from 'react';
import TodoApp from './TodoApp';

export default {
title: 'TodoApp',
component: TodoApp,

export const App = args => <TodoApp {...args}/>;

// match component name for single story hoisting
App.storyName = 'TodoApp';

App.args = {
showTodos: 'all',
todos: [
{ title: 'Foo', completed: true },
{ title: 'Bar', completed: true },
{ title: 'Baz' },
{ title: 'Qux' },
{ title: 'Xyzzy' }

Now, if you won’t take the additional snapshots for the different states you can add the App.parameters sections like below.

App.parameters = {
// take additional snapshots of various states
percy: {
additionalSnapshots: [{
suffix: ' - Active',
args: { showTodos: 'active' }
suffix: ' - Completed',
args: { showTodos: 'completed' }
}, {
suffix: ' - None',
args: { todos: [] }

In the above code we have added additional snapshots option to capture various states of the component. Once you execute the Percy test, then the screenshot will be captured, and the screenshot name will be suffixed with the value given in the suffix parameter as above (EX: Active, None etc).

Best Practices for Performing Storybook Visual Testing

  • Always use one file per component: Having one file per component makes the framework easier to maintain and more readable.
  • Consider visual testing at an early stage: Many times, Visual Testing is an afterthought when developing the UI application, having the visual testing tool integrated with the storybook at an early stage makes the application more stable.
  • Make visual testing a mandate: Any visual bug which is found at a later stage of development is costly, so integrating visual testing at the component level helps to debug at an early stage.
  • Have a scheduled build pipeline for Visual Tests just like any functional tests that help catch unintended UI changes.

Storybook visual testing with Percy is perfect for developing and testing UI. Most importantly, the validation of UI will happen in the initial state so the UI bugs can be eliminated and improve the release cycle.

Unlike other image comparison tools in the market, Percy provides image comparison across browsers and can be easily integrated for visual regression testing with: 

Try Percy for Visual Testing

UI Testing Visual Testing

Featured Articles

How to perform Visual Regression Testing using Cypress

Is Visual Comparison Testing the Future?

Curated for all your Testing Needs

Actionable Insights, Tips, & Tutorials delivered in your Inbox
By subscribing , you agree to our Privacy Policy.
thank you illustration

Thank you for Subscribing!

Expect a curated list of guides shortly.