Per component configuration

Note

These components are only supported on Storybook version 4 and later.

There are two ways to provide configuration for a specific story, or a group of stories.

As an argument to the story - It's possible to pass a third argument to storybook's .add function to customize each story. An eyes property on the parameters object can be specified with configuration properties.
In the global configuration file, applitools.config.js - If a function is specified for one of the properties below, it will be called for each story, and will be passed the story's metadata, of the structure {name, kind, parameters}, where name is the name of the component, kind is the string built by storybook for the category, e.g. Forms|Input/Text, and parameters are the third argument to storybook's .add function. The function should return the configuration value for the specific property+story.

Specifying a value locally in the story takes precedence over the global config value.

include

global

When provided globally, include is a function that receives the story's kind and name, storyTitle, and parameters. All these properties except storyTitle come from storybook and they represent the hierarchy of the stories:

kind - The story's directory and section, where applicable. Nested directory structures are allowed in storybook. These will be suffixed by /, while a section - that can hold many directories will be suffixed with a |.
For example:
- Story named Button in the Components directory - its kind will be Components.
- Story named Button in the Components directory under the App section - its kind will be App|Components.
- Story named RadioButton in the Radio sub-directory of the Components directory under the App section - its kind will be App|Components/Radio.
name - the story name.
For example:
- Story named Button in the Components directory - its name will be Button.
parameters - custom parameters that can specified in the story.

storyTitle is generated by the SDK and is used as the test name. Therefore it is easy to find and filter by it.

For additional information, see Naming components and hierarchy in the Storybook documentation.

You can filter by kind, name, storyTitle, parameters, a combination of them or any logic that will result in a boolean.

Example

applitools.config.js
module.exports = {
  ...
  // given the example above
  // visually test only the stories in the 'Radio' subdirectory
  include: ({kind}) => {
    return kind === 'App|Components/Radio'
  }
  ...
}

When passing a storyTitle as a string only this story will be tested.

Example

applitools.config.js
module.exports = {
...
include: "Button: with text",
...
}

When passing a storyTitle as a Regex only matching stories will be tested.

Example

applitools.config.js
module.exports = {
...
include: /Button: */,
...
}

note

You can use regular expressions or any other method, as long as you return a boolean from this function.

component

When false, the component will not be visually tested.

Example

// This story will not be tested visually
storiesOf('Some kind', module)
  .add(
    'Some story',
    () => <div>I am visually perfect!</div>,
    {eyes: {include: false}}
  )

waitBeforeCapture

Selector or timeout. For Additional information, see Properties

Example

storiesOf('Components with a waitBeforeCapture', module)
  .add(
    'Some story',
    () => <span id="container" class="loading"></span>,
    {eyes: { waitBeforeCapture: '#container.ready' }}
  );

note

The predicate option for waitBeforeCapture is currently not available in the per component configuration.

properties

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.

Example

storiesOf('Components with custom properties', module)
  .add(
    'Some story',
    () => <span id="container" class="loading"></span>,
    {eyes: { properties: [
      {name: 'some prop #1', value: 'some value #1'},
      {name: 'some prop #2', value: 'some value #2'},
    ] }}
  );

browser

Local browser configuration.

Example

.add(
  'Story with local browser configured',
  () => {
    return <div style={{width: 50, height: 50}}>single story</div>;
  },
  {eyes: {browser: [{name: 'chrome', width: 1024, height: 600}]}},
);

ignoreRegions

A single or an array of regions to ignore when checking for visual differences.

Example

storiesOf('Components with ignored region', module)
  .add(
    'Some story',
    () =>
      <div>
        <span>I am visually perfect!</span>
        <span className="ignore-this">this should be ignored</span>
      </div>,
    {eyes: {
      ignoreRegions: [
        {selector: '.ignore-this'}, // by css selector
        {left: 10, top: 20, width: 200, height: 80} // by absolute coordinates
      ]}
    }
  )

floatingRegions

An array of regions to consider as floating when comparing the checkpoint screenshot with the baseline screenshot.

Example

storiesOf('Components with floating region', module)
  .add(
    'Some story',
    () =>
      <div>
        <span>I am visually perfect!</span>
        <span className="floating-region">this should be floating</span>
      </div>,
    {eyes: {
      floatingRegions: [
        { // by selector
          selector: '.floating-region',
          maxUpOffset: 10,
          maxDownOffset: 20,
          maxLeftOffset: 30,
          maxRightOffset: 40,
        },
        { // by absolute coordinates
          left: 10,
          top: 20,
          width: 200,
          height: 80,
          maxUpOffset: 10,
          maxDownOffset: 20,
          maxLeftOffset: 30,
          maxRightOffset: 40,
        }
      ]}
    }
  )

layoutRegions

An array of regions to consider as match level Layout when comparing the checkpoint screenshot with the baseline screenshot.

Example

storiesOf('Components with layout region', module)
  .add(
    'Some story',
    () =>
      <div>
        <span>I am visually perfect!</span>
        <span className="layout-region">this should be compared with layout match level</span>
      </div>,
    {eyes: {
      layoutRegions: [
        {selector: '.layout-region'}, // by css selector
        {left: 10, top: 20, width: 200, height: 80} // by absolute coordinates
      ]}
    }
  )

contentRegions

An array of regions to consider as match level Content when comparing the checkpoint screenshot with the baseline screenshot.

Example

storiesOf('Components with content region', module)
  .add(
    'Some story',
    () =>
      <div>
        <span>I am visually perfect!</span>
        <span className="content-region">this should be compared with content match level</span>
      </div>,
    {eyes: {
      contentRegions: [
        {selector: '.content-region'}, // by css selector
        {left: 10, top: 20, width: 200, height: 80} // by absolute coordinates
      ]}
    }
  )

strictRegions

An array of regions to consider as match level Strict when comparing the checkpoint screenshot with the baseline screenshot.

Example

storiesOf('Components with strict region', module)
  .add(
    'Some story',
    () =>
      <div>
        <span>I am visually perfect!</span>
        <span className="strict-region">this should be compared with strict match level</span>
      </div>,
    {eyes: {
      strictRegions: [
        {selector: '.strict-region'}, // by css selector
        {left: 10, top: 20, width: 200, height: 80} // by absolute coordinates
      ]}
    }
  )

accessibilityRegions

A single or an array of regions for accessibility checking.

Example

storiesOf('Components with accessibility regions', module)
  .add(
    'Some story',
    () =>
      <div>
        <span>I am visually perfect!</span>
        <span className="check-me">this should be tested for accessibility</span>
      </div>,
    {eyes: {
      accessibilityRegions: [
        {accessibilityType: 'RegularText', selector: '.check-me'}, // by css selector
        {accessibilityType: 'RegularText', left: 10, top: 20, width: 200, height: 80} // by absolute coordinates
      ]
    }}
  )
});

Possible accessibilityType values:

IgnoreContrast
RegularText
LargeText
BoldText
GraphicalObject

accessibilityValidation

The level and guidelines version that should be used when validation accessibility regions.

Example

storiesOf('Components with accessibility regions', module)
  .add(
    'Some story',
    () => <div>
      <span>I am visually perfect!</span>
      <span className="check-me">this should be tested for accessibility</span>
    </div>,
    {eyes: {
      accessibilityValidation: {
        level: 'AA',
        guidelinesVersion: 'WCAG_2_0'
      }
    }}
  )
});

Possible values for level:

AA
AAA

Possible values for guidelinesVersion:

WCAG_2_0
WCAG_2_1

ignoreDisplacements

Sets whether Test Manager should initially display mismatches for image features that have only been displaced, as opposed to real mismatches.

Example

storiesOf('Components with ignoreDisplacements', module)
  .add(
    'Some story',
    () => <div>
      <span>I am visually perfect!</span>
    </div>,
    {eyes: {
      ignoreDisplacements: true
    }}
  )
});

sendDom

Example

  storiesOf('Components', module)
    .add(
      'Some story ',
      () =>
        <div>Some Story</div>, { 
          eyes: { 
            sendDom: false
          }
        })

visualGridOptions

An object that specifies options to configure renderings on the Ultrafast Grid. Available options:

polyfillAdoptedStyleSheets - Creates a polyfill when the DOM contains adoptedStyleSheets (reference) for browsers that don't support it (It is currently supported only in Chrome). When true, those browsers will successfully include the css as inline style tags. When false, the css will not be included. When undefined, an error will be thrown with a message stating that this feature is not supported in the desired browser.
ieV2 - Use IE environment v2 in the UFG.

Example

  storiesOf('Components', module)
    .add(
      'Some story ',
      () =>
        <div>Some Story</div>, { 
          eyes: { 
            visualGridOptions: {
              polyfillAdoptedStyleSheets: true,
              ieV2: true
            }
          }
        })

variations

An array of object values, which specifies which variations to add for this story. For each value, an additional visual test will be executed for the component. Each variation could contain queryParams and properties fields to specifies custom query parameters and eyes properties respectfully. Variation tests will have the same name.

This can accommodate many use cases, for example @storybook/addon-contexts. With addons like this it is possible to render components in a different way based on on query parameters in URL.

Example - Storybook that handles an RTL variation

const isRTL = new URL(window.location).searchParams.get('eyes-variation') === 'RTL';

if (isRTL) {
  document.documentElement.setAttribute('dir', 'rtl')
}

// 2 visual tests will be created - one for LTR and one for RTL
storiesOf('Components that support RTL', module)
  .add(
    'Some story',
    () => <div>
        <span>I am visually perfect!</span>
        <span>{isRTL ? ' and rendered right to left as well :)' : ''}</span>
      </div>,
    {
      eyes: {
        variations: [
          {
            queryParams: {'eyes-variation': 'RTL'},
            properties: [{name: 'isRTL', value: 'true'}],
          },
          {
            properties: [{name: 'isRTL', value: 'false'}]
          }
        ]
      }
    }
  )

scriptHooks

A set of scripts to be run by the browser during the rendering. It is intended to be used as a means to alter the page's state and structure at the time of rendering. An object with the following properties:

beforeCaptureScreenshot

A script that runs after the page is loaded but before taking the screenshot.

Example

storiesOf('Components', module)
  .add(
    'Some story',
    () =>
      <div>Some Story</div>, { 
        eyes: { 
          scriptHooks: {
            beforeCaptureScreenshot: "document.body.style.backgroundColor = 'gold'"
          }
        }
      })

storyConfiguration

Allows you to set a configuration for a subset of stories based on story id, name, kind, parameters, and storyTitle. For example you could define a specific match level for all stories with a defined string in the storyTitle or with a defined kind. These settings are in addition to properties set globally in the applitools.config.js file, but override the global settings if there is a conflict.

You can set properties based on any of the following Storybook configurations:

id
name
kind
parameters

You can also set properties based on the storyTitle which is generated by the SDK.

You can set any of the following properties using storyConfiguration:

browser
ignoreCaret
matchLevel
waitBeforeCapture
ignoreDisplacements
ignoreRegions
floatingRegions
layoutRegions
strictRegions
contentRegions
accessibilityRegions
accessibilityValidation
layoutBreakpoints
sendDom
useDom
enablePatterns
visualGridOptions
scriptHooks
target
region
selector
fully
fakeIE

Example

storyConfiguration:[{
      stories: ({storyTitle, id, name, kind, parameters}) =>  storyTitle.includes('image'),
      matchLevel: 'layout',
      target: 'region',
      selector: {selector: '.some-selector'},
      browser: [{ width: 1024, height: 600}]
    }, 
    {
        stories: ({storyTitle, id, name, kind, parameters}) =>  id === 'button--with-text',
        matchLevel: 'strict',
        browser: [{name:'firefox', width: 1024, height: 600}] 
    }
]

Per component configuration

include​

global​

Example​

Example​

Example​

component​

Example​

waitBeforeCapture​

Example​

properties​

Example​

browser​

Example​

ignoreRegions​

Example​

floatingRegions​

Example​

layoutRegions​

Example​

contentRegions​

Example​

strictRegions​

Example​

accessibilityRegions​

Example​

accessibilityValidation​

Example​

ignoreDisplacements​

Example​

sendDom​

Example​

visualGridOptions​

Example​

variations​

Example - Storybook that handles an RTL variation​

scriptHooks​

beforeCaptureScreenshot​

Example​

storyConfiguration​

Example​

include

global

Example

Example

Example

component

Example

waitBeforeCapture

Example

properties

Example

browser

Example

ignoreRegions

Example

floatingRegions

Example

layoutRegions

Example

contentRegions

Example

strictRegions

Example

accessibilityRegions

Example

accessibilityValidation

Example

ignoreDisplacements

Example

sendDom

Example

visualGridOptions

Example

variations

Example - Storybook that handles an RTL variation

scriptHooks

beforeCaptureScreenshot

Example

storyConfiguration

Example