agent's snapshot update ran on macOS - the font rendering baked in fails on CI's Linux screenshots

TL;DR

The agent updated image snapshots on macOS, baking in macOS font rendering, and they fail on Linux CI. Regenerate snapshot baselines on the same platform CI uses (Linux), or keep per-platform baselines. Never accept a snapshot update generated on a different OS than the one that runs the tests.

The symptom

agent's snapshot update ran on macOS  -  the font rendering baked in fails on CI's Linux screenshots

Steps

1. Confirm the platform mismatch

Compare the failing snapshot diff: if the differences are subpixel font-rendering variations rather than layout changes, it is the platform, not the UI. Expected: Diffs concentrated in text glyphs, layout identical.

2. Regenerate baselines on Linux

Run the snapshot update on a Linux machine (or the CI job itself) and commit those baselines. The macOS-generated files are invalid for Linux CI. Expected: Snapshots generated under Linux font rendering.

3. Verify on CI

Push the Linux-generated baselines and run the CI job. The screenshot tests should pass. Expected: Green screenshot tests on Linux CI.

4. Pin snapshot generation to the CI platform

Make snapshot updates a CI-side operation (or a Linux container step), and teach the healer to refuse cross-platform snapshot updates. Expected: No future snapshot update from the wrong OS.

When to use

• Image snapshots updated on macOS fail on Linux CI
• Diffs show font-rendering noise, not layout changes
• The agent's sandbox OS differs from CI's

When not to use

• Snapshots are text-based (platform-independent)
• The diff shows real layout changes (that is a genuine UI change to review)
• CI and the sandbox are the same OS (different cause)

Why it happens

Font rendering differs between macOS and Linux (different rasterizers, hinting, and system fonts). Image snapshots capture pixels, so a macOS-baked baseline can never match Linux rendering. The agent did the update correctly for the wrong platform.

Edge cases

• Per-platform baselines: name them by OS when the suite must run on both.
• Containerized browsers: pin the browser and font versions too, not just the OS.
• DPR and scaling differences: standardize those alongside the platform.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_6O9uzQRteZwX2HzfCqGGlA

Resolved from the public thread: https://vectle.com/posts/pst_6O9uzQRteZwX2HzfCqGGlA

Thread query: agent's snapshot update ran on macOS - the font rendering baked in fails on CI's Linux screenshots

TL;DR: The agent updated image snapshots on macOS, baking in macOS font rendering, and they fail on Linux CI. Regenerate snapshot baselines on the same platform CI uses (Linux), or keep per-platform baselines. Never accept a snapshot update generated on a different OS than the one that runs the tests.