Elastishot

Elastic screenshot comparison for UI change detection. Compare two screenshots, or two versions of a page by URL, and get a report of what changed even when the layout zoomed, a section collapsed, or the viewport changed size. Every difference is named by the DOM locator behind it, not just drawn.

• Aligns before it compares. ORB feature matching and RANSAC recover the zoom, shift and stretch between the two images; a band alignment then maps sections that collapsed or expanded. Pixels are only compared where they correspond.
• Any two sizes. 320x320 against 1080x1350 works. The candidate is warped onto the baseline.
• Names the change. A Playwright capture records an element map (test id, id, role and name, or CSS path) next to each screenshot; regions are attributed to the smallest element that covers them.
• Reports that travel. A summary page with one card per pair, a detail page per pair with an embeddable <elastishot-viewer> (slider, flip, blink, overlay, diff), report.json and JUnit XML.
• Tracks a URL across deployments. snapshot / run / approve keep a baseline per target and viewport; the CLI exits non-zero when a deployment drifted.
• Checks a pull request without baselines. pr serves the base commit next to your working tree and compares the two in one run, on one machine with one browser, so fonts and rendering match and nothing is committed. In GitHub Actions it writes a table to the job summary.
• Modular. Isomorphic core (runs in Node and the browser through opencv.js WASM), Node-only capture and file layers behind subpath exports, plugin hooks and pluggable reporters.

Elastishot is a Node 20+ library and CLI written in TypeScript, MIT licensed, with no telemetry: the CLI contacts only the URLs you pass it. The install is about 16 MB, nearly all of it the opencv.js WebAssembly build; there is no native compile step.

Quick start

npm install -D elastishot
npm install -D playwright && npx playwright install chromium   # only needed for page URLs
npx elastishot compare https://staging.example.com/ https://example.com/ --full-page
npx elastishot compare before.png after.png
open .elastishot/runs/<run-id>/index.html
npx elastishot pr      # this branch against the one it left, both served here (needs a config)

The first command captures both pages, compares them and writes a run folder. The last line of the output is the path of the summary page. Exit code 1 means differences were found.

What's inside

elastishot/
├── bin/elastishot.js                 CLI entry (imports dist/cli/main.js)
├── src/
│   ├── index.ts                      Public entry: types, geometry, image helpers, compare(), comparePair()
│   ├── pipeline.ts                   comparePair(): engine + locators + verdict; Plugin and Reporter contracts
│   ├── core/                         Isomorphic: types, geometry, image utilities, options, thresholds, engine seam
│   ├── engine/                       opencv.js pipeline: preprocess, global align, structural align, diff, classify, verdict
│   │   ├── cv/                       Loader, Mat lifetime scope, typed subset of the opencv.js API
│   │   ├── pure/                     No-WASM algorithms: sequence alignment, colour distance, box merging, scoring
│   │   └── stages/                   One file per stage; every stage is replaceable
│   ├── locators/                     Regions x element maps -> changed locators
│   ├── capture/                      Playwright capture with the in-page element collector
│   ├── report/                       report.json schema, summary page, pair page, JUnit
│   ├── viewer/                       <elastishot-viewer> custom element (bundled by scripts/build-viewer.mjs)
│   ├── node/                         Files, URLs, snapshot folders, config, run folders, artifacts, the Node façade
│   └── cli/                          Argument parsing and the five commands
├── scripts/                          build-viewer, make-fixtures, check-layering, check-package, changelog-section, spike-opencv
├── test/                             Engine, capture, viewer and workflow tests; synthetic fixtures; fixture site v1/v2
├── acceptance/                       Gherkin features A-G with matching *.acceptance.test.js and trace.js
├── docs/                             ATDD.md, ELEMENT-MAP.md, EMBEDDING.md, ROADMAP.md, RELEASING.md
├── examples/ui-lab/                  A localhost page in ten builds with ground truth; scores every run
├── site/                             The landing page builder (site/dist is generated)
└── elastishot.config.example.js      Named targets and viewports for the run workflow

This is the beginning of the README. Read the rest at the original. Read the full README ↗