Ask the Community
Storybook advanced topics
This guide covers advanced configuration options for integrating your Storybook automated tests with BrowserStack Percy.
On this page, you learn how to configure responsive DOM capture, manage snapshot behavior, run tests in parallel, and capture interactions and documentation pages. Use these capabilities to fine-tune snapshot capture, control execution, and scale visual testing across complex Storybook setups.
Enable responsive DOM capture for Storybook components
Responsive DOM capture allows Percy to capture snapshots of a Storybook component across multiple viewport widths.
You can enable this feature either:
- At the snapshot (component) level, or
- Globally using the Percy configuration file
This component-level config works with @percy/storybook SDK version 9.
Snapshot-level configuration
Use the percy parameter in a story to enable responsive snapshot capture and define widths.
Global configuration file
Enable responsive snapshot capture globally using .percy.yml.
Precedence rules
Percy applies the following precedence when configuring responsive snapshots:
- Snapshot-level settings override global settings.
- If a setting is not defined at the snapshot level, Percy uses the global configuration
- If
widthsare not defined at either level, Percy uses the Project-level configuration
CLI options
Use these options with the percy storybook command to control snapshot execution.
| Options | Description |
|---|---|
| -i, –include | Pattern to match story names to include in snapshots. |
| -e, –exclude | Pattern to match story names to exclude from snapshots. |
| –shard-count | Number of shards to split snapshots into. |
| –shard-size | Size of each shard to split snapshots into. |
| –shard-index | Index of the shard to take snapshots of (0-based indexing). |
| –partial | Marks the build as a partial build. |
Percy options
| Options | Description |
|---|---|
| -c, –config | Config file path. |
| -d, –dry-run | Print snapshot names only. |
| -h, –allowed-hostname | Allowed hostnames to capture in asset discovery. |
| –disallowed-hostname | Disallowed hostnames to abort in asset discovery. |
| -t, –network-idle-timeout | Asset discovery network idle timeout. |
| –disable-cache | Disable asset discovery caches. |
| –debug | Debug asset discovery and do not upload snapshots. |
Global options
| Options | Description |
|---|---|
| -v, –verbose | Logs everything. |
| -q, –quiet | Logs errors only. |
| -s, –silent | Logs nothing. |
| –help | Displays command help. |
Supported environment parameters
Configure Percy behavior in your CI environment using the following variables:
| 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. |
PERCY_STORYBOOK_DOC_CAPTURE |
Captures visual snapshots of standalone .mdx documentation pages. |
PERCY_STORYBOOK_AUTODOC_CAPTURE |
Captures visual snapshots of Storybook’s auto-generated documentation pages (“Autodocs”). |
Learn more about Percy’s supported parameters.
Story-level configuration using parameters
Storybook parameters provide static metadata that controls snapshot behavior. Use the percy parameter to configure snapshot-level options.
Supported Percy Storybook parameters
In addition to common per-snapshot options, the following parameters are supported:
| Parameter | Description |
|---|---|
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. |
Additional snapshots configuration
Each additionalSnapshots element supports the following parameters:
| Parameter | Description |
|---|---|
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 configuration file options
In addition to common Percy config file options, Storybook supports the following configuration keys:
The skip and name parameters are not supported at the config file level.
Running Storybook snapshots in parallel
Storybook snapshots can be split into shards and captured on multiple machines to reduce execution time. Use the --shard-count option to divide all snapshots evenly into a specified number of shards, or use --shard-size to split snapshots based on the number of snapshots per shard. The --shard-index option tells the SDK which shard to capture on a given machine. For example, to split snapshots into three shards—each capturing approximately one-third of the snapshots—run the following commands on different machines in parallel:
That way your snapshots capture up to three 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 supports interactive tests using the play function. Percy captures these snapshots without additional configuration.
If Percy captures the snapshot before interactions complete, use waitForSelector to delay capture until the interaction finishes.
Mock Service Worker (MSW) support
Percy supports capturing API responses mocked with Mock Service Worker (MSW).
Enable this by adding captureMockedServiceWorker: true to your Percy configuration file.
MDX support
Percy supports visual testing for Storybook MDX documentation pages, allowing you to track visual changes in component docs and guidelines.
This feature is available starting with @percy/storybook version 9.1.0.
Enable MDX snapshots
Enable one of the following environment variables to start capturing snapshots of your documentation pages.
- For standard
.mdxdocumentation pages if you write documentation in standalone .mdx files, use thePERCY_STORYBOOK_DOC_CAPTUREflag.
- For auto-generated documentation pages (“Autodocs”)
If you want to capture the auto-generated documentation pages that Storybook creates for your components, use the
PERCY_STORYBOOK_AUTODOC_CAPTUREflag.
You can enable both flags at the same time if you use both documentation types.
Limitations and considerations
Percy MDX snapshotting comes with a few important limitations and considerations to keep in mind.
Snapshot-level configuration
Storybook does not support defining story-level parameters within .mdx files. Therefore, you cannot use the percy parameter block to apply specific configurations to an MDX snapshot. For example, the following code block within a story does not apply to an .mdx page:
As a workaround, Percy applies all global configurations defined in your configuration file (for example, percy.yml) to MDX snapshots.
Version compatibility
- MDX snapshot support requires Storybook v7 or later
- MDX snapshot support is not available for Storybook v6
Related topic
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!