Skip to main content

ManagerConfig

Configuration for the storyshots manager. Used when running in UI and CI modes.

devices​

Describes the list of devices on which stories are run.

note

The first object in the devices list becomes the default device.

export default {
  devices: [
    {
      name: 'desktop',
      width: 1480,
      height: 920,
    },
    {
      name: 'mobile',
      userAgent:
        'Mozilla/5.0 (iPhone; CPU iPhone OS 12_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/12.0 Mobile/15E148 Safari/604.1',
      width: 414,
      height: 896,
    },
  ],
  /* ... */
};

preview​

Accepts an app server.

import { createAppServer } from '../manager/createAppServer';

export default {
  preview: createAppServer(),
  /* ... */
};

runner​

Test task execution handler. In most cases, this is a pool of browser instances.
The default implementation lets you control the amount of parallel workers:

export default {
  runner: RUNNER.pool({ agentsCount: 4 }),
  /* ... */
};
note

There is no strict formula for the recommended number of agents. Choose the right value experimentally.

capture​

Page screenshot strategy for capturing the page in a stable state.

note

A page is considered stable when its visual representation stops changing.

By default, storyshots uses an optimized stabilization algorithm, but you can override it:

export default {
  /**
   * Takes an immediate screenshot and skips stabilization.
   * (Not recommended for most scenarios.)
   */
  capture: CAPTURE.instantly,
  /* ... */
};

paths​

Contains the paths for storyshots artifacts.

export default {
  paths: {
    // Path to the folder with logs
    records: path.join(process.cwd(), 'records'),
    // Path to the folder with screenshots
    screenshots: path.join(process.cwd(), 'screenshots')
  },
  /* ... */
};

agentsCount​

Defines playwright agents count:

export default {
  agentsCount: 4,
  /* ... */
};
note

There is no strict formula determining the recommended number of agents. The optimal value should be determined experimentally.

compare​

Describes the algorithm for comparing two images.

note

By default, storyshots uses an algorithm that accounts for human color perception, making tests less fragile.

withPlaywright​

Delegates screenshot comparison to playwright:

export default {
  compare: Compare.withPlaywright(options),
  /* ... */
};

comparator​

Pixel comparison algorithm:

threshold​

Comparison tolerance (from 0 to 1, where 0 is maximum strictness). Works only for pixelmatch

maxDiffPixels​

Maximum allowed difference in pixels. 0 by default

maxDiffPixelRatio​

Maximum allowed difference in pixels (ratio: from 0 to 1). 0 by default

withLooksSame​

Uses looks-same.

export default {
  compare: Compare.withLooksSame(options),
  /* ... */
};
note

All main options are available except createDiffImage (diff is always created as it is mandatory for storyshots)

Optimal Algorithm​

Although the library provides a minimal required set of algorithms out of the box, it may not be suitable for specific project needs.

tip

The right algorithm is one that minimizes false positives (fragile tests) while still catching defects (ensuring high regression protection).

That’s why storyshots allows you to implement your own solution:

{
  compare: (actual, expected, story) => Promise<ComparisonResult>;
  /* ... */
}
  • actual – screenshot of current behavior
  • expected – baseline screenshot
  • story – story object including meta attributes

The result of the algorithm is a ComparisonResult object containing:

  • equal – flag indicating whether the two screenshots are equal
  • explanation – if screenshots are not equal, contains additional information
  • diff – reference to the final diff image
tip

The comparison interface is asynchronous, opening up additional possibilities for advanced comparison techniques, such as using online services.