Per‑story configuration

Overview

Use per‑story settings to override global behavior for a particular story/state. Prefer CSF (parameters.eyes) for new code; classic .add() works too. These settings let you wait for readiness, pick match levels, scope regions, and override rendering targets for just this story.

Where this fits: Authors tweak stories, design/dev reviewers triage diffs. Global policy stays in applitools.config.js.

Choose which stories run — include

• Global function (in config):

  module.exports = {
    include: ({ kind }) => kind.startsWith('App|Components/Radio'),
  };

• Global string/regex (in config):

  module.exports = { include: 'Button: with text' };
  module.exports = { include: /Button: .*/ };

• Per story — CSF:

  export const Primary = { parameters: { eyes: { include: true } } };

• Per story — classic .add():

  storiesOf('Some kind', module).add(
    'Some story',
    () => <div>…</div>,
    { eyes: { include: false } } // skip this story
  );

Capture timing — waitBeforeCapture

• number (ms) or string (CSS selector) per story;
• function only in config (global predicate).

// Per story (selector wait)
export const Loaded = {
  parameters: { eyes: { waitBeforeCapture: '#ready' } },
};

// Global predicate
module.exports = {
  waitBeforeCapture: async ({ rootEl }) => {
    await new Promise((r) => setTimeout(r, 250));
  },
};

Metadata — properties[]

Tag runs with extra context (component owner, theme, etc.).

export const Card = {
  parameters: { eyes: { properties: [{ name: 'team', value: 'checkout' }] } },
};

Per‑story browsers — browser

Limit/override UFG targets just for this story.

export const NarrowOnly = {
  parameters: {
    eyes: { browser: [{ name: 'chrome', width: 768, height: 800 }] },
  },
};

Regions & matching

Scope what matters (selectors or rectangles).

export const WithToasts = {
  parameters: {
    eyes: {
      matchLevel: 'Strict',
      ignoreRegions: [
        { selector: '.ad' },
        { left: 10, top: 20, width: 200, height: 60 },
      ],
      floatingRegions: [
        {
          selector: '.toast',
          maxUpOffset: 10,
          maxDownOffset: 10,
          maxLeftOffset: 30,
          maxRightOffset: 30,
        },
      ],
      layoutRegions: [{ selector: '.grid' }],
      strictRegions: [{ selector: '.cta' }],
      contentRegions: [{ selector: '.article' }],
      accessibilityRegions: [
        { selector: '.a11y', accessibilityType: 'RegularText' },
      ],
      accessibilityValidation: { level: 'AA', guidelinesVersion: 'WCAG_2_1' },
      ignoreDisplacements: true,
    },
  },
};

Responsive snapshots — layoutBreakpoints

export const Responsive = {
  parameters: { eyes: { layoutBreakpoints: [480, 1200] } },
};
// Or auto widths:
export const AutoResponsive = {
  parameters: { eyes: { layoutBreakpoints: true } },
};

Script hooks — scriptHooks.beforeCaptureScreenshot

Run a small script (string) before snapshot (e.g., set a CSS var).

export const GoldBg = {
  parameters: {
    eyes: {
      scriptHooks: {
        beforeCaptureScreenshot: "document.body.style.background='gold'",
      },
    },
  },
};

Variations — extra executions per story

Drive additional runs (e.g., RTL) using query params and/or Eyes properties.

// config
module.exports = {
  variations: [
    {
      queryParams: { 'eyes-variation': 'RTL' },
      properties: [{ name: 'rtl', value: 'true' }],
    },
  ],
};

// story code (switch on the query param inside the story iframe)
const params = new URL(window.location).searchParams;
if (params.get('eyes-variation') === 'RTL')
  document.documentElement.dir = 'rtl';

Story subsets by rule — storyConfiguration[]

Assign Eyes settings to subsets via a predicate.

module.exports = {
  storyConfiguration: [
    {
      stories: ({ storyTitle }) => storyTitle.includes('image'),
      matchLevel: 'Layout',
      target: 'region',
      selector: { selector: '.gallery' },
      browser: [{ width: 1024, height: 600 }],
    },
    {
      stories: ({ id }) => id === 'button--with-text',
      matchLevel: 'Strict',
      browser: [{ name: 'firefox', width: 1024, height: 600 }],
    },
  ],
};

Supported fields inside an item include (non‑exhaustive): browser, ignoreCaret, matchLevel, waitBeforeCapture, ignoreDisplacements, region lists (ignoreRegions, floatingRegions, layoutRegions, strictRegions, contentRegions, accessibilityRegions), accessibilityValidation, layoutBreakpoints, sendDom, useDom, enablePatterns, visualGridOptions, scriptHooks, and capture scoping (target, region, selector, fully, fakeIE).

Interactions & determinism

• Storybook Interactions (play) — Eyes captures after the play function completes. Any waitBeforeCapture delay begins after play.
• Deterministic data — Story iframes include ?eyes-storybook=true; use it to switch fixed dates/seeds in your stories.