@percy/storybook
Advanced tools
Percy is an all-in-one visual testing and review platform. It captures screenshots, compares them against the baseline, and highlights visual changes. With increased visual coverage, teams can deploy code changes with confidence with every commit.
Storybook supports cross-browser visual testing natively using Percy. You can use Percy for visual testing of web applications on desktop and mobile browsers.
Sign up here to get started with Percy for free.
The benefits of utilizing Percy for visual testing include the following:
Percy compares new snapshots against relevant baselines to detect visual changes. Percy manages baseline selection across branches so your tests are always relevant. If visual changes are detected, Percy highlights and groups the resulting diffs for you to review.
Percy’s sample build tutorial for Storybook.
$ npm install --save-dev @percy/cli @percy/storybook
PERCY_TOKEN
is properly configured.
# Unix
$ export PERCY_TOKEN="<your-project-token>"
# Windows
$ set PERCY_TOKEN="<your-project-token>"
# Powershell
$ $Env:PERCY_TOKEN="<your-project-token>"
With a static Storybook build:
$ percy storybook ./storybook-build
With a local or live Storybook URL:
$ percy storybook http://localhost:9009
$ percy storybook https://storybook.foobar.com
Automatically run start-storybook:
$ percy storybook:start --port=9009 --static-dir=./public
percy storybookSnapshot static or hosted Storybook stories
Usage:
$ percy storybook [options] <url|directory>
Arguments:
url|directory Storybook url or build output directory
Subcommands:
storybook:start [options] Run start-storybook to snapshot stories
help [command] Display command help
Options:
-i, --include <pattern> Pattern matching story names to include in snapshots
-e, --exclude <pattern> Pattern matching story names to exclude from snapshots
--shard-count <number> Number of shards to split snapshots into
--shard-size <number> Size of each shard to split snapshots into
--shard-index <index> Index of the shard to take snapshots of
--partial Marks the build as a partial build
Percy options:
-c, --config <file> Config file path
-d, --dry-run Print snapshot names only
-h, --allowed-hostname <hostname> Allowed hostnames to capture in asset discovery
--disallowed-hostname <hostname> Disallowed hostnames to abort in asset discovery
-t, --network-idle-timeout <ms> Asset discovery network idle timeout
--disable-cache Disable asset discovery caches
--debug Debug asset discovery and do not upload snapshots
Global options:
-v, --verbose Log everything
-q, --quiet Log errors only
-s, --silent Log nothing
--help Display command help
Examples:
$ percy storybook ./build
$ percy storybook http://localhost:9000/
percy storybook:startRun start-storybook to snapshot stories
Usage:
$ percy storybook:start [options]
Options:
-i, --include <pattern> Pattern matching story names to include in snapshots
-e, --exclude <pattern> Pattern matching story names to exclude from snapshots
--shard-count <number> Number of shards to split snapshots into
--shard-size <number> Size of each shard to split snapshots into
--shard-index <index> Index of the shard to take snapshots of
--partial Marks the build as a partial build
--port [number] Port to start Storybook (default: 9000)
--host [hostname] Host to start Storybook (default: "localhost")
Percy options:
-c, --config <file> Config file path
-d, --dry-run Print snapshot names only
-h, --allowed-hostname <hostname> Allowed hostnames to capture in asset discovery
--disallowed-hostname <hostname> Disallowed hostnames to abort in asset discovery
-t, --network-idle-timeout <ms> Asset discovery network idle timeout
--disable-cache Disable asset discovery caches
--debug Debug asset discovery and do not upload snapshots
Global options:
-v, --verbose Log everything
-q, --quiet Log errors only
-s, --silent Log nothing
--help Display command help
Examples:
$ percy storybook:start
$ percy storybook:start --port 9000
$ percy storybook:start --static-dir public
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.
// individual stories
MyStory.parameters = {
percy: { ... }
};
// .storybook/preview.js
export const parameters = {
percy: { ... }
};
The following percy Storybook parameters are accepted in addition to common per-snapshot
options:
${story.kind}: ${story.name})MyStory.parameters = {
percy: {
name: 'My snapshot',
additionalSnapshots: [
{ prefix: '[Dark mode] ', args: { colorScheme: 'dark' } },
{ suffix: ' with a search', queryParams: { search: 'foobar' } }
]
}
};
With this example, 3 snapshots will be taken of this story with args and query params appended to the URL of each snapshot:
# --dry-run will log snapshots without creating a new build
# --verbose will show debug logs, including the snapshot url
$ percy storybook --dry-run --verbose ./example-storybook
# ...
[percy] Snapshot found: My snapshot
[percy] -> url: [...]?id=component--my-story
[percy] Snapshot found: [Dark mode] My snapshot
[percy] -> url: [...]?id=component--my-story&args=colorScheme:dark
[percy] Snapshot found: My snapshot with a search
[percy] -> url: [...]?id=component--my-story&search=foobar
In addition to common Percy config file options, this SDK also adds the following Storybook specific options:
# .percy.yml
version: 2
storybook:
args: {}
globals: {}
queryParams: {}
waitForTimeout: 0
waitForSelector: ''
additionalSnapshots: []
include: []
exclude: []
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).
Prior versions of the Storybook SDK were drastically different than the current version. The
command, it's arguments, and how the SDK works internally have changed completely. Using the old
command with new versions will now result in an error message. The new command is now integrated into
@percy/cli as a plugin.
To use new versions of this SDK, you will have to also install the CLI with the SDK:
$ npm install --save-dev @percy/cli @percy/storybook
Since both the command and arguments have changed, you'll need to replace your existing usage with the new usage described above. For some projects, this may require setting additional configuration options. See the list of breaking changes below for details.
Most importantly, the command itself has changed and all previous arguments are no longer accepted.
The percy-storybook command has been replaced with a percy CLI
subcommand, percy storybook.
The previous --build_dir flag is now a command argument and there is no default build directory. If
you relied on the default, it must now be explicitly provided.
# before
$ percy-storybook
# after
$ percy storybook ./storybook-static
# before
$ percy-storybook --build_dir ./build
# after
$ percy storybook ./build
The --widths flag is no longer accepted. Widths can be set using the respective widths
Percy config file snapshot option or
percy Storybook parameter.
The --minimum_height flag is no longer accepted and therefore no longer defaults to
800px. The default minimum height shared by all SDKs is 1024px. The minimum height can be
set using the respective min-height Percy config file snapshot
option or percy Storybook parameter.
The --debug flag is now --verbose, inherited from the CLI.
The --output-format flag is no longer accepted and has no alternative. If you relied on this
flag, please open an issue.
The --rtl and --rtl_regex flags are no longer accepted. The --rtl flag duplicated stories
and set the direction=rtl query parameter for the duplicate's URL. The --rtl_regex flag was
used to determine when to create this RTL duplicate story.
// .storybook/preview.js
export const parameters = {
percy: {
// tell percy to take an additional RTL snapshot for matching stories
additionalSnapshots: [{
suffix: ' [RTL]',
queryParams: { direction: 'rtl' },
include: ['^FormElement: .*']
}]
}
};
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.
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.
prepare-storybook-v6-tests.sh file for more details around changes for storybook v6 testing.FAQs
Storybook addons for visual testing with Percy
The npm package @percy/storybook receives a total of 25,681 weekly downloads. As such, @percy/storybook popularity was classified as popular.
We found that @percy/storybook demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
PyPI confirms no security flaws were exploited in the Ultralytics supply chain attack and highlights improvements for safer package publishing.
Security News
Research
The Socket Research Team breaks down a malicious wrapper package that uses obfuscation to harvest credentials and exfiltrate sensitive data.
Research
Security News
Attackers used a malicious npm package typosquatting a popular ESLint plugin to steal sensitive data, execute commands, and exploit developer systems.