Storybook v3

👍

Covered in this doc

• How to add Percy to your Storybook for visual testing and reviews
• Configuration and troubleshooting for Percy for Storybook

@percy/storybook on GitHub 

Our Storybook SDK is great for taking snapshots of your components in isolation from your application. By default, it captures each story you have setup in Storybook. It supports all frameworks Storybook itself supports, including in React, Vue.js, Ember, and Angular.

If you'd like to take snapshots of your full application rather than components in isolation, take a look at our Puppeteer SDK.

📘

For Storybook v5 and above

These instructions apply to our most recent version of @percy/storybook, which requires Storybook v5 or newer. If you'd like to see instructions for Storybook v4 and below, see our Storybook docs for React, Vue.js, Angular, and Ember.

Setup

1. Add as a dev dependency: npm i --save-dev @percy/storybook
2. Open your package.json, and add a script: "snapshot": "build-storybook && percy-storybook --widths=320,1280"

Before you can successfully run Percy, the PERCY_TOKEN environment variable must be set:

# Windows
$ set PERCY_TOKEN=<your token here>

# Unix 
$ export PERCY_TOKEN=<your token here>

After you've setup the PERCY_TOKEN environment variable, run:

$ npm run snapshot

This will run Storybook's build-storybook command to create a static site from your storybook, and will upload your stories to Percy to generate screenshots from them. Storybook defaults to building the static site in storybook-static, so you'll want to add that folder to your .gitignore file if you run this locally.

📘

Percy Storybook uses headless Chrome process your stories. It’s often installed automatically in your CI environment for you, but if you need help, please ask.

Configuration 

Global options

These options can be appended to the percy-storybook command in the script tag in your package.json file:

• widths - Specify multiple widths to screenshot your stories at. eg. --widths=320,1280
• minimum_height - Specify the minimum height of story screenshots. eg. --minimum_height=300
• build_dir - By default, percy-storybook looks for the static storybook in the storybook-static directory. If you use build-storybook with a custom output directory, use build_dir instruct percy-storybook where to find it. eg. --build_dir=my-static-storybook
• rtl - Process all stories a second time in RTL. eg. --rtl
• rtl_regex - Process stories with matching names a second time in RTL. eg. --rtl_regex=unidirectional
• debug - Provides additional debugging information. eg. --debug

Per-story options

You can override options on a per-story or story-group basis with Storybook's option parameters. These options will override the global options specified in the script command.

Options can be provided in a percy object in story parameters, either as the 3rd argument to the add function, or with Storybook's addParameters function. i.e.:

// add Percy parameters to a single story via add's 3rd argument.
storiesOf('Circle Stories', module)
  .add(
    'with multiple widths',
    () => <span>This span renders in widths of 222px and 333px</span>,
    { percy: { widths: [222, 333] } }
  );

// OR

// add parameters to all Square Stories with addParameters.
storiesOf('Square Stories', module)
  .addParameters({ percy: { widths: [222, 333], rtl: true } });
  .add(
    'with multiple widths',
    () => <span>This span renders in widths of 222px and 333px</span>,
  );

storiesOf('Square Stories', module)
  .addParameters({ percy: { minHeight: 15000 } });
  .add(
    'with minHeight',
    () => <span>This span renders in with a height of 1500px</span>,
  );

// OR

// apply parameters to all stories with addParameters in your config.js.
import { configure, setAddon, addParameters } from '@storybook/react';
addParameters({ percy: { widths: [320, 800] } });

Available options:

• widths - An array of widths as integers for this story.
• minHeight - The minimum height you'd like your snapshots to render at
• rtl - A boolean value specifying whether this story should additionally be run in a RTL direction.
• skip - A boolean value specifying whether this story should be skipped (default: false). You might want to use this for stories that use Storybook's knobs addon.

RTL Direction Support

Percy supports taking screenshots of your stories a second time in the RTL direction.

• To process all stories in the RTL direction, use the --rtl option. To process only a subset in RTL, use the --rtl_regex option and provide a regex that will match the names of the stories you want to capture in RTL.
• Stories you have selected for RTL processing will be processed twice. Once normally, and then a second time with [RTL] appended to their name, and with a direction=rtl url param provided.
• It's up to the stories to process the direction url param and respond appropriately. You can see a basic example of how this can be done in our Direction Demo test story.

Troubleshooting

Freezing time and dynamic data

As you start to introduce visual testing into your workflow, you might find that the passing of time or generated data from tools like faker can cause visual diffs.

It's fairly easy to stabilize these diffs. Tools like faker often allow you to provide a seed to ensure that the same data is generated each time faker is run. Libraries like MockDate allow you to override the current date, eliminating variations due to the screenshots being taking at a different date and time. If you use Math.random, you can seed it with seedrandom.

Percy provides an inPercy function that you can use in your Storybook's config.js if you'd prefer that these adjustments only have an effect when running in Percy's rendering environment. Add the @percy-io/in-percy package if you'd like to use inPercy.

You can see an example of how this type of stabilization can be done in this storybook/config.js.

Hiding regions

If you use Percy-specific CSS to override CSS in Percy, add the @media only percy code inside a style tag in your preview-head.html file to ensure that it will be applied in the Percy rendering environment.

Debugging locally

If you're seeing different screenshots on Percy from what you see in Storybook locally, you'll find build-storybook helpful.

During installation, you added the "snapshots" script command "build-storybook && percy-storybook --widths=320,1280". The first half of that, build-storybook, is a built-in Storybook command to convert your storybook to a set of static assets in a folder called storybook-static.

Inside storybook-static you'll find an index.html file. Open index.html in your browser, and you'll see the exact storybook that Percy receives and renders screenshots from. Reviewing this locally as you make configuration changes can help with troubleshooting, and shorten the debugging cycle. After you make changes, you can re-run build-storybook, and refresh index.html to see if you've resolved the issue.

If the built storybook differs from what you see when viewing the live storybook, it may be due to a configuration issue. Perhaps you need to supply build-storybook with the -c option to provide a different config-dir, or supply the -s option to specify a different static folder. i.e. "build-storybook -c my_storybook -s my_static_folder && percy-storybook --widths=320,1280"

Storybook object not found on window

If you see an error message Storybook object not found on window. and followed all of the installation instructions, then please add the debug flag to the script command in your package.json file:

  "snapshot": "build-storybook && percy-storybook --width=320,1280 --debug"

Run npm run snapshot again, and email the output to [email protected].