Skip to content

feat: compare images with pixelmatch 8 - #42

Merged
kurkle merged 1 commit into
chartjs:masterfrom
kurkle:feat/pixelmatch-8
Nov 19, 2026
Merged

kurkle merged 1 commit into
chartjs:masterfrom
kurkle:feat/pixelmatch-8

Conversation

@kurkle

@kurkle kurkle commented Nov 19, 2026

Copy link
Copy Markdown
Member

Moves the image comparison to pixelmatch 8.0.0 (^7.2.0 -> ^8.0.0). The lockfile diff is the pixelmatch entry only.

pixelmatch 8.0.0 release notes

What changes for consumers

pixelmatch 8 replaces its colour-difference metric (YIQ) with OKLab + HyAB. The API and the scale of threshold are unchanged, but the number of pixels counted as different changes. toEqualImageData and createFixtures pass threshold and tolerance straight through, so the same fixtures can report different counts under the same limits.

  • A render that is pixel-identical to its reference still counts 0 under both metrics.
  • Fixtures whose count was close to tolerance can move either way, mostly around anti-aliased edges and semi-transparent pixels.
  • If a fixture starts failing after upgrading: check the logged actual/expected/diff preview, and if the render is correct either regenerate the reference image (saveFixtureImage / fixtures:update) or adjust that fixture's threshold / tolerance to the new measurement. Do not raise a global default.
  • This is why the PR title is feat: (minor) and not fix(deps):: it changes numbers that consumers' tests assert on. Squash-merging with this title makes semantic-release cut a minor release.

Not changed: the matcher still blends transparency against plain white (checkerboard: false) unless a fixture passes checkerboard: true; pixelmatch 7.2 and 8 both default it to true.

Measurements from this repo's own suite

npm test on this branch (lint, typecheck, type tests, 9 unit tests, browser suite in Chromium and Firefox), before and after the bump:

pixelmatch 7.2.0 pixelmatch 8.0.0
unit 9 passed 9 passed
browser (4 files) 24 passed, 2 skipped 24 passed, 2 skipped

The 2 skips are the "unsupported browser features" spec, which skips by design where OffscreenCanvas is missing. I logged the count toEqualImageData computes for each fixture (limit = 0.1% of 65536 px = 65 px, threshold 0.1):

fixture browser 7.2.0 8.0.0
basic/bar chromium 0 0
basic/bar firefox 0 0
basic/line-sprited chromium 0 0
basic/line-sprited firefox 0 0

All counts are 0 because the renders are pixel-identical to the references, so the suite here does not exercise the metric and nothing in it needed regenerating or adjusting. To show that the metrics do differ, I compared bar.png with line-sprited.png (two unrelated images, only a probe) with checkerboard: false:

threshold 7.2.0 8.0.0
0 32074 32074
0.05 32062 32061
0.1 30734 30741
0.2 30660 30639

and with checkerboard: true:

threshold 7.2.0 8.0.0
0 32573 32821
0.05 31725 32635
0.1 31025 31461
0.2 30296 31072

pixelmatch 8.0.0 replaces its colour-difference metric (YIQ) with OKLab and
HyAB. The API and the scale of `threshold` are unchanged, but the number of
pixels counted as different is not, so `toEqualImageData` and the fixtures
built on it can report different counts under the same `threshold` and
`tolerance`. The shift is largest for anti-aliased edges and semi-transparent
pixels.

A reference image that matches pixel for pixel still counts 0 under both
metrics. A fixture that sat close to its `tolerance` may start failing, or
stop failing; re-render it and regenerate its reference image, or adjust that
fixture's `threshold` / `tolerance`.

The matcher still blends transparency against white unless a fixture passes
`checkerboard: true`.
@kurkle
kurkle merged commit 20a7bde into chartjs:master Nov 19, 2026
2 checks passed
@github-actions

Copy link
Copy Markdown

🎉 This PR is included in version 1.1.0 🎉

The release is available on:

Your semantic-release bot 📦🚀

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant