![\"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%2Fnode?style=flat-square&logo=white\")
\n ![\"MIT](\"https://img.shields.io/github/license/reg-viz/storycap-testrun?label=license&style=flat-square\")
\n\n
Node.js screenshot capture for Storybook Test Runner - Provides stable screenshot functionality using Playwright for visual regression testing.
\n\n---\n\n`@storycap-testrun/node` implements stable screenshot capture for [`@storybook/test-runner`][storybook-test-runner] using the same reliability approach as [storycap][storycap] :camera:\n\n## Why `@storycap-testrun/node`?\n\nStandard `waitForPageReady` in [`@storybook/test-runner`][storybook-test-runner] provides only basic stability checks, often resulting in flaky visual tests.\n\n`@storycap-testrun/node` solves this by implementing [storycap][storycap]'s proven stability detection:\n\n- **Metrics monitoring** via [CDP][cdp] (Chrome DevTools Protocol) for rendering completion\n- **Hash verification** across multiple screenshot captures for content consistency\n- **Flaky test prevention** with masking and element removal capabilities\n\nThis ensures reliable visual regression testing without the common issues of timing-based approaches.\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- Integration with @storybook/test-runner\n- CDP-based metrics monitoring\n\n### Limitations\n\n- **Single viewport per test run**\n - A limitation of [@storybook/test-runner](storybook-test-runner). It can be addressed by running tests in multiple Viewports as needed\n- **No pseudo-state variants** (`:hover`, `:focus`, etc.)\n - Intentionally excluded to avoid conflicts with other `postVisit` hooks\n - **Workaround**: Use Story play functions to set desired states before screenshot capture\n\n## Installation\n\nInstall via npm:\n\n```bash\n$ npm install --save-dev @storycap-testrun/node\n```\n\n## Getting Started\n\nPlease set up [`@storybook/test-runner`][storybook-test-runner] beforehand.\n\nYou can start using it immediately by calling the `screenshot` function in `postVisit`.\n\n```typescript\n// .storybook/test-runner.ts\nimport type { TestRunnerConfig } from '@storybook/test-runner';\nimport { screenshot } from '@storycap-testrun/node';\n\nconst config: TestRunnerConfig = {\n async postVisit(page, context) {\n await screenshot(page, context, {\n // options...\n });\n },\n};\n\nexport default config;\n```\n\n> [!IMPORTANT]\n> Since the `screenshot` function automatically performs stability checks internally, waiting functions like `waitForPageReady` are unnecessary.\n\n```bash\n$ test-storybook\n```\n\nThen, run [`@storybook/test-runner`][storybook-test-runner].\n\nBy default, the screenshot images are saved in the `__screenshots__` directory.\n\n### TypeScript Setup\n\nEnable type checking for screenshot parameters by extending your Storybook framework's module declaration.\n\nAdd this to a `.d.ts` file in your project (e.g., `types/storybook.d.ts`):\n\n```typescript\nimport type { ScreenshotParameters } from '@storycap-testrun/node';\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\nThis enables IntelliSense and type checking when defining screenshot parameters in your stories.\n\n## API\n\n### `screenshot(page, context, options)`\n\n- `page: Page`\n - The Playwright page instance passed in `postVisit`.\n- `context: TestContext`\n - The test context from [`@storybook/test-runner`][storybook-test-runner] passed in `postVisit`.\n- `options: NodeScreenshotOptions`\n - See [Options Section](#options).\n- Returns: `Promise