Reglance

Visual regression at a glance. Reglance screenshots a site across viewports, compares each page against a saved baseline, and opens an HTML report of the visual and HTML differences. It installs per-project and is configured with one reglance.json file.

Quick start

1. Install (downloads a headless Chromium on install):

   npm install @happyprime/reglance --save-dev

2. Add a reglance.json to the project root. List page paths relative to a default domain:

   {
   	"name": "My Site",
   	"domain": "https://site.test",
   	"paths": {
   		"home": "/",
   		"blog": "/blog",
   		"single-post": "/blog/sample-post"
   	}
   }

3. Run the workflow:

   npx reglance capture   # screenshot every path (against the good state)
   npx reglance control   # save those captures as the baseline
   # ...make your changes...
   npx reglance capture   # screenshot again
   npx reglance compare   # diff against the baseline and open the report

control is run once to set the baseline; capture + compare are repeated to check changes against it. Output (captures, baseline, report) goes to a self-ignored .reglance/ directory — nothing to add to .gitignore.

reglance.json

| Field | Required | Description | | ------------------- | -------- | --------------------------------------------------------------------------------- | | paths | yes | Map of key → path. A value may be a full URL to point at a different domain. | | domain | capture | Default domain. A bare host (site.test) becomes https://site.test. | | name | no | Label shown in the report. Defaults to the domain host. | | viewports | no | [{ name, width, height, deviceScaleFactor? }]. Defaults to desktop (1920×1080), mobile (390×844). | | output | no | Output directory. Defaults to .reglance. | | pixelmatchOptions | no | pixelmatch options, e.g. { "threshold": 0.1 }. | | timeouts | no | { goto, settle } in ms. goto bounds navigation; settle bounds each post-scroll wait (network idle, then image load/decode). Defaults { goto: 15000, settle: 8000 }. Raise settle for slow, lazy-loading pages. | | blockHosts | no | Hostnames to block requests to during capture, e.g. ["captcha.example.com"]. Each entry also blocks its subdomains. | | imageCache | no | Serve repeat image requests from a local cache during capture. true for a per-run cache, { "persist": true } to keep it across runs. Off by default. |

domain is only needed by capture; control and compare work on the files already captured. See reglance.example.json for a full example.

blockHosts aborts every request to the listed hosts (and their subdomains) before it leaves the browser. Use it for third-party embeds that keep the network busy and stall capture — CAPTCHA widgets, ad tech, analytics — or that render differently on every load and pollute diffs. Captures wait for the network to go idle, so a widget that polls or retries indefinitely will otherwise time out every viewport on pages that embed it. Entries are bare hostnames; "example.org" blocks example.org and sub.example.org alike.

imageCache keeps a capture run from swarming the origin with the same image requests once per viewport per parallel context. Image requests are intercepted in the browser: the first request for a URL is fetched from the origin and stored under .reglance/image-cache/, and every repeat is answered locally — simultaneous requests for the same URL share a single origin fetch. The full URL, query string included, is the cache key, so CDN resize variants (photo.jpg?w=400 vs photo.jpg?w=800) stay distinct. Nothing in the page is rewritten and only images are cached — the HTML, CSS, and JS under test always load from the origin. With true the cache is cleared at the start of every run, so within-run traffic drops with zero risk of a stale image masking a real change. { "persist": true } keeps the cache across runs — useful when re-capturing repeatedly while iterating on CSS — but a changed origin image will then go unnoticed until you clear it with --fresh-images.

A viewport's optional deviceScaleFactor (device pixel ratio) renders the page as it would appear on a higher-density display — use 2 for a retina capture, 3 for some phones. It defaults to 1. Captures sharing a DPR run in one browser context; a new DPR opens a fresh context, so prefer grouping retina and non-retina variants rather than scattering them. Note that a 2× screenshot is twice the pixel dimensions of its 1× counterpart, so changing the deviceScaleFactor of an existing viewport will diff against its controls as fully changed until you re-run reglance control.

A paths value may be a full URL pointing at a different host than domain. This is supported, but capture prints a warning listing such paths so off-domain navigation is a conscious choice — keep configs from trusted sources, since the report renders captured content.

Commands

| Command | Description | | ------------------- | ------------------------------------------------------------------- | | reglance capture | Screenshot every path across all viewports into .reglance/captures. | | reglance control | Promote the latest captures to the baseline (.reglance/controls). | | reglance compare | Diff the latest captures against the baseline and open an HTML report. |

Append path keys to limit a command to specific pages: npx reglance capture home blog.

Options

| Flag | Command | Description | | -------------------------- | ------- | --------------------------------------------------------------------------------- | | --domain=<host> | capture | Override the configured domain for this run. | | --concurrency=<n> | capture | Parallel browser contexts (default: 4). Must be a positive integer. | | --stagger=<ms> | capture | Delay between starting contexts (default: 500). 0 disables staggering. | | --skip-reload | capture | Reuse the page between viewports instead of reloading. | | --fail-on-degraded | capture | Exit non-zero if any page failed to load cleanly (for CI). Default: warn, exit 0. | | --fresh-images | capture | Clear a persistent image cache before capturing (see imageCache). | | --insecure | capture | Ignore TLS certificate errors for non-local hosts (already ignored for .test/localhost). | | --compare-concurrency=<n>| compare | Parallel diff workers (default: CPU count − 1). Lower it for very tall pages. | | --no-open | compare | Don't open the report when finished. | | --config=<path> | any | Path to the config file (default: reglance.json). |

Per-developer domains

domain is the shared default; override it per run so teammates can point at their own local site without editing the config:

npx reglance capture --domain=site2.test

Trustworthy baselines

A baseline is only useful if it reflects pages that actually loaded. reglance guards against silently baselining bad data:

• If a page never loads cleanly (after retries), capture reports it as degraded instead of treating it as a success. Add --fail-on-degraded to make the run exit non-zero in CI.
• capture scrolls each page one viewport at a time so every lazy-loaded image is triggered, then waits (bounded by timeouts.settle) for all images to load and decode before screenshotting — and warns per capture when any image was still loading, instead of silently shipping a partial screenshot.
• control records each promotion in .reglance/controls/manifest.json and warns when it promoted fewer captures than expected (so the untouched controls are now stale). compare warns when the baseline mixes controls from more than one control run.

Output

.reglance/
	captures/   Latest screenshots + HTML snapshots
	controls/   Baseline screenshots + HTML (+ manifest.json)
	compares/   Diff images
	reports/    The report — open reports/index.html
	assets/     Report stylesheet + script
	image-cache/ Cached image responses (only with imageCache enabled)

The report is a single reports/index.html that embeds every result as JSON and renders three views client-side from the URL hash — a triage overview (grouped by page, changed-only by default, keyboard-navigable), a comparison view (swipe, side-by-side, onion skin, diff overlay, blink), and a unified HTML diff. It opens straight from disk with no network access.

Development

npm run lint   # check style
npm run fix    # auto-fix style