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
You can enable MDX snapshot capture using percy.yml configuration, doc/pattern level rules, or global configuration rules.
percy.yml level flags
You can use the following rules in percy.yml file to enable capturing snapshots of your documentation pages.
- For standard
.mdxdocumentation pages if you write documentation in standalone .mdx files, use thecaptureDocsvariable.
- For auto-generated documentation pages (“Autodocs”)
If you want to capture the auto-generated documentation pages that Storybook creates for your components, use the
captureAutodocsflag.
Doc/pattern level rules
Full reference example
This example demonstrates a complete .percy.yml configuration with all MDX snapshot options, including global flags and doc-level.
Global environment flags
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.
Configuration precedence
Percy applies configuration settings in the following order, with each level overriding as follows:
- When a doc or pattern rule exists for a specific doc ID, that rule takes precedence even if higher-level flags are set to
false. - A flag defined in
.percy.yml(for example,captureDocs: false) overrides a global environment flag set totrue. - If
.percy.ymldoes not specifycaptureDocsorcaptureAutodocs, Percy consults the global environment flags.
Rule-level parameters
These parameters follow the same behavior as the corresponding Storybook story-level settings.
capture: true|falsewidths: [ ... ]responsiveSnapshotCapture: true|falseenableJavaScript: true|false- (Any possible parameters which are being used for stories as well)
- Percy supports the legacy global environment flags
PERCY_STORYBOOK_DOC_CAPTUREandPERCY_STORYBOOK_AUTODOC_CAPTURE, but these features are planned for deprecation. - For deterministic behavior, use
.percy.ymlsettings (storybook.captureDocsandstorybook.captureAutodocs) and per-doc or pattern rules underdocs.*.rules. - Docs and Autodocs are independent. You can enable both flags at the same time if you use both documentation types.
Examples and Use Cases
Example 1. Pattern-level capture: false overrides global captureDocs: true
The system ignores docs whose IDs match components-*, even though captureDocs: true is set globally.
Example 2. Pattern-level capture: true forces capture even when captureDocs: false
The system captures components-button--docs at the specified widths, even though global doc capture is disabled.
Example 3. Widths-only rule (no capture): widths apply only when capture occurs
The system captures components-modal--docs because captureDocs: true is enabled and applies the specified widths. If captureDocs is false and no other rule enable capture, the widths have no effect.
Example 4. Array of patterns with ? and * wildcards
This rule matches configure, configare, configyre- and similar IDs (because ? matches one character). The * wildcard matches any sequence of characters (including empty).
Example 5. Capture-all pattern
This rule captures all docs and overrides higher-level defaults.
Example 6. First match wins (rule order matters)
The system does not capture components-button-* because the first rule, components-* already matched and sets capture: false. To capture buttons, place the components-button-* rule before the broader components-* rule.
Example 7. A single pattern rule with capture: true is self-sufficient.
This rule works without any global setting. It enables capture on its own.
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!