Sign in or start for free
Hey! These docs are for version 1, which is no longer officially supported. Click here for the latest version, 2-web!

### [percy-storybook on GitHub ](🔗)

[![Package Status](https://img.shields.io/npm/v/@percy-io/percy-storybook.svg)](🔗) [![Build Status](https://travis-ci.org/percy/percy-storybook.svg?branch=master)](🔗)

This adds [Percy](🔗) visual testing and review to your [Storybook for Angular](🔗). It's great for taking snapshots of your components in isolation from your application. If you'd like to take snapshots of your application, take a look at our [Puppeteer SDK](🔗).

# Installation





Make sure you have completed [Setup](🔗) of your CI service first. You can also test Percy in your [local development](🔗) environment.

  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/angular`:


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

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


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.
# Usage

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

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.
# 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](🔗).
# 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:

## 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](🔗).
# Percy-specific CSS

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.
# Source code integration

Percy automatically integrates with your source code so you can do visual reviews with each commit or pull request. See our source code integration docs for more info.
  • [GitHub](🔗) 
  • [GitHub Enterprise](🔗) 
  • [GitLab](🔗) 
  • [GitLab self-managed](🔗) 
  • [Bitbucket](🔗) 
# Troubleshooting

## 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:

Run `npm run snapshot` again, and email the output to <[[email protected]](🔗)>.
# Contributing

  1. Fork it ( <https://github.com/percy/percy-storybook/fork> )
  2. Create your feature branch (`git checkout -b my-new-feature`)
  3. Commit your changes (`git commit -am 'Add some feature'`)
  4. Push to the branch (`git push origin my-new-feature`)
  5. Create a new pull request
[Throw a ★ on it!](🔗)