Builds and snapshots
This page defines four terms that the rest of the docs use in exactly this sense: build, snapshot, capture complete and review complete. The fifth core term, baseline, is defined in Baselines and branches.
Snapshot
A snapshot is one screenshot that pixmoat tracks over time. It’s identified by four things:
- the name you pass to
pixmoat.snapshot(page, "<name>") - the viewport, for example
1280x720 - the browser, for example
chromium - the device pixel ratio (1, 2 or 3)
A light and a dark capture of the same page are two snapshots, because the Playwright client adds the theme to the browser label (chromium___dark). Capture options such as fullPage don’t change which snapshot a capture belongs to.
One pixmoat.snapshot() call can produce several snapshots. For example, viewports: ["1280x720", "375x812"] produces one snapshot per viewport. The app calls each snapshot’s image a screenshot.
Renaming a snapshot, or changing its viewport or browser, creates a new snapshot with no history. The old one stops being captured and can show up as Removed (see Completeness and removals).
Build
A build is one run of your test suite for one commit on one branch. It collects the screenshots from that run and compares each one with the snapshot’s baseline.
With the Playwright fixture, startBuild() in global-setup.ts creates the build and finishBuild() in global-teardown.ts finishes it. Every Playwright worker uploads into the same build. See Connect Playwright for the setup.
Each screenshot in a build gets one of these tags in the review page:
| Tag | Meaning |
|---|---|
| New | The snapshot has no baseline yet. |
| Changed | The screenshot differs from its baseline by more than the tolerance. |
| Not changed | The screenshot matches its baseline. The filter chips call these Unchanged. |
| Removed | The snapshot has a baseline but wasn’t captured in this build. See Completeness and removals. |
| Flaky or Quarantined | The snapshot is known to vary between runs. It’s approved automatically when the review finishes. |
The builds list shows a status for each build:
| Status | Meaning |
|---|---|
| Running | Screenshots are still uploading. |
| Uploaded | The client finished the build and it has something to review. |
| In Review | Someone has started deciding screenshots. |
| No changes | Every screenshot matched its baseline, so pixmoat finished the build without a review. |
| Approved | The review is complete and nothing was rejected. |
| Rejected | The review is complete and at least one screenshot was rejected. |
| Failed | The build reported failed uploads, so pixmoat didn’t treat it as complete. |
| Superseded | A newer build on the same branch replaced this one before it was reviewed. |
Capture complete
A build is capture complete when the client has finished it and told pixmoat that it uploaded every snapshot the test run produced. From that point pixmoat knows which snapshots the build is missing.
The fixture’s finishBuild() marks the build capture complete unless an upload failed. When an upload fails, it marks the build as failed instead, and the build shows Failed. Run the suite again once the cause is fixed.
When a capture complete build has no screenshot for a snapshot that has a baseline, pixmoat adds a Removed entry for it. Completeness and removals explains when that happens by accident and what approving a removal does.
finishBuild() never fails your test run, whatever the build contains. To make CI wait for a review, add a gate step. The CI gate section shows one.
Review complete
A build is review complete when someone selects Finish review and then Confirm. Until then, Approve and Reject decisions are staged: you can change them, and no baseline changes.
Finish review is only possible when:
- every New and Changed screenshot has a decision
- every Removed screenshot has a decision, if the project’s removal gating mode is Blocking
- the project’s approval policy is met, if you approve anything. See Approval policy.
When the review is complete:
- Every approved screenshot becomes the baseline for the build’s branch. This happens even when another screenshot in the same build was rejected.
- Every approved removal retires its baseline on that branch.
- The build shows Approved if nothing was rejected, otherwise Rejected.
- If the project has a Git provider connected, pixmoat updates the commit status. See GitLab CI.
A build that shows No changes is review complete as soon as capture is complete, because it has nothing to review.
A CI job that already failed doesn’t rerun itself. After the review is complete, retry the gate job to turn the pipeline green. Your first build walks through this.