@storybook-visual-regression/cli
Advanced tools
A comprehensive visual regression testing tool for any Storybook project
A comprehensive command-line tool for visual regression testing of Storybook projects. This CLI integrates with Playwright to automatically discover all stories in your Storybook and compare them against visual baselines.
npm install --save-dev @storybook-visual-regression/cli
Install Playwright browsers:
npx playwright install chromium
Create a configuration file with default settings:
npx storybook-visual-regression init
This creates a svr.config.js file that you can customize.
If Storybook is already running:
npx storybook-visual-regression test
If you need the CLI to start Storybook automatically:
npx storybook-visual-regression test --command "npm run storybook"
After making intentional visual changes:
npx storybook-visual-regression test --update
npx storybook-visual-regression test
npx storybook-visual-regression test --update
npx storybook-visual-regression init
--url <url> - Storybook server URL (default: http://localhost:9009)--command <command> - Command to start Storybook server (e.g., npm run storybook)--port <number> - Storybook server port (default: 6006)--workers <number> - Number of parallel workers (default: 12)--retries <number> - Number of retries on failure (default: 0)--max-failures <number> - Stop after N failures (default: 10, 0 = stop on first failure)--output <dir> - Output directory for results (default: visual-regression)--grep <pattern> - Filter stories by regex pattern--include <patterns> - Include stories matching these patterns (comma-separated)--exclude <patterns> - Exclude stories matching these patterns (comma-separated)--browser <browser> - Browser to use: chromium, firefox, or webkit (default: chromium)--timezone <timezone> - Browser timezone (default: Europe/London)--locale <locale> - Browser locale (default: en-GB)--threshold <number> - Screenshot comparison threshold (0.0-1.0, default: 0.2)--max-diff-pixels <number> - Maximum number of pixels that can differ (default: 0)--full-page - Capture full-page screenshots--wait-timeout <ms> - Wait-for-element timeout in milliseconds--overlay-timeout <ms> - Maximum time to wait for Storybook's 'preparing' overlays to hide (default: 5000)--test-timeout <ms> - Playwright test timeout: maximum time for each test to complete--snapshot-retries <count> - Number of times to retry taking screenshot if it fails (default: 1)--snapshot-delay <ms> - Delay before taking screenshot (default: 0)--mutation-timeout <ms> - DOM stabilization timeout: wait after last DOM mutation (default: 100)--mutation-max-wait <ms> - Maximum total time to wait for DOM to stabilize (default: 10000)--webserver-timeout <ms> - Playwright webServer startup timeout (default: 120000)--not-found-check - Enable detection and retry for "Not Found" / 404 pages--not-found-retry-delay <ms> - Delay between "Not Found" retries (default: 200)--missing-only - Only create snapshots that do not already exist--failed-only - Run only the tests that failed in the previous test run--config <path> - Path to config file--quiet - Suppress verbose failure output--debug - Enable debug logging--print-urls - Show story URLs inline with test results--progress - Show progress spinners and time estimates--no-progress - Disable progress spinners (useful for CI pipelines)--install-browsers [browser] - Install Playwright browsers before running (chromium, firefox, webkit, or all)--install-deps - Install system dependencies for browsers (Linux CI)--save-config - Save CLI options to config file for future usenpx storybook-visual-regression test \
--url http://localhost:6006 \
--workers 8 \
--browser chromium \
--threshold 0.1
npx storybook-visual-regression test --grep "Button|Modal"
npx storybook-visual-regression test --update --failed-only
npx storybook-visual-regression test \
--command "npm run storybook" \
--url http://localhost:6006 \
--workers 4 \
--threshold 0.5 \
--max-diff-pixels 200 \
--timezone UTC \
--locale en-US \
--no-progress \
--max-failures 0
The CLI supports configuration via config files, CLI flags, or environment variables. CLI flags always override config file values.
The CLI automatically discovers config files in this order:
svr.config.js (JavaScript)svr.config.ts (TypeScript).svrrc.json (JSON)You can also specify a custom config file with --config <path>.
Create a default config file:
npx storybook-visual-regression init
Create a TypeScript config:
npx storybook-visual-regression init --format ts
Create a JSON config:
npx storybook-visual-regression init --format json
svr.config.js:
export default {
// Storybook server configuration
url: 'http://localhost:6006',
command: 'npm run storybook', // Comment out if Storybook is already running
// Test execution
workers: 16, // Number of parallel workers
retries: 0, // Number of retries on failure
maxFailures: 10, // Stop after N failures (0 = no limit)
output: 'visual-regression', // Output directory for results
// Browser settings
browser: 'chromium', // 'chromium' | 'firefox' | 'webkit'
timezone: 'Europe/London',
locale: 'en-GB',
// Performance tuning
waitTimeout: 30000, // Wait-for-element timeout (ms)
overlayTimeout: 5000, // Storybook overlay timeout (ms)
webserverTimeout: 120000, // Webserver startup timeout (ms)
snapshotRetries: 1, // Number of times to retry taking screenshot
snapshotDelay: 0, // Delay before taking screenshot (ms)
mutationTimeout: 100, // DOM stabilization timeout (ms)
mutationMaxWait: 10000, // Maximum time to wait for DOM stabilization (ms)
waitUntil: 'load', // 'load' | 'domcontentloaded' | 'networkidle' | 'commit'
// Story filtering (optional)
// include: ['Components/*', 'Screens/*'],
// exclude: ['**/Docs', '**/Experimental'],
// grep: 'button|modal',
// Screenshot configuration
threshold: 0.2, // Comparison threshold (0.0-1.0)
maxDiffPixels: 0, // Maximum pixels that can differ
fullPage: false, // Capture full-page screenshots
// Display options
quiet: false, // Suppress verbose failure output
debug: false, // Enable debug logging
printUrls: false, // Show story URLs inline with test results
noProgress: false, // Disable progress spinners (useful for CI)
// Advanced options
notFoundCheck: false, // Enable 'Not Found' content heuristic
notFoundRetryDelay: 200, // Delay between Not Found retries (ms)
};
You can set default values via environment variables:
SVR_URL=http://localhost:6006 \
SVR_WORKERS=8 \
npx storybook-visual-regression test
After running tests, you'll find:
visual-regression/
├── snapshots/ # Baseline screenshots (committed to git)
│ └── ComponentName/
│ └── StoryName.png
└── results/ # Test results (gitignored)
└── storybook-Visual-Regression-<hash>/
├── screenshot.png # Actual screenshot
└── diff.png # Diff image (if test failed)
name: Visual Regression Tests
on: [push, pull_request]
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- uses: actions/setup-node@v3
with:
node-version: '20'
- run: npm ci
- run: npx playwright install chromium --with-deps
- run: |
npx storybook-visual-regression test \
--command "npm run storybook" \
--url http://localhost:6006 \
--workers 4 \
--threshold 0.5 \
--max-diff-pixels 200 \
--timezone UTC \
--locale en-US \
--no-progress \
--max-failures 0
- uses: actions/upload-artifact@v3
if: failure()
with:
name: visual-regression-results
path: visual-regression/results/
For consistent font rendering across platforms:
docker build -t storybook-visual-regression .
docker run --rm \
-v $(pwd):/app \
-w /app \
storybook-visual-regression
See the root CROSS-PLATFORM-FONTS.md for more details.
Problem: CLI can't connect to Storybook
Solutions:
--url flag matches your Storybook server URL--debug flag for more informationProblem: Tests fail due to font rendering differences between platforms
Solutions:
--threshold and --max-diff-pixels for CI environments--timezone UTC and --locale en-US for consistencyProblem: Tests take too long to run
Solutions:
--workers for more parallelism--snapshot-retries and --snapshot-delay--mutation-timeout and --mutation-max-wait to fine-tune DOM stabilization--include or --exclude to test only what you needProblem: Tests fail due to memory errors
Solutions:
--workers count--max-failures to stop earlyNODE_OPTIONS="--max-old-space-size=4096"Problem: Baselines don't update or persist
Solutions:
visual-regression/snapshots/ directory--missing-only to only create new baselinesFor CI/CD integration, the CLI can output JSON results:
npx storybook-visual-regression test --json
The JSON output includes:
{
"status": "passed|failed|error",
"startTime": 1697548800000,
"duration": 5432,
"totalTests": 10,
"passed": 8,
"failed": 2,
"tests": [
{
"storyId": "components-button--primary",
"title": "Components / Button",
"name": "Primary",
"status": "passed|failed|error",
"duration": 2341,
"attachments": [
{
"name": "screenshot",
"path": "visual-regression/results/.../screenshot.png",
"type": "image/png"
}
]
}
]
}
The CLI uses Playwright under the hood. Key concepts:
index.jsonvisual-regression/snapshots/visual-regression/results/Contributions are welcome! See the root README.md for development setup.
MIT
FAQs
A comprehensive visual regression testing tool for any Storybook project
We found that @storybook-visual-regression/cli demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
A supply chain attack on Axios introduced a malicious dependency, plain-crypto-js@4.2.1, published minutes earlier and absent from the project’s GitHub releases.
Research
Malicious versions of the Telnyx Python SDK on PyPI delivered credential-stealing malware via a multi-stage supply chain attack.
Security News
TeamPCP is partnering with ransomware group Vect to turn open source supply chain attacks on tools like Trivy and LiteLLM into large-scale ransomware operations.