Storybook integration

The @cappa/plugin-storybook package bridges Storybook with Cappa’s screenshot pipeline. It fetches stories from a running Storybook instance, opens each story in Playwright, and captures images using the same comparison workflow as other targets. This guide walks through installing the plugin, connecting it to Storybook, and fine-tuning how screenshots are generated.

Install the plugin

Add the Storybook plugin alongside the Cappa core packages inside your project:

pnpm add -D @cappa/plugin-storybook

Next, register the plugin inside cappa.config.ts so that the CLI knows how to discover stories. The storybookUrl should point at the running Storybook server.

import { defineConfig } from '@cappa/core';
import { cappaPluginStorybook } from '@cappa/plugin-storybook';

export default defineConfig({
  outputDir: 'screenshots',
  plugins: [
    cappaPluginStorybook({
      storybookUrl: 'http://localhost:6006',
    }),
  ],
});

You can add additional plugin options to filter the stories that are captured:

includeStories – Optional predicate (story) => boolean. If provided, only stories for which it returns true are included. The argument is a StoryFilterContext with id, title, name, and filePath (the path "title/name", e.g. "Button/Primary").
excludeStories – Optional predicate (story) => boolean. If provided, stories for which it returns true are excluded (applied after includeStories).
defaultViewport – Override the default Playwright viewport when a story does not supply its own settings.

You can use minimatch or regex inside your predicates for glob-like behavior:

import { defineConfig } from '@cappa/core';
import {
  cappaPluginStorybook,
  type StoryFilterContext,
} from '@cappa/plugin-storybook';
import { minimatch } from 'minimatch';

export default defineConfig({
  outputDir: 'screenshots',
  plugins: [
    cappaPluginStorybook({
      storybookUrl: 'http://localhost:6006',
      includeStories: (s: StoryFilterContext) => minimatch(s.id, 'button--*'),
      excludeStories: (s: StoryFilterContext) => s.filePath.startsWith('Input/'),
    }),
  ],
});

To quiet noisy console output while the plugin runs, toggle the global logConsoleEvents option inside cappa.config.ts:

export default defineConfig({
  logConsoleEvents: false,
  plugins: [
    cappaPluginStorybook({
      storybookUrl: 'http://localhost:6006',
    }),
  ],
});

Wire up the Storybook addon

The plugin ships with a Storybook addon that exposes story-level configuration to Cappa. Enable it by adding @cappa/plugin-storybook to the Storybook addons list:

import type { StorybookConfig } from '@storybook/react-vite';

const config: StorybookConfig = {
  addons: ['@cappa/plugin-storybook'],
};

export default config;

The addon registers a global decorator that collects parameters for each story. If you need to adjust Storybook’s runtime when Cappa is in control, you can use the exported isCappa helper in .storybook/preview.ts:

import { isCappa } from '@cappa/plugin-storybook/browser';

if (isCappa()) {
  // Disable animations, load mock data, etc.
}

Capture stories

Start Storybook in one terminal and keep it running so the plugin can connect to the storybookUrl. From another terminal, run the Cappa capture command from the directory that contains your config:

# Terminal 1
pnpm storybook

# Terminal 2
pnpm cappa capture

Cappa will fetch the list of stories, load each one in Playwright, and write screenshots, diffs, and reports to the configured output directory. Pair it with cappa review and cappa approve to follow the normal approval workflow.

Keep in mind that the dev server of storybook might introduce delays in the story loading. It is therefore recommended to build storybook before running cappa capture, and then run cappa on the resulting static files.

You can use start-server-and-test to start Storybook and Cappa in one command.
Terminal window
pnpm start-server-and-test storybook "pnpm cappa capture"

Control per-story behaviour

Story-specific parameters can override how Cappa captures each story. Define them in your story file under parameters.cappa.

Option	Description	Default
`skip`	Skip capturing the story.	`false`
`delay`	Wait (in ms) before taking the screenshot. Cappa emits a debug log before waiting when debug logs are enabled.	`null` (no delay)
`fullPage`	Capture the full page instead of the viewport. Inherits from global `screenshot.fullPage` in `cappa.config.ts` when not set.	`true`
`mask`	Array of selectors to blur or hide in the screenshot.	`[]`
`omitBackground`	Capture the page with a transparent background.	`false`
`viewport`	Override the viewport size for the story.	Playwright default
`variants`	Additional screenshots to capture with overrides.	`[]`
`diff`	Override the global diff configuration for this story. Supports both `{ type: "pixel", ... }` and `{ type: "gmsd", ... }`.	Inherits global `diff` from `cappa.config.ts`

export const Primary = {
  parameters: {
    cappa: {
      delay: 250,
      mask: ['.tooltip'],
      diff: {
        // Switch this story to gmsd
        type: "gmsd",
        threshold: 0.2,
        downsample: 1,
      },
      variants: [
        {
          id: 'mobile',
          label: 'Mobile',
          options: {
            viewport: { width: 375, height: 812 },
            // Per-variant diff override (can also switch algorithm)
            diff: {
              type: "pixel",
              threshold: 0.25,
              maxDiffPixels: 10,
            },
          },
        },
        {
          id: 'dark-mode',
          label: 'Dark mode',
          options: { omitBackground: true },
        },
      ],
    },
  },
};

parameters are usually typed as any in storybook. To provide better types for cappa parameters, you can overwrite storybook parameters like this:
stories/types.d.ts
import type { CappaStorybookOptions } from "@cappa/plugin-storybook";
import "@storybook/react-vite"; // replace with your framework

declare module "@storybook/react-vite" { // replace with your framework
  interface Parameters {
    cappa?: CappaStorybookOptions;
  }
}

Variants

You can instruct cappa to capture multiple screenshots of a story, e.g. with different viewport:

export const Primary = {
  parameters: {
    cappa: {
      variants: [
        {
          id: 'mobile',
          label: 'Mobile',
          options: { viewport: { width: 375, height: 812 } },
        },
      ],
    },
  },
};

The id is used to identify the variant, and the label is used to display the variant in the report. The options are mostly the same as the options for the story, but they are applied to the variant.

The filename is the name of the file that will be created for the variant. If not provided, it will be generated from the story name and the variant id.

Args

You can override the args for a variant by adding them to the options.args property.

export const Primary = {
  parameters: {
    cappa: {
      variants: [
        {
          id: 'small',
          label: 'Small',
          options: {
            args: {
              size: 'small',
            },
          },
        },
      ],
    },
  },
};

Args only work if your component also is supporting these props AND spreads the args to the component.

Play function

If your story has a play function, cappa will wait for it to complete before capturing the screenshot.

export const Primary = {
  play: async ({ canvasElement }) => {
    const canvas = within(canvasElement);
    await userEvent.click(canvas.getByRole("button"));
  },
};

This allows you to take interactive screenshots of your stories.