[!WARNING]

Migration Notice for Existing Users

If you're currently using the legacy storycap-testrun package, please note that v2 introduces breaking changes with a new package structure.

• For @storybook/test-runner users: Migrate to @storycap-testrun/node
• For @storybook/addon-vitest users: Use @storycap-testrun/browser

👉 See the complete Migration Guide for step-by-step upgrade instructions.

storycap-testrun implements the same stability checking approach as storycap, enabling reliable screenshot capture for Visual Regression Testing in Storybook workflows :camera:

Packages

This monorepo contains three packages:

@storycap-testrun/browser

Screenshot capture for Storybook addon-vitest - Provides stable visual testing functionality and Vitest plugin for Storybook stories running in browser environments.

@storycap-testrun/node

Node.js screenshot capture for Storybook Test Runner - Provides stable screenshot functionality using Playwright for visual regression testing.

Why storycap-testrun?

The Problem

Visual Regression Testing in Storybook faces different challenges depending on your testing framework:

Common challenges:

• Incomplete rendering detection leads to inconsistent screenshots
• Animation and dynamic content cause flaky test results
• No built-in mechanisms to handle unstable elements

Framework-specific limitations:

• @storybook/test-runner: Standard waitForPageReady provides only minimal stability checks
• @storybook/addon-vitest: Basic screenshot APIs lack stability detection and flexible configuration options

The Solution

storycap solved this by monitoring browser rendering metrics through CDP (Chrome DevTools Protocol) to accurately determine when content is fully stable. storycap-testrun brings this proven approach to modern Storybook testing workflows.

Key stability mechanisms:

• Metrics monitoring: Tracks rendering completion through browser performance metrics
• Hash verification: Ensures screenshot consistency by comparing image hashes across multiple captures
• Flaky test prevention: Built-in masking and element removal for dynamic content

This approach significantly reduces visual test flakiness while maintaining fast execution times.

Features

• High stability checks for rendering content
• Accurate waiting for Play Function
• Customization before and after screenshot capture using Hooks
• Masking of unstable elements
• Removal of unstable elements
• Skipping of unstable elements
• Support for both @storybook/test-runner and @storybook/addon-vitest
• CDP-based metrics monitoring in Chromium browsers

Which Package Should I Use?

Choose the right package based on your current Storybook testing setup:

Testing Framework	Package
@storybook/addon-vitest	@storycap-testrun/browser
@storybook/test-runner	@storycap-testrun/node

Not sure which testing framework you're using?

• If you run tests with vitest command → Use browser package
• If you run tests with test-storybook command → Use node package

Getting Started

Choose the package that matches your testing environment:

For @storybook/addon-vitest users

Use @storycap-testrun/browser package for Vitest browser environments.

npm install --save-dev @storycap-testrun/browser

See @storycap-testrun/browser documentation for detailed setup and usage.

For @storybook/test-runner users

Use @storycap-testrun/node package for Node.js environments with Playwright.

npm install --save-dev @storycap-testrun/node

See @storycap-testrun/node documentation for detailed setup and usage.

Common Features

Both packages share common functionality provided by @storycap-testrun/internal:

Story Parameters

Configure screenshot behavior for individual stories using these parameters:

// Button.stories.tsx
const meta: Meta<typeof Button> = {
  component: Button,
  parameters: {
    screenshot: {
      skip: false, // Skip screenshot capture for this story
      delay: 1000, // Additional delay after stability checks (ms)
      mask: '.dynamic-element', // Hide dynamic content with colored overlay
      remove: '.ads, .analytics', // Remove elements before screenshot
    },
  },
};

Parameter Details:

• skip: Disable screenshot capture while keeping other tests enabled
• delay: Extra wait time after automatic stability detection completes
• mask: CSS selector for elements to cover with a colored rectangle (useful for timestamps, random content)
• remove: CSS selector for elements to completely remove from the DOM (useful for ads, analytics)

Stability Detection

Automatic Stability Checks:

• Metrics Monitoring: Uses Chrome DevTools Protocol to monitor rendering completion signals (layout shifts, network activity, paint events)
• Hash Verification: Captures multiple screenshots and compares their hash values to ensure content stability
• Retry Logic: Automatically retries captures when instability is detected, with configurable limits

Why This Matters:

• Eliminates flaky tests caused by incomplete rendering
• Reduces false positives in visual regression detection
• Works reliably with animations, lazy-loaded content, and dynamic elements

For detailed API documentation, configuration options, and advanced usage, please refer to the specific package documentation:

• @storycap-testrun/browser documentation - For Vitest browser environments
• @storycap-testrun/node documentation - For Node.js environments

Examples

• Vitest + React example - Using @storycap-testrun/browser
• Test Runner + React example - Using @storycap-testrun/node

License

MIT © reg-viz