@crvy/rprtr

Playwright reporter with a visual regression UI for comparing and approving screenshot test diffs.

Pronunciation: crvy sounds like "creevey," not "curvy."

Installation

npm install --save-dev @crvy/rprtr

Requires: Playwright ≥1.40, plus Node 22+ or Bun for the live UI server/CLI. You can install the package with npm, pnpm, yarn, or Bun.

Setup

Add the reporter to your playwright.config.ts:

import { defineConfig } from '@playwright/test'

export default defineConfig({
  reporter: [['@crvy/rprtr', { screenshotDir: './screenshots' }]],
})

Viewing Results

Start the UI server to view and approve screenshot diffs:

npx crvy-rprtr

Other package-manager launchers work too: pnpm dlx crvy-rprtr, yarn dlx crvy-rprtr, and bunx crvy-rprtr.

Open http://localhost:3000 in your browser.

Every test run also writes a browser-openable static artifact:

• ./crvy-rprtr.html

Open crvy-rprtr.html directly from CI artifacts or your filesystem to review results without starting a server. The static artifact is self-contained except for screenshot image files, and it is read-only; use the server-backed UI to approve screenshots.

To open downloaded CI artifacts with the full approval UI, point the CLI at the artifact directory:

npx crvy-rprtr ./artifacts

Reporter Options

| Option | Type | Default | Description | | ------------------- | -------- | ------------------------------ | -------------------------------------------------- | | serverUrl | string | "ws://localhost:3000" | WebSocket URL of the Crvy Rprtr server | | screenshotDir | string | "./screenshots" | Directory for saving screenshot artifacts | | offlineReportPath | string | "./crvy-rprtr-{worker}.json" | Path for offline report when server is unavailable | | reportHtmlPath | string | "./crvy-rprtr.html" | Path for the browser-openable static report HTML |

Server CLI Options

npx crvy-rprtr [artifact-dir] [options]

If artifact-dir is provided, the CLI treats it as the directory containing:

• report.json
• screenshots/
• crvy-rprtr-*.json

Explicit flags override the paths derived from artifact-dir.

| Option | Short | Default | Description | | ------------------ | ----- | --------------- | ----------------------------------------------------------------------------------------- | | --port | -p | 3000 | Server port | | --screenshot-dir | -s | ./screenshots | Screenshot directory path | | --report-path | -r | ./report.json | Report JSON file path or directory containing report.json and crvy-rprtr-*.json files |

How It Works

1. During test runs: The Playwright reporter sends test results to the server via WebSocket in real-time and records the same run for artifact export.
2. After tests complete: A static crvy-rprtr.html artifact is written for direct browser viewing, and offline report JSON is also written if the server was unavailable.
3. In the browser: The UI shows all screenshot tests with side-by-side, swap, slide, and blend diff views.
4. Approving changes: Start the UI server and click "Approve" to accept a new screenshot as the baseline. The server copies the actual image to the expected snapshot location.

Offline Mode

When the server isn't running during tests, the reporter automatically falls back to offline mode:

• Test events are queued in memory
• On test completion, events are written to crvy-rprtr-{index}.json
• On test completion, a self-contained crvy-rprtr.html is written for direct browser review
• When the server starts, it loads and merges all crvy-rprtr-*.json files from the offline report directory

Programmatic API

import { startServer } from '@crvy/rprtr/server'

// reportPath can be a directory (will use report.json inside)
await startServer({
  port: 3000,
  screenshotDir: './screenshots',
  reportPath: './artifacts',
})

// Or a specific file path
await startServer({
  port: 3000,
  screenshotDir: './screenshots',
  reportPath: './artifacts/report.json',
})

The programmatic server API works in both Node 22+ and Bun.

Development

bun install
bun run dev      # Start dev server with HMR
bun run build    # Build for production
bun run test     # Run tests
bun run lint     # Lint with oxlint

License

MIT