"Image Comparison in Apps: Perceptual Diff Basics"
"Your golden tests pass on your Mac and fail on Linux CI — and nothing in the UI actually changed. The culprit is font-rendering drift, and the fix is perceptual diff thinking: bundle the fonts, allow a small threshold, pin the runner."
Golden tests are the cheapest visual regression net you can own: every PR gets pixel-level proof that the UI didn't change. The benefit dies the first time you wire them into CI — your flutter golden test failing on CI while green on your Mac is the classic macOS→Linux font-rendering trap. Nothing in the app changed; the *pixels* changed, because fonts rasterize differently on each OS. Here is how to fix it, and the perceptual-diff concepts that explain why the fix works. What the CI failure looks like Your CI log says something like: Golden "goldens/profile_card.png": Pixel test failed, 2.31% diff detected. Expected: goldens/profile_card.png Actual: .../failures/profile_card_testImage.png Or worse, the "actual" image shows tofu boxes (□□□□) where text should be. The diff is tiny outlines around every text edge — antialiasing and font metrics differing between macOS CoreText and Linux FreeType. The UI is visually fine. The test is technically right and practically useless. Why pixels drift between macOS and Linux This is where perceptual diff basics matter. There are three ways to compare two images, and each answers a different question: Pixel-exact diff (what matchesGoldenFile does by default): are the bytes identical? Any antialiasing difference fails. Precise, but brittle across machines. Threshold diff : are the images different by *more than X%*? alchemist 0.14.0 added diffThreshold for exactly this — "comparison failures that depend on the image generation environment." A 0.5% allowance absorbs font antialiasing drift while still catching real layout changes. Perceptual hashing (pHash/dHash + hamming distance) : do these images *look* the same to a human? The image is reduced to a tiny fingerprint; the hamming distance between fingerprints measures visual…