Skip to main content
Transform your testing process with: Company-wide Licences, Test Observability & App Percy

Integrate your Storybook tests with Percy

Visual testing for Storybook

This documentation applies to Percy Storybook SDK version 4.0.0 and above.


Before you start, ensure you install the Node version needed for the Percy SDK with the appropriate Storybook version. Refer to the following table:

Storybook Version Node Version
v6 Node 14 and later
v7 Node 16 and later
v8 Node 18 and later

Create a Percy project
Sign in to Percy. In Percy, create a project of the type, Web, and then name the project. After the project is created, Percy generates a token. Make a note of it. You have to use it set your environment variable in the next step.

For details on creating a project, see Create a Percy project.

Set the project token as an environment variable
Run the given command to set PERCY_TOKEN as an environment variable:

Copy icon Copy snippet
Copy icon Copy snippet
Copy icon Copy snippet

To learn about environment variables in Percy, see Percy environment variables.

Install Percy dependencies
Install the dependencies by running the following command:

Copy icon Copy snippet

Update your test script
Import the Percy library to use the method and attributes required to take screenshots.

Copy icon Copy snippet

To learn more, visit Percy snapshot.

Run Percy
Run your tests with Percy.

If you are unable to use the percy:exec command or prefer to run your tests using IDE run options, you can use the percy exec:start and percy exec:stop commands. To learn more, visit Run Percy.

With a static Storybook build:

Copy icon Copy snippet

With a local or live Storybook URL:

Copy icon Copy snippet

Automatically run start-storybook:

Copy icon Copy snippet

With the sample test script, Percy takes four snapshots with args, globals, and any other query params appended to the URL of each snapshot:

Copy icon Copy snippet

Congratulations! You have successfully created your first build on Percy. To see the build with snapshots of your application, visit your project in Percy.
When you run another build with visual changes to your application, Percy takes new snapshots. You can then see the comparisons between the two runs on the new build.

CLI options

Copy icon Copy snippet


Storybook parameters are a set of static, named metadata about a story, used to control the behavior of Storybook features and addons. The percy parameter can be provided to add per-snapshot configuration options to a story or set of stories.

Copy icon Copy snippet
Copy icon Copy snippet

The following Percy Storybook parameters are accepted in addition to common per-snapshot options:

  • skip - Boolean indicating whether or not to skip this story.
  • name - Snapshot name. (default: ${story.kind}: ${})
  • args - Story args to use when snapshotting.
  • globals - Story globals to use when snapshotting.
  • queryParams - Query parameters to use when snapshotting.
  • waitForTimeout - Wait for a timeout before taking the snapshot.
  • waitForSelector - Wait for a selector to exist before taking the snapshot.
  • include - An array of regex patterns matching story names to only include for snapshotting.
  • exclude - An array of regex patterns matching story names to always exclude from snapshotting.
  • additionalSnapshots - An array of additional snapshots to take of this story.

additionalSnapshots accepts the following parameters:

  • prefix - A prefix added to this additional snapshot’s name.
  • suffix - A suffix added to this additional snapshot’s name.
  • name - Snapshot name. Replaces the inherited name.
  • args - Additional story args for this additional snapshot.
  • globals - Additional story globals for this additional snapshot.
  • queryParams - Additional query parameters for this additional snapshot.
  • include - Only apply the additional snapshot to matching stories.
  • exclude - Do not apply the additional snapshot to matching stories.

Percy config file options

In addition to common Percy config file options, this SDK also adds the following Storybook specific options:

Copy icon Copy snippet

See the configuration options above for details about each accepted config file option (note: the skip and name parameters are not accepted as Percy config file options).

Running in parallel

Storybook snapshots can be split into shards, so that they can be captured on multiple machines. The --shard-count option will split all snapshots into a number of shards. The --shard-size option is the inverse, splitting by number of snapshots. The --shard-index option tells the SDK which shard to take snapshots of. For example, to split into three shards, each capturing one third of the snapshots, each of these commands would be run on a different machine in parallel:

Copy icon Copy snippet

That way your snapshots capture up to 3 times faster.

Parallel build support requires a PERCY_PARALLEL_NONCE environment variable, a unique ID for this parallel build. If your CI provider is supported by Percy, this variable will automatically be set for you. Percy uses this to group many builds into a single build (with matching nonce’s). It can only be used once.

Storybook interactions tests

Storybook support interactive tests using play function. Percy Supports it by default without any additional configuration.

[Optional] Percy by default doesn’t wait for this play function to finish before taking the snapshot. In this case, The waitForSelector config can be used for Percy SDK to wait for that selector to appear. This selector can be added just before the play function completes, let’s check with a help of an example.

Copy icon Copy snippet


The old SDK did not take DOM snapshots or perform asset discovery, as all other modern Percy SDKs do. This sometimes resulted in flakey snapshots or snapshots with missing assets. However, DOM snapshots and asset discovery add an overhead cost of performance. Where the old SDK was very quick to simply upload the local build directory, the new SDK can be a little slower while it is capturing the real DOM and relevant assets of each story.

Unexpected diffs

Because the old SDK did not take DOM snapshots, JavaScript had to be enabled in our rendering environment for Storybook to properly load. This is in contrast to all of our other SDKs, where JavaScript is disabled by default to prevent flakey diffs caused by animations or other JavaScript running on the page. With the new SDK and real DOM snapshots, JS is disabled by default. If you upgrade and experience diffs due to the lack of JavaScript, it can be re-enabled using the matching Percy config file or per-snapshot option, enableJavaScript.

Mock Service Worker (MSW) support

You can capture API responses using Mock Service Worker (MSW). To enable this feature, include captureMockedServiceWorker: true in your configuration file as detailed here.

We're sorry to hear that. Please share your feedback so we can do better

Contact our Support team for immediate help while we work on improving our docs.

We're continuously improving our docs. We'd love to know what you liked

Thank you for your valuable feedback

Is this page helping you?


We're sorry to hear that. Please share your feedback so we can do better

Contact our Support team for immediate help while we work on improving our docs.

We're continuously improving our docs. We'd love to know what you liked

Thank you for your valuable feedback!

Talk to an Expert
Download Copy