StorySnap

Visual regression testing for Storybook. Capture screenshots of your components, detect visual changes, and maintain baselines with ease.

Features

• Automatic Story Discovery - Automatically finds and captures all stories from your Storybook
• Multi-Browser Support - Test across Chromium, Firefox, and WebKit
• Pixel-Perfect Comparison - Detects even the smallest visual differences
• CI/CD Integration - Works seamlessly with GitHub Actions, GitLab CI, and other CI platforms
• Local & Cloud Modes - Run tests locally or connect to StorySnap API for team collaboration
• Configurable Thresholds - Set custom tolerance levels for visual comparisons

Installation

# Using npm
npm install -D @storysnap/cli

# Using yarn
yarn add -D @storysnap/cli

# Using pnpm
pnpm add -D @storysnap/cli

# Or run directly with npx
npx @storysnap/cli --help

Quick Start

1. Initialize Configuration

npx @storysnap/cli init

This creates a storysnap.config.ts file in your project root.

2. Start Your Storybook

npm run storybook

3. Capture Baseline Screenshots

npx @storysnap/cli update

4. Run Visual Regression Tests

npx @storysnap/cli test

Configuration

StorySnap looks for configuration in the following order:

• storysnap.config.ts
• storysnap.config.js
• storysnap.config.json

Example Configuration

// storysnap.config.ts
import { defineConfig } from 'storysnap';

export default defineConfig({
  // Storybook URL (required)
  storybookUrl: 'http://localhost:6006',

  // Output directory for screenshots
  outputDir: '.storysnap',

  // Browsers to test (default: ['chromium'])
  browsers: ['chromium', 'firefox', 'webkit'],

  // Viewport sizes
  viewports: [
    { width: 1280, height: 720, name: 'desktop' },
    { width: 375, height: 667, name: 'mobile' },
  ],

  // Comparison threshold (0-1, default: 0.1)
  threshold: 0.1,

  // Stories to include (glob patterns)
  include: ['**/*.stories.*'],

  // Stories to exclude (glob patterns)
  exclude: ['**/docs/**'],
});

CLI Commands

storysnap init

Initialize StorySnap configuration in your project.

npx @storysnap/cli init [options]

Options:
  -f, --format <format>  Config file format (ts, js, json) [default: ts]
  --force               Overwrite existing config file

storysnap test

Run visual regression tests against baseline screenshots.

npx @storysnap/cli test [options]

Options:
  -c, --config <path>      Path to config file
  -s, --story <pattern>    Filter stories by pattern (supports * wildcards)
  -b, --browser <browsers> Browsers to test (chromium,firefox,webkit)
  --ci                     CI mode - fail on any visual diff or new story
  --local                  Force local-only mode without using the API
  -v, --verbose            Verbose output

storysnap update

Update baseline screenshots.

npx @storysnap/cli update [options]

Options:
  -c, --config <path>      Path to config file
  -s, --story <pattern>    Filter stories by pattern (supports * wildcards)
  -b, --browser <browsers> Browsers to test (chromium,firefox,webkit)
  --dry-run               Show what would be updated without making changes
  --local                  Force local-only mode without using the API
  -v, --verbose            Verbose output

storysnap login

Authenticate with the StorySnap API (for cloud mode).

npx @storysnap/cli login [options]

Options:
  -u, --api-url <url>   API URL
  -t, --token <token>   API token (will prompt if not provided)
  -v, --verbose         Verbose output

storysnap logout

Remove stored API credentials.

npx @storysnap/cli logout [options]

Options:
  -v, --verbose  Verbose output

CI/CD Integration

GitHub Actions

name: Visual Regression Tests

on:
  pull_request:
    branches: [main]

jobs:
  visual-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install dependencies
        run: npm ci

      - name: Build Storybook
        run: npm run build-storybook

      - name: Serve Storybook
        run: npx http-server storybook-static -p 6006 &

      - name: Run visual tests
        run: npx @storysnap/cli test --ci
        env:
          STORYSNAP_API_TOKEN: ${{ secrets.STORYSNAP_API_TOKEN }}

GitLab CI

visual-tests:
  image: mcr.microsoft.com/playwright:v1.40.0-jammy
  script:
    - npm ci
    - npm run build-storybook
    - npx http-server storybook-static -p 6006 &
    - npx @storysnap/cli test --ci
  variables:
    STORYSNAP_API_TOKEN: $STORYSNAP_API_TOKEN

Local Mode vs Cloud Mode

Local Mode (Default)

Screenshots are stored locally in your project directory (.storysnap/ by default). Perfect for individual developers or teams that prefer to store baselines in git.

Cloud Mode

Connect to the StorySnap API for:

• Centralized baseline storage
• Web dashboard for visual review
• Team collaboration features
• Approval workflows

To enable cloud mode:

npx @storysnap/cli login

Multi-Browser Testing

Test across multiple browsers simultaneously:

# Via CLI flag
npx @storysnap/cli test --browser chromium,firefox,webkit

# Via configuration
export default defineConfig({
  browsers: ['chromium', 'firefox', 'webkit'],
});

Baseline screenshots are stored per-browser:

.storysnap/
  baselines/
    button-primary-chromium.png
    button-primary-firefox.png
    button-primary-webkit.png

Troubleshooting

Storybook Not Found

Ensure your Storybook is running and accessible:

curl http://localhost:6006/index.json

Browser Installation

StorySnap uses Playwright for browser automation. Install browsers with:

npx playwright install chromium firefox webkit

Permission Errors

If you encounter permission errors on Linux, you may need to run:

npx playwright install-deps

Requirements

• Node.js 18 or higher
• A running Storybook instance (v6.0+)

License

MIT

Contributing

Contributions are welcome! Please read our contributing guidelines before submitting a pull request.