Golden Records: One Approved Baseline, Three Ways to Keep It Fresh

The hardest question in visual regression testing is "changed compared to what?"

Compare against the previous run and an accepted change keeps showing up as a diff until another run replaces it. Compare against a pinned run and someone has to remember to re-pin it after every intentional change. Both approaches make the baseline a moving part that your team has to manage by hand.

Golden records remove that moving part. A golden record is a mutable, approved baseline of screenshots for a project, exactly one per project. New runs are compared against it to detect regressions, and it evolves as your team approves changes (never behind your back, unless you explicitly ask for that).

Runs Are Immutable, the Baseline Isn't

In PixelEagle, a run is an immutable snapshot: the screenshots your CI uploaded for one commit, on one platform, at one moment. That immutability is what makes history trustworthy: you can always go back and see exactly what a build looked like.

But a baseline has a different job. It represents "what the product is supposed to look like right now," and that changes every time a redesign lands or a new page ships. So the golden record is deliberately mutable: it starts as a copy of a run you're happy with, and grows one approval at a time.

Getting started takes one call, or one click in the project view:

# Set a run you are happy with as the project's golden record
curl https://pixel-eagle.com/runs/$run_id/golden \
  -X POST --oauth2-bearer $token

From then on, every new run can be checked against it, and each screenshot is reported as unchanged, changed, new, or missing.

Three Ways Screenshots Enter the Golden Record

These are orthogonal, and you can combine them.

1. Manual Approval: the Default Workflow

A new run comes in, the comparison flags three changed screenshots. You open the comparison view, look at the diffs, and decide: two are an intentional redesign, one is a regression.

The Approve panel lets you accept all changes, pick a subset, or remove screenshots that are missing from the run. The approved screenshots become the new baseline; the regression stays flagged until it's fixed. The same operation is available over the API for scripted workflows:

# Approve all of the new run's changes into the golden record
curl https://pixel-eagle.com/runs/$new_run_id/golden/approve \
  -X POST --oauth2-bearer $token

2. Compare on Upload: Results Ready When the Run Finishes

Normally a comparison is something you trigger after uploading. If you create the run with compare_with_golden, each screenshot is compared against the golden record as it arrives:

curl https://pixel-eagle.com/runs \
  --json '{"compare_with_golden": true, "branch": "my-feature"}' \
  --oauth2-bearer $token

By the time your CI job finishes uploading, the comparison is already done: no separate compare step, no polling delay. This never modifies the golden record; it only reads from it.

3. Auto-Update from a Trusted Branch: No Approval Step at All

Some branches are the baseline by definition. If a run came from main, its screenshots are what the product looks like now.

For that case, set a golden record auto-update filter in the project settings: a metadata filter such as branch = main. Whenever a run whose metadata matches uploads, each of its screenshots is folded into the golden record as it arrives. The record is even created on the first matching run, so a brand-new project bootstraps its own baseline from its first main build.

Combined with the previous two, this gives a complete PR workflow with zero baseline management:

• Pushes to main auto-update the golden record, so the baseline always matches what's shipped
• PR runs are created with compare_with_golden, so every pull request gets compared against the approved baseline automatically
• Reviewers only look at flagged diffs, and approvals only happen where a human decision is actually needed

The Details That Make It Cheap

Two implementation choices affect your bill and your wait time.

Comparisons are content-addressable: diff results are keyed by the screenshot contents and comparison settings, not by run IDs. If a screenshot pair was already compared (in any run-vs-run or run-vs-golden comparison), the cached result is reused. Identical screenshots are matched by hash, which is free on every plan.

The golden record also reuses everything you already know. It appears in the same screenshot and comparison views as any run (its virtual run ID is literally golden), so there is no new UI to learn: project/<id>/run/golden shows the baseline, and any run can be compared to it like any other.

Golden records are available on every plan, including the free tier.

When You Still Want Run-vs-Run

The golden record is the simple case, and the right default for most projects. Free comparison between any two runs is still there for the advanced cases: comparing two feature branches against each other, checking platform parity by comparing a Linux run with a macOS run (--same platform), or auditing history. See the comparison docs for both workflows.

Key Takeaways

• A golden record is a mutable, approved baseline; exactly one per project, so "compared to what?" always has an answer
• Manual approval keeps humans in control: accept everything, a subset, or prune missing screens
• compare_with_golden compares screenshots as they upload, so results are ready when the run finishes
• An auto-update filter (e.g. branch = main) keeps the baseline in sync with your trusted branch with no approval step
• Diffs are cached by content, so repeated comparisons of the same screenshots cost nothing extra