Skip to main content

Storybook test configuration

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

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 valueDescription
storybookUrl undefinedURL for Storybook (also available as command-line argument).
storybookPort 9000Port to run Storybook (also available as command-line argument).
storybookHost localhostHost to run Storybook (also available as command-line argument).
storybookConfigDir .storybookPath to Storybook's config folder (also available as command-line argument).
storybookStaticDir undefinedPath to Storybook's static files folder (also available as command-line argument).
showStorybookOutput undefinedWhether 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 trueIf 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 falseWhether or not you want to see logs of the Eyes-Storybook plugin.
batch undefinedAn object which describes different aspects of the batch. The following lines in this table depict the various ways to configure the batch.
batch.id randomProvides ability to group tests into batches. Read more about batches here.
batch.name The name of the first test in the batchProvides a name to the batch (for display purpose only).
batch.sequenceName undefinedName for managing batch statistics.
batch.notifyOnCompletion falseIf true batch completion notifications are sent.
batch.properties undefinedCustom 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 undefinedThe name of the environment of the baseline.
envName undefinedA name for the environment in which the application under test is running.
ignoreCaret falseWhether to ignore or the blinking caret or not when comparing images.
matchLevel undefinedThe 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 undefinedThe name of the branch.
baselineBranchName undefinedThe name of the baseline branch.
parentBranchName undefinedSets the branch under which new branches are created.
proxy undefinedSets 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 falseIf true, tests with diffs are saved by default as a baseline.
saveNewTests trueIf true, new tests are saved by default as a baseline.
serverUrl Default Eyes server URLThe URL of Eyes server
compareWithParentBranch false
ignoreBaseline false
runInDocker falseIf you are having issues running the SDK in docker, set this flag to true. For additional information, see Running Eyes-Storybook in Docker
puppeteerOptions undefinedOptions 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 undefinedOptions to send to page.setExtraHTTPHeaders. For additional information, see the Puppeteer documentation
jsonFilePath undefinedDirectory 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 undefinedDirectory 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 undefinedDirectory 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 undefinedSelector, 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 trueA 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 undefinedSpecifies additional variations for all or some of the stories. For example, RTL. For more information, see variations.
dontCloseBatches falseIf true, batches are not closed for notifyOnCompletion.
testConcurrency 5The 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 60000The 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 falseSets 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 undefinedAdds 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 undefinedAn array of regions to ignore when comparing the checkpoint screenshot with the baseline screenshot. For more information, see ignoreRegions
floatingRegions undefinedAn array of regions to consider as floating when comparing the checkpoint screenshot with the baseline screenshot. For more information, see floatingRegions
layoutRegions undefinedAn array of regions to consider as match level Layout when comparing the checkpoint screenshot with the baseline screenshot. For more information, see layoutRegions
strictRegions undefinedAn array of regions to consider as match level Strict when comparing the checkpoint screenshot with the baseline screenshot. For more information, see strictRegions
contentRegions undefinedAn array of regions to consider as match level Content when comparing the checkpoint screenshot with the baseline screenshot. For more information, see contentRegions
accessibilityRegions undefinedAn 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 undefinedAn 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 undefinedWhen 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 trueSpecifies 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
visualGridOptionsundefinedAn 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]
}
})