Storybook for Vue.js
Visual testing for Storybook for Vue.js
This adds Percy visual testing and review to your Storybook for Vue. 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.
- Add as a dev dependency:
npm i --save-dev @percy-io/percy-storybook
- Open your package.json, and add a script:
"snapshot": "build-storybook && percy-storybook --widths=320,1280"
- Update your .storybook/config.js:
Adjust the existing line that imports @storybook/vue
:
// On the line that imports from @storybook/vue, add getStorybook and setAddon
import { configure, getStorybook, setAddon } from '@storybook/vue';
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.
Usage
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. 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:
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 adirection=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.
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:
"snapshot": "build-storybook && percy-storybook --width=320,1280 --debug"
Run npm run snapshot
again, and email the output to [email protected].
Contributing
- Fork it ( https://github.com/percy/percy-storybook/fork )
- Create your feature branch (
git checkout -b my-new-feature
) - Commit your changes (
git commit -am 'Add some feature'
) - Push to the branch (
git push origin my-new-feature
) - Create a new pull request
Updated over 4 years ago