Screenshots over time
Baselines and ignore regions
What a baseline is, how CirCI picks the one a build is compared with, and how to leave parts of a screenshot out of comparisons.
A baseline is the approved screenshot a new one is compared with. Every screenshot has a name, and a build's screenshot is compared with the baseline of the same name. This page covers how baselines are chosen, the Baselines page of a project, and ignore regions, the rectangles that are blanked out before comparing.
How a build gets its baseline
Section titled “How a build gets its baseline”For each build, CirCI picks one earlier build of the same project and the same build name to compare against:
- Only a finished build can be a baseline, and only one that is approved (by a person or automatically) or that matched its own approved baseline.
- CirCI walks the commit history back, nearest first: from where the branch started for a pull request, or from the previous commit on the default branch. The first commit that has an eligible build gives the baseline. If a commit was built several times (CI re-runs), the newest build wins.
- If no ancestor has one, the newest eligible build on the default branch is used. The build page then shows a warning that the history wasn't available.
- If there is nothing at all, the build has No baseline and every screenshot is new.
Within the build, screenshots are paired by name:
| Result | When |
|---|---|
| Added | The name has no baseline |
| Removed | The baseline has a name the build didn't upload |
| Unchanged | Byte-identical files, with no pixel comparison needed |
| Compared | Same name, different bytes: a pixel diff decides changed or unchanged, using the project's diff threshold. A change of size is always a change |
The default branch is a project setting (main unless changed). On it, approving a screenshot makes it the baseline that every other branch is compared with. With Approve default-branch builds automatically on, a default-branch build is approved without review once there is an approved baseline to compare with, so a project's first build is always reviewed. See Project settings and Reviewing a build.
A rejected screenshot never becomes a baseline.
The Baselines page
Section titled “The Baselines page”Open a project in the sidebar and choose Baselines. It lists the current baseline of every screenshot name, grouped by the part of the name before the first / ("checkout/cart.png" is in checkout; names without a slash are under Ungrouped). The header counts them ("12 on main") and has a find field. Until a build of the default branch finishes, the page says "No baselines yet".
Each row shows:
- a thumbnail and the name
- the build it comes from, and the build name when it isn't
default - when it was approved
- a chip with the number of ignored regions
- a flaky chip that says why ("Came back to an earlier image 4 times") and opens the item in Triage
Press j and k to move, and right-click a row for Open, Open build, Open in Triage (when flaky), Open in new tab, Copy link and Copy name. See Triage and flaky screenshots.
One baseline
Section titled “One baseline”Open a row to see the screenshot's page: the baseline image, which build it's from and who approved it, Open build, and History on main: the recent builds where this screenshot changed, each with its status, newest first. If the screenshot is flaky, it says why.
The page also holds the screenshot's ignore regions.
Ignore regions
Section titled “Ignore regions”An ignore region is a rectangle, in whole pixels measured from the top left, that is blanked out on both images before they are compared. Use it for a clock, a rotating banner, an ad or a cursor: something that changes without meaning anything.
- A region belongs to a screenshot name. It applies to every build of that screenshot, until it's removed.
- There's no pattern or per-branch setting.
- Insights shows how many diffs the regions kept unchanged. See Insights.
Who can change them
Section titled “Who can change them”Owners and admins add, move, edit and remove regions. Other members see them. A phone shows regions but doesn't edit them: draw them on a larger screen.
Add a region
Section titled “Add a region”-
Open the screenshot's baseline page, or open the screenshot in a build and choose Ignore regions under Dragging draws in the View options menu (⋯).
-
Drag a rectangle over the baseline image. It's saved at once, with a toast ("Ignore region added").
-
To place it precisely, use the keyboard tool (the crosshair button): arrow keys move, Shift + arrows resize, Enter confirms.
Drag a region's handles to move or resize it ("Ignore region saved"). In the list under the image, Edit opens fields for Left, Top, Width and Height in pixels, and Remove removes the rectangle after a confirmation: the area is compared again from the next build. Each region shows its size and position (300 x 40 at 120, 16) and who added it.
A region can also be added from a server shell with circi admin ignore add --org <slug> --project <project> --name <screenshot> --region x,y,width,height, with circi admin ignore list and circi admin ignore remove <id> beside it. See Admin CLI.
In project settings
Section titled “In project settings”Project settings › Ignore regions lists every screenshot that has regions, with a count. Choosing one opens its baseline page inside settings, where the regions are edited. Members of the project can read this page too. See Project settings.