@dinaalghazali/ui-vrt-kit

npm package to scaffold and run dynamic Storybook visual regression tests: Playwright reads storybook-static/index.json, captures pixel screenshots per story and viewport, and fails when the UI (layout, typography, colors) drifts from committed baselines.

Scope / name: The published name defaults to @dinaalghazali/ui-vrt-kit. Before npm publish, change "name" in package.json if you use a different npm scope or unscoped name.

Why uivrt (not vrt)?

This package exposes the uivrt and ui-vrt-kit binaries so it does not clash with other tools that already register vrt globally (for example @dinaalghazali/visual-regression-kit).

Install (consumers)

After publish:

npm install -D @dinaalghazali/ui-vrt-kit

You still need @playwright/test in the target project and browsers:

npm install -D @playwright/test
npx playwright install

Commands

uivrt init [targetDir] [--force]

Copies into the project root (default: current directory):

• docs/ (includes VISUAL_REGRESSION_DYNAMIC.md)
• tests/visual-dynamic/**
• npm-scripts.example.json (merge manually or use merge-scripts)

uivrt merge-scripts [targetDir] [--force]

Merges keys from npm-scripts.example.json (from the package template) into the target package.json → scripts:

• New keys are added.
• Existing keys with the same value are left as-is (logged as unchanged).
• Existing keys with a different value are skipped with a warning unless --force (then overwritten).

uivrt run test [targetDir]

Runs:

1. npm run build-storybook
2. npx playwright test -c tests/visual-dynamic/playwright.config.ts

uivrt run update [targetDir]

Same as run test, plus --update-snapshots to refresh PNG baselines after you intentionally accept UI changes.

npx (no install)

npx --yes -p @dinaalghazali/ui-vrt-kit uivrt init
npx --yes -p @dinaalghazali/ui-vrt-kit uivrt merge-scripts
npx --yes -p @dinaalghazali/ui-vrt-kit uivrt run test

On Git Bash / MSYS on Windows, prefer uivrt (short bin) over the hyphenated package shim if the shim misbehaves.

Seeing pixel diffs (Playwright)

When run test fails, Playwright’s HTML reporter shows Expected / Actual / Diff:

npx playwright show-report

(Run from the same project root where tests ran.)

npm install does not auto-edit your package.json; use uivrt merge-scripts when you want the standard scripts added.

Publish (maintainers)

From packages/ui-vrt-kit/:

npm pack
npm publish --access public

Bump version in package.json for each release.

Refresh template/ from this monorepo

If visual-regression-scaffold/ at the repo root changes, copy it into this package before publishing:

# repo root (PowerShell)
Remove-Item -Recurse -Force packages/ui-vrt-kit/template -ErrorAction SilentlyContinue
New-Item -ItemType Directory -Force -Path packages/ui-vrt-kit/template
Copy-Item -Path visual-regression-scaffold/* -Destination packages/ui-vrt-kit/template -Recurse

License

MIT — see LICENSE.