Storybook Visual Testing That Works with Your Workflow

If you’re building a component library or design system with Storybook, you’ve probably wondered: how do I actually test that these components look right? Sure, Storybook gives you an isolated environment to view each component, but that’s not the same as systematically tracking visual changes or collaborating with your team on those changes.

The new Vizzly Storybook SDK solves exactly this. It brings your Storybook stories into Vizzly’s visual development workflow, which means you get local TDD iteration with vizzly tdd and seamless team collaboration through automatic CI/CD builds. Let me show you how it works.

What You Actually Get

Here’s the thing about visual testing for Storybook: you don’t want a separate testing tool. You want visual quality integrated into how you already work. The Vizzly Storybook SDK does three things that matter:

1. Captures screenshots from your Storybook build - All your stories, all your viewports, zero manual work
2. Integrates with your development workflow - Use vizzly tdd locally to see visual changes as you code
3. Enables team collaboration - Automatic CI/CD builds with position-based comments, mentions, review decisions, and deep links

What makes this different from other Storybook visual testing solutions is that it’s part of a real development workflow. You’re not just comparing screenshots - you’re making visual quality part of how your team ships components.

Quick Start

Install the Storybook SDK alongside the Vizzly CLI:

npm install -D @vizzly-testing/cli @vizzly-testing/storybook

The plugin auto-discovers through the @vizzly-testing/* scope, so it’s immediately available. Here’s the fastest way to try it locally:

# Build your Storybook
npm run build-storybook

# Start TDD server and capture screenshots
vizzly tdd start
vizzly storybook ./storybook-static

# View results at http://localhost:47392

The vizzly storybook command automatically detects the TDD server and sends screenshots there. For CI/CD with a VIZZLY_TOKEN, it automatically uploads to the cloud instead.

Local TDD Workflow

Here’s where it gets interesting. When you’re building a new component or updating an existing one, you want to see exactly what changed visually as you code. vizzly tdd gives you that.

# Start TDD server (runs in background)
vizzly tdd start

# Build Storybook and capture screenshots
npm run build-storybook
vizzly storybook ./storybook-static

# View results at http://localhost:47392

The TDD dashboard shows you:

• Live comparisons - See visual diffs in real-time as you iterate
• Multiple diff modes - Overlay, side-by-side, onion skin, toggle views
• Baseline management - Accept/reject changes directly in the UI
• Test statistics - Real-time pass/fail metrics

What I love about this workflow is you’re not waiting for CI to tell you something broke. You know immediately when a CSS change affects a component you didn’t expect it to touch. That’s the visual development workflow we’re talking about.

Automatic Team Builds from CI/CD

Once you’re happy with your changes locally, your CI/CD pipeline takes over. Every commit automatically creates a team build with sophisticated collaboration tools.

Here’s a GitHub Actions example:

name: Visual Tests

on: [push, pull_request]

jobs:
  visual-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install dependencies
        run: npm ci

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

      - name: Capture Storybook Screenshots
        run: npx vizzly storybook ./storybook-static
        env:
          VIZZLY_TOKEN: ${{ secrets.VIZZLY_TOKEN }}

When VIZZLY_TOKEN is present, the command automatically uploads screenshots to the cloud and creates a build for team review. The exit code will be non-zero if visual differences are detected, failing your CI build appropriately.

Advanced Collaboration Features

This is where Vizzly’s collaboration system shines. When your team reviews a build:

• Position-based comments - Click directly on areas of screenshots to start conversations
• Review decisions - Approve or reject changed and new screenshots
• Mentions and notifications - Tag teammates and get notified about visual changes
• Deep links - Share specific feedback via direct URLs

Let’s say you updated the Button component and it affected the Card component in an unexpected way. Your teammate can click directly on the Card story screenshot, leave a comment about the padding change, mention you, and you’ll get a notification. That’s real collaboration, not just image comparison.

Configuration Options

You can configure the Storybook SDK through a vizzly-storybook.config.js file:

export default {
  viewports: [
    { name: 'mobile', width: 375, height: 667 },
    { name: 'tablet', width: 768, height: 1024 },
    { name: 'desktop', width: 1920, height: 1080 },
  ],

  concurrency: 3,

  // Pattern-based hooks for interactions
  interactions: {
    'Button/*': async (page) => {
      await page.hover('button');
    },
    'Tooltip/*': async (page) => {
      await page.click('.tooltip-trigger');
    },
  },
};

Or configure specific stories inline:

// Button.stories.js
export let WithTooltip = {
  args: { label: 'Hover me' },
  parameters: {
    vizzly: {
      viewports: [
        { name: 'mobile', width: 375, height: 667 },
      ],
      beforeScreenshot: async (page) => {
        await page.hover('button');
        await page.waitForSelector('.tooltip', { visible: true });
      },
    },
  },
};

The interaction hooks are particularly useful for components with hover states, open dropdowns, or other dynamic behaviors you want captured in your visual tests.

Migrating from Chromatic

If you’re currently using Chromatic for Storybook visual testing, here’s the practical migration path:

What Changes

CI/CD Workflow:

# Before (Chromatic)
- run: npx chromatic --project-token=${{ secrets.CHROMATIC_PROJECT_TOKEN }}

# After (Vizzly)
- name: Build Storybook
  run: npm run build-storybook

- name: Capture Screenshots
  run: npx vizzly storybook ./storybook-static
  env:
    VIZZLY_TOKEN: ${{ secrets.VIZZLY_TOKEN }}

The main difference: Chromatic builds Storybook internally, while Vizzly works with your static build. This gives you more control over the build process and makes it simpler - just one command with your token set.

Story Parameters:

Chromatic uses chromatic parameters in your stories:

// Chromatic approach
export let ButtonStory = {
  parameters: {
    chromatic: {
      viewports: [320, 1200],
      delay: 300,
      disableSnapshot: false,
    },
  },
};

Vizzly uses vizzly parameters with a similar structure:

// Vizzly approach
export let ButtonStory = {
  parameters: {
    vizzly: {
      viewports: [
        { name: 'mobile', width: 320, height: 568 },
        { name: 'desktop', width: 1200, height: 800 },
      ],
      beforeScreenshot: async (page) => {
        // Replaces chromatic.delay with explicit control
        await page.waitForTimeout(300);
      },
      skip: false, // Replaces chromatic.disableSnapshot
    },
  },
};

Global Configuration:

Instead of CLI flags and Chromatic’s .chromatic.yml, Vizzly uses vizzly-storybook.config.js:

// vizzly-storybook.config.js
export default {
  viewports: [
    { name: 'mobile', width: 375, height: 667 },
    { name: 'desktop', width: 1920, height: 1080 },
  ],

  concurrency: 3,

  // Pattern-based interactions (more powerful than Chromatic's global delays)
  interactions: {
    'Button/*': async (page) => {
      await page.hover('button');
    },
  },
};

Migration Steps

1. Install Vizzly:

npm install -D @vizzly-testing/cli @vizzly-testing/storybook
npm uninstall chromatic  # Optional: remove when fully migrated

2. Move story parameters: Search and replace chromatic: with vizzly: in your .stories.js files. Update viewport arrays to objects with name, width, and height.

3. Create global config: Move your Chromatic CLI flags or .chromatic.yml settings into vizzly-storybook.config.js.

4. Update CI workflow: Replace the Chromatic action with Vizzly commands (see example above).

5. Establish baselines locally:

vizzly tdd run "vizzly storybook ./storybook-static" --set-baseline

This captures your current visual state as the baseline. Review in the TDD dashboard before committing.

What You Get with Vizzly

Local TDD workflow - The biggest workflow change is vizzly tdd. Instead of pushing to CI to see visual changes, you iterate locally with real-time feedback. This is a fundamental shift in how you develop components.

Team collaboration - Vizzly adds position-based comments, direct links to feedback, mentions, notifications, and review decisions.

Flexible screenshot sources - Since Vizzly works with static builds, you can integrate screenshots from anywhere: BrowserStack, Sauce Labs, Playwright with real browsers, mobile simulators, etc. You’re not locked into Chromatic’s rendering infrastructure.

The core philosophy difference: Chromatic treats visual testing as a cloud service. Vizzly treats it as a development workflow with local iteration and team collaboration built in.

Real-World Workflow

Here’s how this looks in practice for a component library team:

1. Developer makes changes locally:

   • Starts vizzly tdd start
   • Builds Storybook and runs vizzly storybook ./storybook-static
   • Sees visual changes immediately in the TDD dashboard
   • Accepts new baselines or fixes issues

2. Developer pushes to GitHub:

   • CI runs Storybook build automatically
   • Vizzly captures screenshots and compares to baselines
   • Team gets automatic build in Vizzly dashboard

3. Team reviews visual changes:

   • Design lead adds position-based comments on spacing issues
   • Frontend engineer mentions designer about color concerns
   • Product manager approves the changed screenshots

4. Changes get approved:

   • Build becomes new baseline
   • PR can merge
   • Visual changes are documented with full audit trail

No manual screenshot capture. No separate testing phase. Visual quality is just part of shipping components.

Supported Storybook Versions

The SDK works with Storybook v6.x, v7.x, and v8.x. We automatically discover your index.json file and process all your stories.

Try It Out

If you’re building UI components with Storybook and want visual quality integrated into your development process instead of bolted on afterward, give the Vizzly Storybook SDK a try.

npm install -D @vizzly-testing/cli @vizzly-testing/storybook
npm run build-storybook
vizzly tdd start
vizzly storybook ./storybook-static

Check out the Storybook SDK documentation for advanced configuration options and the examples guide for more integration patterns.

Visual bugs in component libraries are frustrating because they cascade to every app using those components. Might as well catch them while you’re still in the flow of coding, rather than discovering them days later in production.