A screenshot without a baseline only warned, so with no baseline committed every screen was "new" and the CI step could not fail, and a screen added after the first baselines could stay ungated for good. Now the baseline folder is armed as soon as it holds a PNG: from then on a screen without its own baseline fails (Verdict.Unbased, an error annotation). Before the first baselines the run says plainly, in its warning and in bold in the job summary, that it compared nothing and that no visual change can fail it. The baselines README explains why the existing ci-screenshots pictures cannot serve (captured before the clock was fixed: times and dates follow the capture moment) and how the first set is accepted from the first green windows-latest run of the reproducible capture. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_012iLMBNwBE2GnphAsu4cjaC
53 lines
2.9 KiB
Markdown
53 lines
2.9 KiB
Markdown
# Screenshot baselines
|
|
|
|
The approved look of every screen, one PNG per `--capture` screenshot (`<screen>-<theme>.png`, as `Titano.exe`,
|
|
`Titano.Uploader.exe` and `Titano.Setup.exe --capture <dir>` write them). CI compares each new screenshot with the
|
|
file of the same name here (BRIEF §20.2, visual regression with a pixel-diff tolerance):
|
|
|
|
```
|
|
dotnet run --project src/Titano.Tools -- screenshots diff out/screenshots --out out/screenshot-diff
|
|
```
|
|
|
|
- A pixel differs when one of its channels moves by more than `--tolerance` (default 8 of 255); a screen fails when
|
|
more than `--max-diff` of its pixels differ (default 0.0005, that is 0.05 %), when its size changed, or when a
|
|
baseline here has no screenshot any more.
|
|
- A screenshot without a baseline fails as soon as this folder holds any PNG: a pull request that adds a screen adds its
|
|
baselines too.
|
|
- While this folder holds no PNG nothing is compared: the step passes, with a warning and a bold line in the job summary
|
|
saying that no visual change can fail it.
|
|
- `out/screenshot-diff` gets `<screen>-diff.png` for every screen with differing pixels (the baseline faded to grey, the
|
|
differences magenta) and `summary.md`; CI uploads them as the `screenshot-diff` artifact and adds the summary to the
|
|
job page.
|
|
|
|
## The pictures are reproducible
|
|
|
|
The capture runs on sample data whose clock stands at `SampleData.Now` (2026-10-02 10:18 UTC), in English with English
|
|
formats and with animations off, so the same code draws the same pixels on any day. Two things still come from the
|
|
machine:
|
|
|
|
- the time zone: times are shown in local time, and the baselines are made on the CI runner (`windows-latest`, UTC);
|
|
- a few measured values: the server's response time and the time and duration of the last sync comparison. They change
|
|
a few dozen pixels, well inside the allowed fraction.
|
|
|
|
## Adding or updating baselines
|
|
|
|
Take them from CI, never from a local run (fonts, scaling and the time zone differ). Every same-repository pull request
|
|
pushes its screenshots to the `ci-screenshots` branch (one commit, the PNGs at its root). After checking them:
|
|
|
|
```
|
|
git fetch origin ci-screenshots
|
|
git worktree add ../ci-screenshots origin/ci-screenshots
|
|
dotnet run --project src/Titano.Tools -- screenshots accept ../ci-screenshots
|
|
git worktree remove ../ci-screenshots
|
|
```
|
|
|
|
`screenshots accept <dir>` copies every PNG of `<dir>` here. Commit only the screens whose change is intended, and delete
|
|
the baseline of a screen that no longer exists.
|
|
|
|
## The first baselines
|
|
|
|
None is committed yet. Screenshots captured before the capture was made reproducible cannot serve: their times and
|
|
dates follow the moment they were taken (a job finished at "12:18 AM", sample sequences dated from that day). The first
|
|
baselines are accepted, all at once, from the `ci-screenshots` commit of the first green `windows-latest` run whose
|
|
code captures at `SampleData.Now`; from that commit on, every screen is gated.
|