Storybook Test Runner

You can use Storybook tags to include, exclude, or skip specific stories during test execution.

1. Annotate Stories

Add tags to your component meta or individual stories. Tags must be defined inline as an array of strings due to Storybook's static analysis requirements (do not import constants for tags).

• Meta tags: Apply to all stories in a file.
• Story tags: Apply only to that specific story.
• Negation: Use !tagname to remove a tag (e.g., tags: ['!test']).

2. Apply Filters

You can filter these tags in three ways:

• CLI Flags: Use --includeTags, --excludeTags, or --skipTags. CLI flags take precedence over configuration file settings.
• Config File: Define tags in your ejected test-runner-jest.config.js.

Difference between Skip and Exclude:

• --excludeTags: The story is completely ignored and does not appear in the output.
• --skipTags: The story is marked as "skipped" in the CLI output, which is useful for temporarily disabling tests.

const meta = {
  component: Button,
  tags: ['atom'],
};
export default meta;

// will inherit tags from project and meta to be ['dev', 'test', 'atom']
export const Primary = {};

export const Secondary = {
  // will combine with project and meta tags to be ['dev', 'test', 'atom', 'design']
  tags: ['design'],
};

export const Tertiary = {
  // will combine with project and meta tags to be ['dev', 'atom']
  tags: ['!test'],
};

The test runner executes a story's play function in the browser. For tasks that require Node.js access (like visual snapshots or DOM snapshots), you can override global test hooks in .storybook/test-runner.js.

There are three primary hooks:

• setup: Runs once in Node before all tests. Use this for global configuration (e.g., extending Jest expect).
• preVisit: Runs in the test before a story renders. Use this to configure the Playwright Page (e.g., setting viewport size).
• postVisit: Runs in the test after a story renders. Use this for assertions like DOM or image snapshotting.

Note: While these hooks provide access to the Playwright Page object, it is encouraged to perform as much testing as possible within the story's play function.

// .storybook/test-runner.ts
import type { TestRunnerConfig } from '@storybook/test-runner';

const config: TestRunnerConfig = {
  async setup() {
    // Runs once in Node before all tests
  },
  async preVisit(page, context) {
    // Runs before the story renders
  },
  async postVisit(page, context) {
    // Runs after the story renders
  },
};
export default config;

To perform visual regression testing, use jest-image-snapshot within the postVisit hook.

It is highly recommended to use the waitForPageReady(page) utility from @storybook/test-runner before taking the screenshot to ensure fonts and other assets are fully loaded. You can use context.id as a customSnapshotIdentifier to ensure unique filenames for each story.

// .storybook/test-runner.ts
import { TestRunnerConfig, waitForPageReady } from '@storybook/test-runner';
import { toMatchImageSnapshot } from 'jest-image-snapshot';

const customSnapshotsDir = `${process.cwd()}/__snapshots__`;

const config: TestRunnerConfig = {
  setup() {
    expect.extend({ toMatchImageSnapshot });
  },
  async postVisit(page, context) {
    await waitForPageReady(page);

    const image = await page.screenshot();
    expect(image).toMatchImageSnapshot({
      customSnapshotsDir,
      customSnapshotIdentifier: context.id,
    });
  },
};
export default config;"

The test runner is built on Jest. While it works out of the box, you can eject its configuration to gain full control over Jest and jest-playwright settings.

To eject, run: test-storybook --eject

This creates a test-runner-jest.config.js file in your project root (or in your Storybook config directory if you use --config-dir). This file allows you to:

1. Override Jest options: Such as testTimeout, maxWorkers, or reporters.
2. Configure Playwright: Pass testEnvironmentOptions to configure the jest-playwright environment.

Note: The test runner uses an internal version of Jest. If you already have a compatible version of Jest in your project, the runner will use yours instead of installing a duplicate.

// ./test-runner-jest.config.js
const { getJestConfig } = require('@storybook/test-runner');

const testRunnerConfig = getJestConfig();

/**
 * @type {import('@jest/types').Config.InitialOptions}
 */
module.exports = {
  // The default Jest configuration comes from @storybook/test-runner
  ...testRunnerConfig,
  /** Add your own overrides below
   * @see https://jestjs.io/docs/configuration
   */
  testTimeout: 20000, // default timeout is 15s
};

You can use Playwright's APIs within the postVisit hook to capture the HTML of a story and compare it against a snapshot using expect(innerHTML).toMatchSnapshot().

In Storybook 6.x, the selector for the story container is #root. In modern versions, use #storybook-root.

Note on storage: When running with --stories-json, snapshots are stored in a temporary folder. To store them in your working directory, you must use --eject and configure a custom snapshotResolver in your Jest configuration.

// .storybook/test-runner.ts
import type { TestRunnerConfig } from '@storybook/test-runner';

const config: TestRunnerConfig = {
  async postVisit(page, context) {
    // The #storybook-root element wraps the story.
    const elementHandler = await page.$('#storybook-root');
    const innerHTML = await elementHandler.innerHTML();
    expect(innerHTML).toMatchSnapshot();
  },
};
export default config;"