visual-regression.mjs

Captures reference screenshots of a fixed set of UI scenes with Playwright, or checks the live render against those references.

Contributor tooling › visual-regression.mjs

What it does

Captures a fixed set of UI scenes as reference screenshots with Playwright, or checks the live render against those references. Boots its own vite dev server and a headless Chromium browser for either subcommand. Reports each checked scene as passing, allowed, riding a measured noise floor, or failing, and exits non-zero when any scene fails or errors.

Usage

No npm run alias wraps it. Two subcommands, run directly:

node tools/visual-regression.mjs capture

node tools/visual-regression.mjs check

Options

Flag	Value	What it does	Default
--allow	scene id	Marks that scene's check result allowed-delta instead of fail when its diff is non-zero and over the scene's noise floor. Repeatable, once per scene id.	off, no scene id is pre-allowed
--base-url	URL	The already-running dev loop --live attaches to, instead of the vite port the worktree registry names for this checkout. Read only under --live, and only by capture and check.	the registry's vite port for this worktree
--disable-gpu	not a CLI flag	The fixed Chromium launch argument every browser instance starts with (BROWSER_LAUNCH_ARGS); the script never reads this string from argv.	always applied; the caller cannot turn it off
--host	not a CLI flag	The fixed host, 127.0.0.1, passed to the vite dev server this tool boots for itself; the script never reads this string from argv.	fixed at 127.0.0.1
--live	none	Captures and checks against a running dev loop instead of the vite server this tool boots for itself: keeps the three live-only scenes, opens a session, and holds the world clock at 1x for the run, restoring the prior rate after. References move to .gwtmp/perf/references-live.	off, live-only scenes are dropped and references come from .gwtmp/perf/references
--port	number	The port capture and check boot their own vite dev server on.	5301
--references-dir	path	Where capture writes reference screenshots and check reads them from, resolved from the current working directory.	.gwtmp/perf/references
--scenes	a,b,c	Restricts the run to the named, comma-separated scene ids instead of all five default scenes.	planet-idle, planet-midpan-freeze, system-scale, galaxy-scale, station-resources

Inputs and outputs

check reads the reference files an earlier capture wrote under --references-dir: pixels.rgba, meta.json, and mask.json per scene.

capture writes pixels.rgba, canvas.png, screenshot.png, meta.json, and mask.json per scene, plus roster-cell-measurement.json and manifest.json for the whole directory. check writes one file, last-check-report.json, into the same directory.

check exits 0 when every scene passes, rides its noise floor, or is allowed, and 1 when any scene fails or errors. Neither subcommand given, or an unrecognized one, prints the usage line and exits 2. An uncaught error, such as vite failing to boot, exits 1.

Examples

Capture fresh references after a deliberate visual change:

node tools/visual-regression.mjs capture

Check the live render against the committed references, the way the browser build suite does:

node tools/visual-regression.mjs check

Recheck two scenes only, and accept one of them as a known, reviewed delta:

node tools/visual-regression.mjs check --scenes system-scale,galaxy-scale --allow system-scale

Notes

Every run checks the booted world's seed against a fixed constant, REFERENCE_SEED_EXPECTED. A mismatch throws, naming the fix: update the constant in this file, then recapture, since every reference goes stale at once when the default world's seed changes.

A pass-noise-floor result is not byte-identical. It only stayed under a per-scene, hand-measured pixel-count tolerance, and the tool warns on stderr when a scene passes this way.

This file also exports bootVite, browserAvailable, MAP_CANVAS_SELECTOR, captureScenes, checkScenes, and SCENES, which several files under test/perf, test/build, and test/proto import directly instead of shelling out to the CLI.

Source

tools/visual-regression.mjs — part of Contributor tooling