Sauce Labs Visual Storybook Integration

An extension for Storybook's test-runner to integrate effortless visual testing with Sauce Labs Visual.

Compatibility

This package leverage's Storybook's test-runner and metadata generation system for enabling automatic testing of Storybook stories. We recommend running Storybook ^7.0.0 and an up-to-date version of the Storybook test-runner (>=0.13.0 at time of writing).

Getting Started

1. Follow Storybook's instructions for setting up, installing, and configuring the test-runner if you haven't done so already. If you have already used or enabled the test-runner, you can skip this step.

2. Install the saucelabs visual-storybook plugin:

npm i -D @saucelabs/visual-storybook

3. Eject your test-runner config and append the Sauce Visual storybook configuration:

If you already have a custom config file for the test-runner you can skip to the next step for appending our configuration bootstrap. If not see below or read through the docs to eject the default test configuration.

npx test-storybook --eject

The above should have created a file in the root directory, test-runner-jest.config.js. Edit this file and add an import for the sauce visual plugin: const { getVisualTestConfig } = require('@saucelabs/visual-storybook');, then append ...getVisualTestConfig(), below the jest config spread. Your file should look similar to the example below:

// test-runner-jest.config.js
const { getJestConfig } = require('@storybook/test-runner');
const { getVisualTestConfig } = require('@saucelabs/visual-storybook');

/**
 * @type {import('@jest/types').Config.InitialOptions}
 */
module.exports = {
  // The default configuration comes from @storybook/test-runner
  ...getJestConfig(),
  // The configuration for Sauce Lab's Visual Integration
  ...getVisualTestConfig(),
  /** Add your own overrides below
   * @see https://jestjs.io/docs/configuration
   */
};

4. Create a test-runner.js file in your storybook configuration directory (<root>/.storybook by default) if you do not already have one, and append our postRender hook into it. You can read more about this file in the hook API section. It should look something like below:

// .storybook/test-runner.js
const { postRender } = require('@saucelabs/visual-storybook');

module.exports = {
  postRender,
};

5. Run your Storybook instance (or point to a built one), set the required environment variables (see here for all available / required fields), and run the test-runner! We'll take snapshots of all known Storybook stories and upload them into Sauce Visual.

# Spin up your storybook instance in a separate terminal window if you're not using a live / 
# hosted one
npm run storybook

# Export your username and access key or set them in your CI variables. You can get these from 
# app.saucelabs.com
export SAUCE_USERNAME=__YOUR_SAUCE_USER_NAME__
export SAUCE_ACCESS_KEY=__YOUR_SAUCE_ACCESS_KEY__

# Run the storybook command! Note: if you're running against a non-standard port or URL, you'll 
# need to supply the --url parameter followed by the root url for your storybook instance. See the
# test-runner docs for more details / examples of config parameters. 
# ex: --url http://localhost:6006
npx test-storybook

6. Review your changes in the Sauce Labs Visual Dashboard!

Customizing Your Builds (Environment Variables)

Below are the environment variables available in the visual-storybook plugin: