Storybook Setup

Storybook integration makes it easy to test your component library with ViSnap. It automatically discovers all your stories and tests them exactly as they render in Storybook, giving you comprehensive visual coverage of your components.

Prerequisites

Storybook v8 or later
A built Storybook (run npm run build-storybook)

Installation

Install ViSnap:

npm install -D visnap

Create your config:

npx visnap init

Configure the Storybook adapter in visnap.config.ts:

// visnap.config.ts
import { type VisualTestingToolConfig } from '@visnap/protocol';

const config: VisualTestingToolConfig = {
  adapters: {
    // Browser settings - how screenshots are captured
    browser: {
      name: "@visnap/playwright-adapter",
      options: {
        launch: { browser: 'chromium', headless: true },
        context: { colorScheme: 'light', reducedMotion: 'reduce' },
      }
    },
    // Test source - what to test
    testCase: [
      {
        name: "@visnap/storybook-adapter",
        options: {
          source: "./storybook-static", // Path to your Storybook build
          include: "*", // Test all stories (use minimatch patterns to filter)
        }
      }
    ]
  }
};

export default config;

Build Storybook:

npm run build-storybook

Take your first baseline screenshots:

npx visnap update

Test for changes:

npx visnap test

Open report:

npx visnap open

Configuration Options

Source Options

Local build directory:

options: {
  source: "./storybook-static", // Local build
}

Remote Storybook URL:

options: {
  source: "https://your-storybook.com", // Remote URL
}

Custom port for local server:

options: {
  source: "./storybook-static",
  port: 4478, // Custom port (default: 4477)
}

Filtering Stories

Use patterns to include or exclude specific stories:

options: {
  source: "./storybook-static",
  include: ["Button/*", "Card/*"], // Only Button and Card stories
  exclude: ["*-skip*", "*-test*"], // Exclude stories with -skip or -test in name
}

Story-Level Configuration

Configure visual testing options directly in your stories using parameters.visualTesting:

export const MyStory: Story = {
  // ...
  parameters: {
    visualTesting: {
      skip: false,                    // Skip this story
      threshold: 0.05,               // Custom threshold (0.0-1.0)
      viewport: { width: 1200, height: 800 }, // Custom viewport
      browser: ["chromium", "firefox"],       // Specific browsers
      screenshotTarget: "#storybook-root",    // Custom screenshot target
      elementsToMask: [".sticky", "#ad-slot"], // Mask dynamic elements
      disableCSSInjection: true,     // Disable global CSS injection
      interactions: [                // Execute before screenshot
        // See Interactive Testing guide for examples
      ],
    },
  },
};

Common options:

skip: true - Skip this story entirely
threshold: 0.01 - More strict comparison (1% difference)
viewport: { width: 375, height: 667 } - Mobile viewport
browser: ["chromium"] - Test only specific browsers
screenshotTarget - Custom screenshot target
elementsToMask: [".dynamic"] - Hide elements that change frequently
disableCSSInjection - Disable global CSS injection from visnap.config
interactions: [...] - Execute actions before screenshot

Troubleshooting

Stories not found? Make sure your Storybook build is up to date:

npm run build-storybook

Port conflicts? Change the port in your config:

options: { port: 4478 }

Next Steps

Interactive Testing - Test user interactions
Screenshot Stabilization - Make tests more stable
CI Integration - Run tests in your pipeline
Configuration Reference - All configuration options

Storybook Setup

On this page