Advanced usage

This page is your last stop before the API reference for trickier setups, scale/perf tuning, and production-hardening.
If you haven’t yet, first follow Quick Start and Integration with Storybook to get a green run, then return here to refine.

Handling dynamic content effectively

1. Dynamic match level Prefer the Dynamic match level for pages with emails, timestamps, or randomized data. Combine with ignoreRegions/floatingRegions for animations and moving containers.

   Per-story example (CSF):

   export const PriceCard = {
     parameters: {
       eyes: {
         matchLevel: 'Dynamic', // tolerate fluctuating minor text
       },
     },
   };

2. Ignore regions Use ignore regions for truly irrelevant content (ads/timestamps). Use floating regions when something moves within bounds (snackbars/toasts).

   export const WithToast = {
     parameters: {
       eyes: {
         ignoreRegions: [{ selector: '.timestamp' }],
         floatingRegions: [
           {
             selector: '.toast',
             maxUpOffset: 10,
             maxDownOffset: 10,
             maxLeftOffset: 40,
             maxRightOffset: 40,
           },
         ],
       },
     },
   };

3. Make stories deterministic (pro tip)

   Eyes appends ?eyes-storybook=true to the story iframe. Branch off it to freeze dates/seeds.

   const params = new URL(window.location.href).searchParams;
   if (params.get('eyes-storybook')) {
     (window as any).__NOW__ = new Date('2025-01-01T00:00:00Z');
     Math.random = () => 0.42;
   }

Asynchronous UIs & interactions

If a story uses Storybook play (interactions), Eyes captures after the play function finishes. Then any waitBeforeCapture delay applies.

• Prefer navigationWaitUntil: 'networkidle2' for UIs with long async work.
• In interactions, favor explicit readiness markers (data-ready, aria-busy=false) over sleeps.

// applitools.config.js
module.exports = {
  navigationWaitUntil: 'networkidle2',
  waitBeforeCapture: '#ready', // or a global predicate as above
};

Network hygiene & performance

Trim noise and speed up cycles:

• Block chatter:

  npx eyes-storybook --networkBlockPatterns "*/ads/*,*/analytics/*"

  Or in config:

  module.exports = { networkBlockPatterns: ['*/ads/*', '*/analytics/*'] };

• Cache requests:

  module.exports = { browserCacheRequests: true };

• Subset locally, go broad in CI:

  npx eyes-storybook --include /Button:.*/

• Avoid unnecessary full-page capture: keep fully for pages/containers that truly need it.

Concurrency & throughput tuning

Balance speed vs. resources/quota.

• Local tab fan-out (APPLITOOLS_CONCURRENT_TABS) Default is 3. Increase cautiously on small CI runners.

  export APPLITOOLS_CONCURRENT_TABS=5

Monorepos & multiple Storybooks

• Use storybookConfigDir to point Eyes to the right .storybook per package.
• Run separate batches per package to keep results focused.

Theming, locales, and feature flags

Drive stories with globals/args and run Eyes with different permutations using --include filters or multiple CI jobs; tag each run with properties (theme=dark, locale=fr‑FR, etc.).

Docker & CI hardening

If Chrome struggles in containers, set runInDocker: true or override puppeteerOptions.executablePath. Ensure enough shared memory and fonts are available. Prefer serving a static Storybook in CI, then run Eyes against its URL.

# GitHub Actions sketch
- run: npm run build-storybook
- run: npx http-server storybook-static -p 6006 &
- run: npx eyes-storybook -u http://localhost:6006 -e
  env:
    APPLITOOLS_API_KEY: ${{ secrets.APPLITOOLS_API_KEY }}

Root Cause Analysis (RCA) for encoded DOM/CSS

Provide a domMapping JSON to map hashed identifiers back to readable names:

module.exports = { domMapping: './dom-mapping.json' };
// { "abcd": "cls-button", "qwerty": "var-color" }