Chromatic

Promptfree, for everyone, and the only version there is

Copy the prompt for Claude CodeCopy the prompt for CodexCopy the prompt for Cursor

Copy

Build me visual testing that replaces Chromatic — and know why this is ALMOST.

Rendering components and diffing screenshots is a weekend. **Making the diff mean something is not.** A rendering environment that produces identical pixels every run — same fonts, same animations stopped, same scrollbars, same GPU behaviour — is the entire product, and without it every run is full of false positives and the tool gets switched off in a fortnight. That, plus a review step a designer can use, is where the work is.

STACK
- Node 20+ with Fastify for the service
- SQLite through better-sqlite3, WAL mode
- Playwright with Chromium, **in a container**, for rendering
- odiff or pixelmatch for comparison, sharp for processing
- Caddy in front

THE DATA MODEL
- projects: id, name, repo_url, baseline_branch, config_json
- builds: id, project_id, commit_sha, branch, pull_number, parent_build_id, status, started_at, finished_at
- stories: id, build_id, story_id, title, viewport, theme, image_path, sha256, bytes, render_ms
- comparisons: id, build_id, story_id, baseline_story_id, diff_pixels, diff_ratio, diff_image_path, status — unchanged, changed, new, removed
- reviews: id, comparison_id, decision, actor, note, at — append-only
- baselines: project_id, branch, story_id, image_sha256 — what a story is expected to look like

DETERMINISM, WHICH IS THE PRODUCT
- Everything renders in one container image, pinned by digest. A font installed on a developer's machine and not in CI is the classic source of a phantom diff
- Fonts bundled in the image and loaded from disk; wait for the document's font loading to settle before capturing
- Animations and transitions disabled by an injected stylesheet, and any animation with a fixed frame set
- A fixed viewport, a fixed device scale factor, and a fixed colour scheme per capture — and capture each combination you care about as its own story rather than hoping
- Scrollbars hidden, caret hidden, and anything with a timestamp or random content stubbed at the story level
- Network requests intercepted: no external image, no analytics tag, no font from a CDN. A remote asset is a non-deterministic asset
- Then run the same commit twice and confirm zero diffs. Do that in CI as its own check — a suite that cannot reproduce itself cannot test anything

COMPARING
- Compare against the baseline for the target branch, not against the previous run on this branch
- A perceptual comparison with an anti-aliasing tolerance, not a raw pixel equality
- A threshold per story, because a component with a shadow will always differ by a few pixels
- Ignore regions by selector, for the parts that genuinely cannot be stabilised
- The diff image shows the before, the after, and the difference — all three, side by side and overlaid

THE REVIEW STEP
- One comment per pull request, edited in place, with the count of changed stories and a link
- A review page a designer can use: approve or reject each change, or accept all, with a note
- Accepting updates the baseline for that branch, and the update is recorded with who did it
- The build blocks the merge until every change is reviewed. That gate is what makes the tool worth having, and it is also what makes false positives intolerable — hence the determinism work above

OPERATIONS
- .env: DATABASE_PATH, STORAGE_PATH, BASE_URL, FORGE_TOKEN, SESSION_SECRET, RENDER_CONCURRENCY
- Migrations on boot, each once
- Images stored by content hash; unchanged stories store no new file
- Storage retention per project, and a disk watchdog
- Health endpoint that renders one fixture and compares it with itself

WHAT MATTERS MOST
Rendering the same commit twice with zero diffs. Achieve that before comparing anything, and treat any later flakiness as a bug of the highest severity.