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

Run the interactive CLI setup​

To configure your project for Applitools Eyes, run the setup tool:

npx eyes-setup

The CLI will:

  • Configure your project for Applitools Eyes.
  • Adds default configuration properties to an applitools.config.js file located in your projects root directory.
info

You will be prompted to enter your Eyes Server URL. If you are using the Applitools public cloud, your server URL will be https://eyes.applitools.com. If you're using a private deployment, enter your account's server URL instead.

Set your Applitools API key​

When prompted by the CLI, enter your Applitools API key. If you don't have one, you can sign up for a free account and obtain your API key. For details on how to retrieve your API key, see the Retrieve Your API KEY documentation.

Alternatively, you can set the API key as an environment variable:​

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>

See all available environment variables.

Using the Storybook SDK​

After completing the installation and defining the API key, you will be able to execute npx eyes-storybook from the command line and it will capture 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

Baseline Attributes in Storybook​

Eyes uses the following test and execution environment attributes to identify a baseline. Any changes to these values will generate a new baseline for your stories in Eyes.

  • appName - The default Applcation Name is the "name" of your Storybook project in your package.json file.
    • You can override this value in your applitools.config.js file.
  • testName – The default Test Name is the path to and name of each story. Example: {component directory}/src/{component name}:{story name}.
  • Viewport size – The default value is 1024x768 for each component.
    • You can override this value in your applitools.config.js file by specifying the browsers, viewports, or devices you want to validate.
  • Host OS – The default value is Linux.
    • You can override this value based on the browsers or devices you configure in your applitools.config.js file.
  • Browser – The default value is Chrome.
    • You can override this value based on the browsers or devices you configure in your applitools.config.js file.
info

When testing multiple Themes or Varients, the eyes-storybook SDK will automatically create unique baselines for each theme.

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]
  -v, --version                                         Show the version number                                                                                [boolean]
  -f, --conf                                            Path to applitools.config.js config file                                                                [string]
  -u, --storybookUrl, --storybook-url                   URL to storybook                                                                                        [string]
  -p, --storybookPort, --storybook-port                 Port to run Storybook                                                                                   [number]
  -h, --storybookHost, --storybook-host                 Host to run Storybook                                                                                   [string]
  -c, --storybookConfigDir, --storybook-config-dir      Path to Storybook's config folder (defaults to .storybook)                                              [string]
  -s, --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]
      --include                                         A string that represents a story title or a regex (starts and ends with /) to match stories title       [string]
      --networkBlockPatterns, --network-block-patterns  Patterns to block from network requests                                                                  [array]
      --browserCacheRequests, --browser-cache-requests  Intercept and cache requests coming from the browser                                                   [boolean]
      --navigationWaitUntil, --navigation-wait-until    When to consider navigation to be finished          ["load", "domcontentloaded", "networkidle0", "networkidle2"]
  -e, --exitcode                                        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.

applitools.config.js example:

module.exports = {
  apiKey: process.env.APPLITOOLS_API_KEY,
  serverUrl: 'https://eyes.applitools.com',
  showLogs: false,
  batchName: 'My Storybook',
  testConcurrency: 5
  ...
  // all other configuration variables apply
}

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.

Puppeteer has reported issues when using Alpine 3.20 so you may need to use Alpine 3.19 to get the browser to launch correctly if you see issues with tests not running. See here. We have also seen this as an issue on Alpine 3.21.

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

Need help?​

Having Trouble?

Don't suffer in silence! Let us help you. Please reach out to us to get your project working.