Skip to main content

Setting Up Visual Component Testing with Storybook

Screener Docs are Now Sauce Docs
As part of our efforts to bring you a single, unified documentation site, we've migrated all Visual Docs from Screener.io to Sauce Docs.

Follow this quickstart guide to integrate Sauce Labs Visual Component Testing (Screener) with Storybook, a UI component development tool.

Our Storybook integration will run your existing Storybook stories as UI regression test cases in our automated visual testing platform, which can accelerate debugging and shorten release cycles. You'll get detailed UI test results across your React, Vue, Angular, and HTML components.

What You'll Need#

Confirm Screener Installation#

  1. First, confirm that Storybook is installed correctly on your local machine by running npm run storybook.
New to Storybook?

If you've never used Storybook, follow the steps below to install it and create your first project. Then proceed to step 1.

Install Storybook

Open a terminal and run the following commands, one at a time.

Installs Storybook and Creates Storybook Project Called 'my-storybook'
npx create-react-app my-storybook
Navigates to Storybook Project
cd my-storybook
Initializes Storybook
npx -p @storybook/cli sb init
Launches Your Storybook Project
npm run storybook

Install Screener Package#

  1. From your terminal, navigate to the file path where you downloaded your Storybook sample project (i.e., cd my-storybook or cd downloads/my-storybook).

  2. Install the screener-storybook package as a dependency in your project:

    npm install screener-storybook --save-dev

Set Environment Variables#

  1. In your terminal, set your Screener API key as an environment variable:

    export SCREENER_API_KEY="REPLACE WITH SCREENER API KEY"

Create Screener Config File#

  1. Create a new JavaScript file, name it screener.config.js, and save it to the root folder of your Storybook project.

  2. Choose one the two options:
    a. If you're using the my-storybook sample project, copy and paste this code snippet into your screener.config.js file, then save it.

    module.exports = {  projectRepo: 'sb-6.1-test',  storybookConfigDir: '.storybook',  apiKey: process.env.SCREENER_API_KEY,  resolution: '1024x768'};

    b. If you're integrating Visual Component Testing into your own Storybook project, copy and paste this code snippet into your screener.config.js file, then replace the placeholder values with your own. projectRepo is the name of your project's repository (e.g., GitHub repos are in the "owner/repository-name" format) and resolution is your desired browser resolution.

    storybookConfigDir/storybookStaticDir are your Storybook server options; you may not need to add both. In your project directory, find the start-storybook command, usually a script in package.json file. If the -c or --config-dir option is set, add storybookConfigDir and that value to your code snippet. If the -s or --static-dir option is set, add the storybookStaticDir with its value.

    module.exports = {  projectRepo: '<your-repo>',  storybookConfigDir: '<directory>',  storybookStaticDir: '<directory>',  apiKey: process.env.SCREENER_API_KEY,  resolution: '<resolution>'};

Add Screener Script#

  1. Open your project's package.json file and add the following npm script to "scripts": { section:
    "scripts": {   "test-storybook": "screener-storybook --conf screener.config.js"}  

Run Test#

  1. Run your test with the following command:
    npm run test-storybook

View Results#

  1. Log in to Visual Testing Dashboard (Sauce Labs > SAUCE APPS > Visual > Login) to view your running test in progress. This initial test will be labeled as failed because there's no preexisting baseline state to compare against. To resolve this, review and accept the new states as the baseline.

    For each build, you should receive an email summary indicating the pass/fail status, delivered to the address associated with your Sauce Labs account.

More Information#

Next Steps#

Related Links#