Integrate your Storybook tests with Percy
Visual testing for Storybook
This documentation applies to Percy Storybook SDK version 4.0.0 and above.
Prerequisites
Before you start, ensure you install the Node version needed for the Percy SDK with the appropriate Storybook version. Refer to the following table:
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:
To learn about environment variables in Percy, see Percy environment variables.
Install Percy dependencies
Install the dependencies by running the following command:
Update your test script
Import the Percy library to use the method and attributes required to take screenshots.
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:
With a local or live Storybook URL:
Automatically run start-storybook:
With the sample test script, Percy takes four snapshots with args, globals, and any other query params appended to the URL of each snapshot:
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
Supported environment parameters
Modify certain aspects of Percy’s behavior with Storybook by configuring these environment variables within your CI environment:
| Environment Variable | Description |
|---|---|
PERCY_RETRY_STORY_ON_ERROR |
Percy retries a story three times when there is an error. You can set this to false if you do not want to include retries. The default is set to true. |
PERCY_SKIP_STORY_ON_ERROR |
Set this to true to skip a story if an error occurs, allowing subsequent stories to be processed successfully. The default is false. |
Learn more about Percy’s supported parameters.
Configuration
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.
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}: ${story.name}) -
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:
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:
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.
Performance
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
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!