Storybook test configuration

You can specify test configuration using one of the following methods:

• Command line arguments
• Set environment variables
• Modify the applitools.config.js file

If you specify a property as an environment variable, it will override the value defined for the same property in the applitools.config.js file.

Set Environment variables

The name of the corresponding environment variable is in uppercase, with the APPLITOOLS_ prefix, and separating underscores instead of camel case:

APPLITOOLS_APP_NAME
APPLITOOLS_SHOW_LOGS
APPLITOOLS_BATCH_ID
APPLITOOLS_BATCH_NAME
APPLITOOLS_BATCH_SEQUENCE_NAME
APPLITOOLS_PROXY
APPLITOOLS_NOTIFY_ON_COMPLETION
...
// all other configuration variables apply as well..

Modify the applitools.config.js file

You can set the properties listed below in a file called applitools.config.js located in the current working directory (the directory you are at when running the eyes-storybook script). In this file specify the desired configuration, as an exported CommonJS module. For example:

module.exports = {
  appName: 'My app',
  showLogs: true,
  batchName: 'My batch'
  ...
  // all other configuration variables apply
}

RCA (Root Cause Analysis)

If your website has enhanced security by encoding the DOM, the RCA feature will display results as hashed values which cannot be decoded. To resolve this issue, you can used the domMapping value to link the SDK to a mapping file that can decode the hashed values to their original values:

// applitools.config.js
module.exports = {
  // ...
  domMapping: <mapping file file path, buffer, or URL>   // File path, buffer, or URL to the DOM mapping file
}

The mapping file should be in the following format:

{
    "abcd": "some-class",
    "qwerty": "other-class",
    "zxcv": "some-variable-name"
}

Properties

You can define the following configuration parameters for tests by in the applitools.config.js file. These parameters can also be set using environment variables or command-line arguments.

Property name	Default value	Description
storybookUrl	undefined	URL for Storybook (also available as command-line argument).
storybookPort	9000	Port to run Storybook (also available as command-line argument).
storybookHost	localhost	Host to run Storybook (also available as command-line argument).
storybookConfigDir	.storybook	Path to Storybook's config folder (also available as command-line argument).
storybookStaticDir	undefined	Path to Storybook's static files folder (also available as command-line argument).
showStorybookOutput	undefined	Whether or not you want to see Storybook output (also available as command-line argument).
viewportSize	{ width: 1024, height: 600}	The size of the Puppeteer browser's window. This is the browser window which renders the stories originally (and opens at the size provided in the viewportSize parameter), and then a DOM snapshot is uploaded to the server, which renders this snapshot on all the browsers and sizes provided in the browser parameter.
exitcode	true	If tests failed or has visual differences close with non-zero exit code (also available as command-line argument).
browser	{ width: 1024, height: 768, name: 'chrome' }	The size and browser of the generated screenshots. For additional information, see the Configuring the browser.
showLogs	false	Whether or not you want to see logs of the Eyes-Storybook plugin.
batch	undefined	An object which describes different aspects of the batch. The following lines in this table depict the various ways to configure the batch.
batch.id	random	Provides ability to group tests into batches. Read more about batches here.
batch.name	The name of the first test in the batch	Provides a name to the batch (for display purpose only).
batch.sequenceName	undefined	Name for managing batch statistics.
batch.notifyOnCompletion	false	If true batch completion notifications are sent.
batch.properties	undefined	Custom properties for the entire batch. The format is an array of objects with name/value properties. For example: [{name: 'My prop', value:'My value'}].
baselineEnvName	undefined	The name of the environment of the baseline.
envName	undefined	A name for the environment in which the application under test is running.
ignoreCaret	false	Whether to ignore or the blinking caret or not when comparing images.
matchLevel	undefined	The test-wide match level to use when checking application screenshot with the expected output. Possible values are Strict, Exact, Layout and Content. Read more about match levels here.
branchName	undefined	The name of the branch.
baselineBranchName	undefined	The name of the baseline branch.
parentBranchName	undefined	Sets the branch under which new branches are created.
proxy	undefined	Sets the proxy settings to be used in network requests to Eyes server. This can be either a string to the proxy URI, or an object containing the URI, username, and password. For example: {url: 'https://myproxy.com:443', username: 'my_user', password: 'my_password', isHttpOnly: false} or: "https://username:password@myproxy.com:443"
saveDiffs	false	If true, tests with diffs are saved by default as a baseline.
saveNewTests	true	If true, new tests are saved by default as a baseline.
serverUrl	Default Eyes server URL	The URL of Eyes server
compareWithParentBranch	false
ignoreBaseline	false
runInDocker	false	If you are having issues running the SDK in docker, set this flag to true. For additional information, see Running Eyes-Storybook in Docker
puppeteerOptions	undefined	Options to send to puppeteer.launch. This is a low-level configuration and should be used with great care. Example use { args: ['--no-sandbox'], headless: false, devtools: true}
puppeteerExtraHTTPHeaders	undefined	Options to send to page.setExtraHTTPHeaders. For additional information, see the Puppeteer documentation
jsonFilePath	undefined	Directory path of a results file. If set, then a JSON file is created in this directory, the file named eyes.json and contains the Eyes test results.
tapFilePath	undefined	Directory path of a results file. If set, then a TAP file is created in this directory, the file is named eyes.tap and contains the Eyes test results.
xmlFilePath	undefined	Directory path of a results file. If set, then a XUnit XML file is created in this directory, the file is named eyes.xml and contains the Eyes test results.
waitBeforeCapture	undefined	Selector, function or timeout: number - the argument is treated as time in milliseconds to wait before all screenshots. string - the argument is treated as a selector for elements to wait for before all screenshots. function - the argument is treated as a predicate to wait for before all screenshots. For per component configuration see waitBeforeCapture. Note that Eyes uses Puppeteer's page.waitForTimeout(), page.waitForSelector(), page.waitForXPath() and page.waitForFunction().
include	true	A predicate function, a string or a regular expression specifying which stories should be visually tested. Visual baselines will be created only for the components specified. The function receives an object with name, kind, storyTitle and parameters properties. For example (exclude all stories with a name that start with [SKIP]): ({name, kind, storyTitle, parameters}) => !/^\[SKIP\]/.test(name) For more information, see include.
variations	undefined	Specifies additional variations for all or some of the stories. For example, RTL. For more information, see variations.
dontCloseBatches	false	If true, batches are not closed for notifyOnCompletion.
testConcurrency	5	The maximum number of tests that can run concurrently. The default value is the allowed amount for free accounts. For paid accounts, set this number to the quota set for your account.
readStoriesTimeout	60000	The amount of time (in milliseconds) Eyes-Storybook waits for storybook to load. For old storybook versions 2 and 3, this is also the time it takes for Eyes-Storybook to acknowledge it is working on those versions. If working with Storybook version 2 or 3 we recommend making this value small (e.g. 3000)
ignoreDisplacements	false	Sets whether Test Manager should initially display mismatches for image features that have only been displaced, as opposed to real mismatches. This can also be specified per-story, see ignoreDisplacements
properties	undefined	Adds custom properties for each test. These show up in Test Manager, and tests can be grouped by custom properties. By default, Eyes-Storybook adds 2 custom properties for each test: the Component name and State of each component. Adding more properties via this config param will not override these two properties.
ignoreRegions	undefined	An array of regions to ignore when comparing the checkpoint screenshot with the baseline screenshot. For more information, see ignoreRegions
floatingRegions	undefined	An array of regions to consider as floating when comparing the checkpoint screenshot with the baseline screenshot. For more information, see floatingRegions
layoutRegions	undefined	An array of regions to consider as match level Layout when comparing the checkpoint screenshot with the baseline screenshot. For more information, see layoutRegions
strictRegions	undefined	An array of regions to consider as match level Strict when comparing the checkpoint screenshot with the baseline screenshot. For more information, see strictRegions
contentRegions	undefined	An array of regions to consider as match level Content when comparing the checkpoint screenshot with the baseline screenshot. For more information, see contentRegions
accessibilityRegions	undefined	An array of regions to validate accessibility when comparing the checkpoint screenshot with the baseline screenshot. Validation is according to the configured accessibilityValidation. For more information, see accessibilityRegions
accessibilityValidation	undefined	An object that specifies the accessibility level and guidelines version to use for the screenshots. Possible values for level are None, AA and AAA, and possible values for guidelinesVersion are WCAG_2_0 and WCAG_2_1. For example: {level: 'AA', guidelinesVersion: 'WCAG_2_0'}. For more information, see accessibilityValidation
layoutBreakpoints	undefined	When set to true, a snapshot of the DOM will be taken once for each browser/device size in the browser configuration. For optimization purposes, an array of numbers can be passed. The DOM snapshot will be taken once for every width in the array. For more information, see layoutBreakpoints
sendDom	true	Specifies whether a capture of DOM and CSS should be taken when rendering the screenshot. The default value is true and should only be modified to troubleshoot unexpected behavior, and not for normal production use. For more information, see sendDom
visualGridOptions	undefined	An object that specifies options to configure renderings on the Ultrafast grid. For additional information, see visualGridOptions.

Note

You can override properties for a subset of stories using storyConfiguration.

Parameters that cannot be set as an advanced configuration

runBefore and runAfter functions

The runBefore function can be used to perform any action prior to taking the story snapshot. The runAfter method can be used to cleanup any side-effect that runBefore creates, if there are any.
For example, if runBefore adds a class to the body element, this class should be removed in runAfter. This is because the browser tab's window is not reloaded between stories.

Note: rootEl also needs to be cleaned up, so any modification that was done on this element in runBefore should be reverted in runAfter.

runBefore

An asynchronous function that will be evaluated before the story's screenshot is taken. This is the place to perform any interaction with the story using DOM API's.

For performing various DOM interactions, see dom-testing-library. It provides utilities to interact, query, and wait for conditions on the DOM.

For example, a component that renders a popover could trigger the opening of the popover and wait for content to appear:

// these are utilities from dom-testing-library
import {wait, within, fireEvent} from '@testing-library/dom';

// <Popover /> is a component in your UI library.
// The assumption in this example is that it is opened by an element with the text 'Open',
// and then that element's text changes to 'Close':
storiesOf('UI components', module)
  .add('Popover', () => <Popover />, {
    eyes: {
      runBefore({rootEl, story}) {
        fireEvent.click(within(rootEl).getByText('Open'))
        return wait(() => within(rootEl).getByText('Close'))
      }
    },
  })

runAfter

An asynchronous function that is evaluated after the story's screenshot is taken. This is the place to perform any clean ups that could change the way the next story renders.

For example, reverting back to the original background color that was changed by a previous component:

.add('background color', () => (
  <div style={{fontSize: '30px'}}>Component with runBefore hook that modifies the background color</div>
  ), {
  eyes: {
    runBefore({rootEl, story}) {
     window.originalBackgoundColor = document.querySelector("html").style.backgroundColor;
     document.querySelector("html").style.backgroundColor = 'fuchsia';
    },
    runAfter({rootEl, story}){
     document.querySelector("html").style.backgroundColor = window.originalBackgoundColor;
     delete window.originalBackgoundColor;
    }
  }
})

layoutBreakpoints

storiesOf('Components', module)
  .add(
    'Some story with breakpoints for all browser and device sizes',
    () =>
      <div>Some Story</div>, { 
        eyes: { 
          layoutBreakpoints: true
        }
      })
  .add(
    'Some story with breakpoints for desktop and mobile',
    () =>
      <div>Some Story</div>, { 
        eyes: { 
          layoutBreakpoints: [500, 1200]
        }
      })