Completeness and removals

A build can only tell you a snapshot disappeared if it knows it captured everything. That’s what capture complete means: the client finished the build and declared that its upload is the whole set. Builds and snapshots defines the term.

How a removal appears

When a build becomes capture complete, pixmoat looks for snapshots that have a baseline on the build’s branch or on the default branch but no screenshot in this build. Each one gets a Removed entry in the build, showing its last baseline image.

That’s correct when you deleted a test or a page on purpose. It’s wrong when the snapshot is missing for another reason, and pixmoat can’t tell the two apart.

Snapshots that go missing by accident

Every snapshot that has a baseline but wasn’t captured shows as Removed, whatever the reason. Common causes:

• A test failed before it reached pixmoat.snapshot(). The fixture still finishes the build as capture complete. Fix the test and run the full suite again before reviewing.
• Only part of the suite ran. --grep, test.only, a single test file, a single --project or a skipped test all leave snapshots out. Run the whole suite for any build you plan to review.
• The suite is sharded. The client can’t combine shards into one build, so a shard finishes its build without the other shards’ screenshots, and those show as Removed. Don’t shard the suite that captures screenshots.
• The snapshot’s identity changed. A new name, viewport, browser or theme makes a new snapshot. The old one shows as Removed and the new one as New. That’s expected: approve both if the rename was intentional.
• The capture uses the Playwright reporter (beta). The reporter uploads only the images attached to test results and marks the build capture complete even when uploads failed, so snapshots it didn’t upload show as Removed. Use the fixture instead.

A failed upload with the fixture doesn’t cause removals. finishBuild() then marks the build Failed instead of capture complete. Run the suite again once the upload problem is fixed.

Approving a removal

When you approve a Removed screenshot and the review is complete, pixmoat retires its baseline on the build’s branch:

• The baseline is deleted from that branch. Baseline History shows the version with a Retired badge.
• If the snapshot comes back in a later build, it’s New and needs a fresh approval.

So approving a false removal loses a valid baseline. You can recover by running the full suite again and approving the snapshot as New, but the comparison with the old image is gone. Before you approve a removal, confirm that the test or page was removed on purpose.

On a feature branch, approving a removal retires only that branch’s baseline. The default branch keeps its baseline until the merge request is merged and promoted. Until then, the next build on the feature branch falls back to the default branch’s baseline and shows the snapshot as Removed again. That’s expected.

Two places make removals easy to approve without noticing:

• Approve all includes Removed screenshots. Its confirmation dialog shows how many removals it will approve. Check that number before you select Confirm approve.
• The Finish Review dialog shows Baselines to retire. If that number isn’t what you expect, select Cancel and change the decisions.

To keep a baseline, Reject the removal. Use Reject removals to reject all pending removals with an optional shared comment. Already decided screenshots are skipped. If a request fails, saved decisions remain staged; retry to reject the remaining removals. In blocking mode, the build becomes Rejected when you finish. In advisory mode, rejecting a removal keeps its baseline without rejecting the build. Then restore the missing test or page and run the suite again.

A build containing only removed screenshots still shows Approve all, Reject removals, and Finish review. In blocking mode, Finish appears after every removal has a decision. In advisory mode, you can finish without deciding removals. The confirmation shows any approved baselines that will be retired.

Removal gating mode

Settings → Removals → Removal gating mode decides whether removals must be decided before a review can finish. Set it there: the removal_gating key in .pixmoat.yaml is stored with the build, but pixmoat uses the project’s setting.

In either mode, only a removal that someone approved retires a baseline.