![\"GitHub](\"https://img.shields.io/github/actions/workflow/status/reg-viz/storycap-testrun/ci.yaml?branch=main&style=flat-square&logo=GitHub%20Actions&logoColor=white\")
\n ![\"NPM](\"https://img.shields.io/npm/v/%40storycap-testrun%2Fbrowser?style=flat-square&logo=white\")
\n ![\"MIT](\"https://img.shields.io/github/license/reg-viz/storycap-testrun?label=license&style=flat-square\")
\n\n
Screenshot capture for Storybook addon-vitest - Provides stable visual testing functionality and Vitest plugin for Storybook stories running in browser environments.
\n\n---\n\n**@storycap-testrun/browser** brings reliable visual testing to [`@storybook/addon-vitest`][storybook-addon-vitest] with the same stability approach as [storycap][storycap], optimized for Vitest browser environments :camera:\n\n## Why `@storycap-testrun/browser`?\n\n[`@storybook/addon-vitest`][storybook-addon-vitest] enables running Storybook tests directly in the browser environment. While the underlying `@vitest/browser` provides basic screenshot functionality, it lacks the specialized features needed for reliable visual regression testing:\n\n**Limited visual testing capabilities:**\n\n- Basic screenshot API without stability detection\n- No automatic waiting for rendering completion\n- Fixed file paths with limited configuration options\n- No built-in handling for dynamic content or animations\n- Missing retry mechanisms for flaky captures\n\n`@storycap-testrun/browser` enhances the basic functionality with production-ready features:\n\n**Stability and reliability:**\n\n- **Intelligent waiting**: Automatically detects when rendering is truly complete using CDP metrics\n- **Hash verification**: Ensures screenshot consistency through multiple capture comparison\n- **Flaky prevention**: Built-in masking and removal for dynamic content\n\n**Developer experience:**\n\n- **Flexible file management**: Full control over screenshot paths and naming conventions\n- **Story-level configuration**: Per-story parameters for skip, delay, mask, remove, and viewport\n- **Vitest plugin**: Seamless integration with Vitest's configuration and lifecycle\n\n**Performance optimizations:**\n\n- **Metrics monitoring**: Uses Chrome DevTools Protocol for efficient stability detection (Chromium)\n- **Smart retries**: Configurable retry logic that minimizes unnecessary captures\n- **Browser-native execution**: Screenshots captured directly in the test environment without external automation\n\nThis makes it ideal for teams who need more than basic screenshots - providing the reliability and flexibility required for production visual regression testing workflows.\n\n### Features\n\n- High stability checks for rendering content\n- Accurate waiting for Play Function\n- Customization before and after screenshot capture using Hooks\n- Masking of unstable elements\n- Removal of unstable elements\n- Skipping of unstable elements\n- Easy setup with Vitest plugin\n- Integration with Storybook addon-vitest\n\n### Requirements\n\n- Vitest browser mode with Playwright provider\n- `@storybook/addon-vitest` setup\n\n### Limitations\n\n- **Metrics monitoring limited to Chromium browsers**\n - Full stability checks work only with Chromium-based browsers (Chrome, Edge, etc.)\n - **Fallback**: Other browsers use hash verification only (still effective, but slower)\n- **Browser environment constraints**\n - Limited to capabilities available in browser context.\n- **Full-page screenshots with `position: fixed/sticky`**\n - When capturing full-page screenshots of content larger than the viewport, elements with `position: fixed` or `position: sticky` may appear duplicated in the output image.\n- **Incompatible with `browser.ui`**\n - The Vitest UI keeps mutating the page, so the CDP metrics never settle and every capture ends in `MetricsTimeoutError`. `browser.ui` is already off whenever `headless: true` is set.\n- **Only Chromium is exercised**\n - The examples and CI run Chromium. Firefox and WebKit should work through the hash-verification fallback, but are not verified.\n\n## Installation\n\nInstall via npm:\n\n```bash\n$ npm install --save-dev @storycap-testrun/browser\n```\n\n## Getting Started\n\nPlease set up [`@storybook/addon-vitest`][storybook-addon-vitest] beforehand.\n\n### 1. Configure Vitest\n\nAdd the storycap plugin to your `vitest.config.js`:\n\n```javascript\nimport path from 'node:path';\nimport { defineConfig, defineProject } from 'vitest/config';\nimport { storybookTest } from '@storybook/addon-vitest/vitest-plugin';\nimport { playwright } from '@vitest/browser-playwright';\nimport storycap from '@storycap-testrun/browser/vitest-plugin';\n\nexport default defineConfig({\n test: {\n projects: [\n defineProject({\n plugins: [\n storybookTest({\n configDir: '.storybook',\n storybookScript: 'storybook --ci',\n }),\n storycap({\n viewport: {\n width: 1280,\n height: 720,\n },\n }),\n ],\n test: {\n name: 'storybook',\n browser: {\n enabled: true,\n provider: playwright(),\n headless: true,\n instances: [{ browser: 'chromium' }],\n },\n setupFiles: ['./.storybook/vitest.setup.ts'],\n },\n }),\n ],\n },\n});\n```\n\n### 2. Setup Screenshot Capture\n\nCreate `.storybook/vitest.setup.ts`:\n\n```typescript\nimport { afterEach, beforeEach } from 'vitest';\nimport { page } from '@vitest/browser/context';\nimport { screenshot } from '@storycap-testrun/browser';\nimport { setProjectAnnotations } from '@storybook/react-vite'; // Adjust for your framework\nimport * as projectAnnotations from './preview';\n\nsetProjectAnnotations([projectAnnotations]);\n\n// Sizes the iframe while the test body runs. The captured image uses the\n// storycap plugin's viewport option instead.\nbeforeEach(async () => {\n await page.viewport(1280, 720);\n});\n\nafterEach(async (context) => {\n await screenshot(page, context);\n});\n```\n\n**`beforeEach` with `page.viewport()`**\n\n`page.viewport()` sizes the Vitest iframe while your test body runs, so it is what play functions and interaction assertions see. It does not decide the screenshot dimensions: immediately before capturing, storycap lays the story out at the plugin's `viewport` size, and the image is taken at that size.\n\nSet it when a play function depends on the viewport. Otherwise the captured image size is controlled by the plugin's `viewport` option, optionally overridden per story with the [`viewport` parameter](#viewport-1).\n\n**`afterEach` with `screenshot()`**\n\n- **Post-story state**: Captures the final state after all story rendering and play functions complete\n- **Test isolation**: Each story gets its own screenshot without interference from previous tests\n- **Automatic execution**: No need to manually call screenshot in every story file\n\n### 3. Run Tests\n\n```bash\n$ vitest run --project=storybook\n```\n\nBy default, the screenshot images are saved in the `__screenshots__` directory.\n\n### TypeScript Setup\n\nBy importing types and merging them for the framework you use, you can enable type checking for parameters specified in each Story.\n\n```typescript\nimport type { ScreenshotParameters } from '@storycap-testrun/browser';\n\n// Replace it with the framework you are using.\ndeclare module '@storybook/react' {\n interface Parameters {\n screenshot?: ScreenshotParameters;\n }\n}\n\n// For other frameworks, replace with your framework's module name\n```\n\n## API\n\n### `screenshot(page, context, options)`\n\n- `page: BrowserPage`\n - The page instance from `@vitest/browser/context`.\n- `context: TestContext`\n - The test context from Vitest passed in setup hooks.\n- `options: BrowserScreenshotOptions`\n - See [Options Section](#options).\n- Returns: `Promise