Comparison

Pixel Eagle compares two sets of screenshots, matched by name. For each screenshot name it reports whether it is unchanged, changed (a visual diff), new, or missing. There are two ways to compare: against a project's golden record (the simple case), or freely between any two runs (the advanced case).

Simple: compare against a golden record

A golden record is a mutable, approved baseline of screenshots. There is exactly one per project. New runs are compared against it to detect regressions, and you grow the baseline over time by approving changes. This is the recommended workflow for most projects — you don't have to track which run to compare against.

1. Set a run as the golden record

Once you have a run you're happy with, mark it as the project's golden record. This fails if a golden record already exists — there is only one per project.

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

2. Send a new run, then compare it

Create a new run and upload its screenshots as usual (see the API Reference). Then compare that run against the golden record. The first call triggers the diff computation; poll the read-only endpoint until every diff is complete.

# Trigger the comparison of a new run against the golden record
curl https://pixel-eagle.com/runs/$new_run_id/compare/golden \
  -X POST --oauth2-bearer $token

# Poll for the results until every diff is done
curl https://pixel-eagle.com/runs/$new_run_id/compare/golden \
  --oauth2-bearer $token

To skip the separate compare step entirely, create the run with compare_with_golden set to true. Each screenshot is then compared against the golden record as it is uploaded, so the results are ready as soon as the run finishes; just poll the read-only endpoint above.

# Create a run that auto-compares with the golden record as screenshots arrive
curl https://pixel-eagle.com/runs \
  --json '{"compare_with_golden": true, "branch": "main"}' \
  --oauth2-bearer $token

3. Approve changes to evolve the baseline

When a change is intentional, approve it into the golden record so future runs compare against the updated baseline. You can do this straight from the web UI: open a run's comparison against the golden record and use the Approve panel to accept all changes, pick specific screenshots, or remove ones missing from the run.

The same is available over the API. Approving with no body accepts all changed and new screenshots; you can also approve a subset or remove screenshots missing from the run (see the API Reference).

# 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

Keep the baseline up to date automatically

For a branch that is always considered correct (typically your main branch), you can let Pixel Eagle approve its runs automatically. In Project Settings → Project, set a golden record auto-update metadata filter such as branch = main. Whenever a run whose metadata matches every pair in the filter uploads, each of its screenshots is folded into the golden record as it arrives, creating the record on the first matching run and evolving it on every one after, with no manual approval step.

Advanced: free comparison between runs

You can also compare any two runs directly, without a golden record. This is useful for one-off comparisons, comparing across environments, or building your own baseline logic on top of run metadata.

Compare two runs by ID

Compare a run against another run you choose explicitly. Screenshots are matched by name.

# API
curl https://pixel-eagle.com/runs/$run_id_a/compare/$run_id_b \
  -X POST --oauth2-bearer $token

# CLI
pixeleagle compare-run $run_id_a --with-run $run_id_b

Auto comparison by metadata

Instead of specifying a run ID to compare against, you can let Pixel Eagle automatically select the best matching run based on metadata filters. This is especially useful in CI where you want to compare against the latest run on a base branch.

Exact match

Filter for the latest run with a specific metadata value:

# API
curl https://pixel-eagle.com/runs/$run_id/compare/auto \
  --json '{"branch": "main"}' --oauth2-bearer $token

# CLI
pixeleagle compare-run $run_id --filter branch:main

Same value match

Find a run that has the same value for a metadata field as the current run. Use the special <same> marker in the API, or --same in the CLI:

# API
curl https://pixel-eagle.com/runs/$run_id/compare/auto \
  --json '{"platform": "<same>"}' --oauth2-bearer $token

# CLI
pixeleagle compare-run $run_id --same platform

Combining filters

You can combine multiple filters to narrow down the matching run. For example, find the latest run on the "main" branch with the same platform:

# API
curl https://pixel-eagle.com/runs/$run_id/compare/auto \
  --json '{"branch": "main", "platform": "<same>"}' --oauth2-bearer $token

# CLI
pixeleagle compare-run $run_id --filter branch:main --same platform