Skip to main content

Storybook Overview

Applitools Eyes SDK for Storybook.

Installation​

Install npm package​

Install Eyes-Storybook as a local dev dependency in your tested project:

npm install --save-dev @applitools/eyes-storybook

Entering the Applitools API key​

To authenticate via the Applitools server and run tests, you need to set the environment variable APPLITOOLS_API_KEY to the API key provided from Applitools Eyes. For details on how to retrieve your API key, see the Applitools documentation.

Entering the API Key on Linux or a Mac​

export APPLITOOLS_API_KEY=<API_key>

Entering the API Key on Windows​

set APPLITOOLS_API_KEY=<API_key>

Using the Storybook SDK​

After completing the installation and defining the API key, you will be able to run Eyes-Storybook from the command line and let it take screenshots of all your stories.

If your project uses the default storybook config folder (<project_folder>/.storybook), then run the following command:

npx eyes-storybook

Configuring local storybook server​

By default, Eyes-Storybook starts a Storybook dev server in an available port between 9000-9010 for the duration of the tests. You can pass arguments to Eyes-Storybook to configure the local storybook server:

  • --storybook-port OR -p: Port to run storybook (passed as -p to start-storybook).
  • --storybook-host OR -h: Host to run storybook (passed as -h to start-storybook).
  • --storybook-config-dir OR -c: Directory where to load Storybook configurations from (passed as -c to start-storybook)
  • --storybook-static-dir OR -s: Directory where to load static files from, comma-separated list (passed as -s to start-storybook)

Standalone server​

As noted in the previous section, Eyes-Storybook starts a storybook dev server. If you want to start the server outside the Storybook dev server, or test a production build that is available at a certain URL, specify the URL for the Storybook in the command line (or in the applitools.config.js file).

For example:

npx eyes-storybook -u http://localhost:6006

Or for a production Storybook:

npx eyes-storybook -u http://react.carbondesignsystem.com/

Command line arguments​

Following are common command line arguments. For a full list of command line arguments, run npx eyes-storybook --help.

Usage: eyes-storybook.js [options]

Options:
  --help                                            Show help                                                                       [boolean]
  --version, -v                                     Show the version number                                                         [boolean]
  --conf, -f                                        Path to applitools.config.js config file                                         [string]
  --storybook-url, -u                               URL to storybook                                                                 [string]
  --storybookPort, -p, --storybook-port             Port to run Storybook                                                            [number]
  --storybookHost, -h, --storybook-host             Host to run Storybook                                                            [string]
  --storybookConfigDir, -c, --storybook-config-dir  Path to Storybook's config folder (defaults to .storybook)                       [string]
  --storybookStaticDir, --storybook-static-dir      Path to Storybook's static files folder                                          [string]
  --showStorybookOutput, --show-storybook-output    Whether or not you want to see Storybook output                                 [boolean]
  --readStoriesTimeout, --read-stories-timeout      The time to wait until all stories are read, before starting the visual tests    [number]
  --exitcode, -e                                    If tests failed close with non-zero exit code                                   [boolean]

Concurrency​

The default level of concurrency for free accounts is 5. This means that only up to 5 visual tests can run in parallel, and therefore the execution might be slow. If your account supports a higher level of concurrency, you can pass a different value in the testConcurrency property in the applitools.config.js file.

If you are interested in speeding up your visual tests, contact sdr@applitools.com to get a trial account and faster tests with more concurrency.

Running Eyes-Storybook in Docker​

When running the SDK in Docker, there might be issues related to properly launching the internal Chrome browser using Puppeteer. If you experience problems, , set runInDocker: true in your configuration file. This will pass the internal chrome browser special arguments, as described here.

If you still have issues, you might need to follow the instructions to use your own Chromium browser in the Docker container, and point that to the SDK's Puppeteer. Follow the instructions here and set the executablePath via the puppeteerOptions.

Example​

applitools.config.js
module.exports = {
  puppeteerOptions: {
    executablePath: '/usr/bin/chromium-browser'
  }
}

Dealing with dynamic data​

Sometimes components render dynamic data, such as dates, or random data. This creates a challenge when testing these components. If you have dynamic data, we recommend to insert code into your storybook which normalizes the data (uses fixed dates, or a specific seed), when it is being run in an automated environment.

Eyes Storybook makes it possible for components to be aware that they are being tested. There will be a specific query parameter on the URL of the story's iframe: ?eyes-storybook=true.

This way you can write a story like this:

const isBeingTested =
    new URL(window.location).searchParams.get('eyes-storybook')

const SOME_FIXED_DATE = 354060000000

const date = new Date(isBeingTested ? SOME_FIXED_DATE : undefined)

storiesOf('Some kind', module).add('Date', () => <div>{date}</div>)

Storybook interactions Play functionality​

As of Storybook-Eyes SDK version 3.28.0, there is support for Storybooks' Interactions Play functionality. For stories that use 'Play', screenshot will be taken automatically after the 'Play' flow is done. This will replace the existing point of taking screenshots, it should not affect any new or existing stories which do not use the 'Play' functionality. For tests that use the waitBeforeCapture property, the wait period will begin after the 'Play' flow is complete. For additional information, see https://storybook.js.org/docs/react/essentials/interactions