feat: compare images with pixelmatch 8

.changeset/pixelmatch-8.md

@@ -0,0 +1,10 @@
+---
+"@wdio/image-comparison-core": major
+"@wdio/visual-service": major
+---
+
+feat: compare images with pixelmatch 8 (OKLab/HyAB color distance)
+
+The comparison engine is now pixelmatch 8. It measures color differences in the OKLab color space with the HyAB distance instead of YIQ, which is closer to how people see colors: fewer false positives and fewer missed changes.
+
+The threshold scale did not change (`0` to `1`, where `1` is black vs white), so the `ignore*` presets keep their values. But **mismatch percentages can differ a little** from v10 for the same images. On real screenshots the number of different pixels changed by about −3 % to +3 % (for a 1-pixel shift of a full page with `ignoreAntialiasing`: 0.002 % → 0.003 %). If a check depends on an exact mismatch percentage or a tight tolerance, check it again after the upgrade.

packages/image-comparison-core/README.md

@@ -21,7 +21,7 @@ v10 uses [pixelmatch](https://github.com/mapbox/pixelmatch) instead of resemble.
 |---|---|---|
 | AA forgiveness | opt-in (`ignoreAntialiasing: true`) | on by default (`ignoreAntialiasing: true`) |
 | Strict comparison | default | set `ignoreAntialiasing: false` |
-| Engine | resemble RGB/brightness | pixelmatch YIQ perceptual distance |
+| Engine | resemble RGB/brightness | pixelmatch perceptual distance (OKLab/HyAB since v11, YIQ in v10) |
 
 No config change is needed if you rely on forgiving comparison behaviour.
 
@@ -36,7 +36,7 @@ No config change is needed if you rely on forgiving comparison behaviour.
 | `ignoreColors` | resemble luma grayscale | ~16/255 (`0.063`) | no |
 | `ignoreNothing` | - | `0` | no |
 
-Thresholds are calibrated to resemble outcomes; the underlying algorithm is YIQ perceptual distance, not resemble's RGB math.
+Thresholds are calibrated to resemble outcomes; the underlying algorithm is pixelmatch's perceptual color distance, not resemble's RGB math. Since v11 this is pixelmatch 8 (OKLab color space and HyAB distance; v10 used YIQ). pixelmatch 8 keeps the threshold scale (`0` to `1`, where `1` is black vs white), so the thresholds above stay the same, but mismatch numbers can differ a little from v10.
 
 ### Last-wins semantics
 

packages/image-comparison-core/package.json

@@ -37,10 +37,10 @@
     "watch:tsc": "pnpm run build:tsc -w"
   },
   "dependencies": {
-    "fast-png": "^8.0.0",
-    "pixelmatch": "^7.2.0",
     "@wdio/logger": "^10.0.0",
-    "@wdio/types": "^10.0.0"
+    "@wdio/types": "^10.0.0",
+    "fast-png": "^8.0.0",
+    "pixelmatch": "^8.0.0"
   },
   "devDependencies": {
     "webdriverio": "^10.0.0"

packages/image-comparison-core/src/base.interfaces.ts

@@ -114,7 +114,7 @@ export interface BaseImageCompareOptions {
      */
     ignoreColors?: boolean;
     /**
-     * Use a relaxed RGB tolerance (~16/255 per channel in YIQ space).
+     * Use a relaxed color tolerance (pixelmatch threshold `0.063`).
      * Preset: strict threshold, AA not forgiven (does not inherit default AA forgiveness).
      * @default false
      */

packages/image-comparison-core/src/helpers/options.interfaces.ts

@@ -184,7 +184,7 @@ export interface ClassOptions {
     ignoreColors?: boolean;
 
     /**
-     * Use a relaxed RGB tolerance (~16/255 per channel in YIQ space).
+     * Use a relaxed color tolerance (pixelmatch threshold `0.063`).
      * Preset: strict threshold, AA not forgiven (does not inherit default AA forgiveness).
      */
     ignoreLess?: boolean;
@@ -496,7 +496,7 @@ export interface IgnorePresetCompareOptions {
     ignoreColors: boolean;
 
     /**
-     * Use a relaxed RGB tolerance (~16/255 per channel in YIQ space).
+     * Use a relaxed color tolerance (pixelmatch threshold `0.063`).
      * Preset: strict threshold, AA not forgiven (does not inherit default AA forgiveness).
      */
     ignoreLess: boolean;

packages/image-comparison-core/src/helpers/options.ts

@@ -504,7 +504,8 @@ const COMPARE_PRESET_SETTINGS: Record<ComparisonIgnoreOption, { threshold: numbe
     nothing: { threshold: 0, includeAA: true },
     less: { threshold: 0.063, includeAA: true },
     antialiasing: {
-        // Resemble's ignoreAntialiasing uses 32/255 per-channel tolerance (~0.13 YIQ).
+        // Calibrated to resemble's ignoreAntialiasing (32/255 per channel). The scale is pixelmatch's:
+        // 0 to 1, where 1 is black vs white (pixelmatch 8 kept it when it moved from YIQ to OKLab/HyAB).
         threshold: 0.13,
         includeAA: false,
     },
@@ -538,7 +539,8 @@ export function resolveComparePreset(ignoreList: ComparisonIgnoreOption[]): { th
         return COMPARE_PRESET_SETTINGS[activePreset]
     }
 
-    // Default strict tolerance: 16/255 per channel (~6.3% of max YIQ distance).
+    // Default strict tolerance, calibrated to resemble's 16/255 per channel. The scale is pixelmatch's:
+    // 0 to 1, where 1 is black vs white.
     return { threshold: 0.063, includeAA: true }
 }
 

packages/image-comparison-core/src/pixelmatch/compareImages.checkerboard.test.ts

@@ -0,0 +1,31 @@
+import { describe, it, expect } from 'vitest'
+import compareImages from './compareImages.js'
+import { DEFAULT_PIXELMATCH_OPTIONS } from '../helpers/constants.js'
+import { createCanvas, encodeImage } from '../utils/imageUtils.js'
+
+// Runs the real pixelmatch (no mock): `checkerboard` only changes how pixelmatch blends semi-transparent pixels
+const SIZE = 16
+const transparent = encodeImage(createCanvas(SIZE, SIZE, 0, 0, 0, 0))
+const opaqueWhite = encodeImage(createCanvas(SIZE, SIZE, 255, 255, 255, 255))
+
+function compareWithCheckerboard(checkerboard: boolean) {
+    return compareImages(transparent, opaqueWhite, {
+        pixelmatch: { ...DEFAULT_PIXELMATCH_OPTIONS, threshold: 0.063, includeAA: true, checkerboard },
+    })
+}
+
+describe('compareImages checkerboard', () => {
+    it('blends transparent pixels with white when checkerboard is false, so they match white', async () => {
+        const result = await compareWithCheckerboard(false)
+
+        expect(result.rawMisMatchPercentage).toBe(0)
+        expect(result.diffPixels).toHaveLength(0)
+    })
+
+    it('blends transparent pixels with a checker pattern when checkerboard is true, so they differ from white', async () => {
+        const result = await compareWithCheckerboard(true)
+
+        expect(result.rawMisMatchPercentage).toBeGreaterThan(0)
+        expect(result.diffPixels.length).toBeGreaterThan(0)
+    })
+})