Storycap Test Runner for Storybook Visual Testing

1.0.0 verified Thu Apr 23 auth: no javascript

storycap-testrun is a utility designed to provide stable screenshot capture functionality specifically for Storybook components, integrated with `@storybook/test-runner`. While the root `storycap-testrun` package is currently at version 1.0.0, the primary development and new features are delivered through its scoped sub-packages: `@storycap-testrun/node` and `@storycap-testrun/browser`, which are actively maintained and are at version 2.1.0. This library enables visual regression testing by capturing screenshots of Storybook stories, leveraging Playwright for reliable browser automation. It differentiates itself by integrating directly into the `@storybook/test-runner` ecosystem, allowing developers to extend their existing Storybook testing setups with visual verification. Recent updates in the 2.x.x series of the scoped packages include per-story image configuration options and official support for Vitest-based browser testing. The release cadence for the scoped packages appears to be several minor/major updates per year, indicating active development.

Common errors

error ERR_OS_NOT_SUPPORTED: The current operating system is not supported. ↓

cause Playwright, a peer dependency, has specific OS requirements or native binaries might not be installed correctly.

fix

Ensure your environment meets Playwright's system requirements. Run npx playwright install to download necessary browser binaries if they are missing or corrupted.

error Error: Node.js v18.x is not supported. Please upgrade to Node.js v20.x or higher. ↓

cause Using `storycap-testrun@1.0.0` or newer with an unsupported Node.js version.

fix

Upgrade your Node.js environment to version 20 or higher. You can use a version manager like nvm (Node Version Manager) or volta.

error TypeError: (0 , storycap_testrun_1.preset) is not a function ↓

cause Attempting to import `preset` directly from `storycap-testrun` (the root package) when it's now exported from `@storycap-testrun/node/preset` in versions 2.0.0+ of the scoped packages, or `storycap-testrun@1.0.0` never directly exported it.

fix

Change your import statement to import preset from '@storycap-testrun/node/preset'; and ensure @storycap-testrun/node is installed and at version 2.0.0 or higher.

Warnings

breaking The `storycap-testrun` package (version 1.0.0) dropped support for Node.js 18. The minimum required Node.js version is now 20. ↓

fix Upgrade your Node.js environment to version 20 or higher.

gotcha Starting from version 2.0.0, the core functionality and new features are primarily delivered through scoped packages: `@storycap-testrun/node` and `@storycap-testrun/browser`. The root `storycap-testrun` package at 1.0.0 may not include these newer features or configurations directly. ↓

fix Ensure you are installing and importing from `@storycap-testrun/node` or `@storycap-testrun/browser` for the latest features and configurations. Refer to their respective documentation.

gotcha Per-story image options (`fullPage`, `omitBackground`, `scale`) for screenshot capture were introduced in `@storycap-testrun/node` and `@storycap-testrun/browser` at version 2.1.0. These options are set via `parameters.screenshot` in your Storybook stories or `preview.js`. ↓

fix Update `@storycap-testrun/node` or `@storycap-testrun/browser` to version 2.1.0 or newer to utilize per-story screenshot parameters. Configure them in `parameters.screenshot` within your stories or `preview.js`.

gotcha Support for `@storybook/addon-vitest` and a new Vitest plugin were added in `@storycap-testrun/browser` at version 2.0.0, accessible via the `/vitest-plugin` export. ↓

fix To enable visual testing with Vitest, install `@storycap-testrun/browser` v2.0.0+ and use the `createVitestPlugin` from `'@storycap-testrun/browser/vitest-plugin'` in your Vitest configuration.

Install

npm install storycap-testrun

yarn add storycap-testrun

pnpm add storycap-testrun

Imports

preset
wrong
```
import { preset } from 'storycap-testrun';
```
correct
```
import preset from '@storycap-testrun/node/preset';
```
The `preset` configuration for `@storybook/test-runner` is provided by the `@storycap-testrun/node` package since v2.0.0, not directly from the root `storycap-testrun` package.
VitestPlugin
wrong
```
import { VitestPlugin } from 'storycap-testrun';
```
correct
```
import { createVitestPlugin } from '@storycap-testrun/browser/vitest-plugin';
```
For Vitest integration, the `createVitestPlugin` function is exported specifically from the `/vitest-plugin` entry point of `@storycap-testrun/browser` since v2.0.0.

Quickstart

Demonstrates how to configure `@storybook/test-runner` with `@storycap-testrun/node`'s preset for stable screenshot capture. It also hints at per-story options.

// .storybook/test-runner-jest.config.js (or similar Jest/Playwright configuration)
import { defineConfig } from 'jest-runner-storybook';
import preset from '@storycap-testrun/node/preset';

export default defineConfig({
  ...preset(),
  // You can customize Playwright launch options here
  // playwright: {
  //   launchOptions: {
  //     headless: true,
  //   },
  // },
  // Add any other custom Jest configuration
  testTimeout: 30000,
});

// Example .storybook/preview.js for per-story options (requires @storycap-testrun/node@2.1.0+)
// import type { Preview } from '@storybook/react';
// const preview: Preview = {
//   parameters: {
//     screenshot: {
//       fullPage: false,
//       omitBackground: true,
//       scale: 1,
//     },
//   },
// };
// export default preview;