Storybook for Ember

Visual testing for Storybook for Ember

📘

For Storybook v4 and earlier

This documentation is for @percy-io/percy-storybook v2, which works with Storybook v4 and earlier. For Storybook v5, see the documentation for the current @percy/storybook package.

👍

Covered in this doc

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

Package Status Build Status

Our Storybook for Ember SDK is great for taking snapshots of your components in isolation from your application. If you use Ember without Storybook see our Ember page.

Setup


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

Adjust the existing line that imports @storybook/ember:

// On the line that imports from @storybook/ember, add getStorybook and setAddon
import { configure, getStorybook, setAddon } from '@storybook/ember';

Still in config.js, add the following before calling configure to configure your stories:

import createPercyAddon from '@percy-io/percy-storybook';
const { percyAddon, serializeStories } = createPercyAddon();
setAddon(percyAddon);

Finally, add the following at the end of your config.js file:

// NOTE: if you're using the Storybook options addon, call serializeStories *BEFORE* the setOptions call
serializeStories(getStorybook);

📘

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.

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 set up 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. You'll want to add storybook-static to your .gitignore file if you run this locally.

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 basis by adding stories with addWithPercyOptions instead of add. These options will trump the Global Options specified for the storybook.

addWithPercyOptions takes 3 parameters: the story name, the percyOptions, and the story function. If you've been calling add to add the story previously, simply change it to addWithPercyOptions and insert percyOptions as the second parameter.

Available options:

  • widths - An array of widths as integers for this story.
  • 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.

Examples:
Have a look at the storybook in percy-storybook for an example of how to use .addWithPercyOptions. including ways to use it in conjunction with other add-ons. Here's a simple example:

storiesOf('My basic span', module)
  .addWithPercyOptions('with multiple widths', { widths: [222, 333], rtl: true }, () =>
    <span>This span renders in widths of 222px and 333px</span>,
  )

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].


What's next

Once you've set up Percy for Storybook, the next step is to add Percy to your CI service. That way, every time CI runs, Percy will automatically kick off visual tests as well.