@wdio/image-comparison-core 1.2.4 → 2.0.0

package/dist/methods/rectangles.js

@@ -1,4 +1,5 @@
-import { Jimp } from 'jimp';
+import { readFileSync } from 'node:fs';
+import { decodeImage } from '../utils/imageUtils.js';
 import { ANDROID_OFFSETS, IOS_OFFSETS } from '../helpers/constants.js';
 import { calculateDprData, getBase64ScreenshotSize, isObject } from '../helpers/utils.js';
 import { getElementPositionAndroid, getElementPositionDesktop, getElementWebviewPosition } from './elementPosition.js';
@@ -374,10 +375,14 @@ export async function determineWebElementIgnoreRegions(options, ignores) {
     // to reduce 1px boundary differences on high-DPR / BiDi.
     let result = [...regions, ...regionsFromElements]
         .map((region) => {
+        // Floor position (x/y) to include the start pixel, ceil size (width/height)
+        // to include the end pixel. Flooring size can lose 1px when CSS * DPR has
+        // a fractional part, causing the last row or column of an element to fall
+        // outside the ignored region.
         let x = Math.floor(region.x * devicePixelRatio);
         let y = Math.floor(region.y * devicePixelRatio);
-        let width = Math.floor(region.width * devicePixelRatio);
-        let height = Math.floor(region.height * devicePixelRatio);
+        let width = Math.ceil(region.width * devicePixelRatio);
+        let height = Math.ceil(region.height * devicePixelRatio);
         if (padding > 0) {
             x = Math.max(0, x - padding);
             y = Math.max(0, y - padding);
@@ -498,10 +503,8 @@ export async function prepareIgnoreRectangles(options) {
             }
         }
         if (webStatusAddressToolBarOptions.length > 0) {
-            // There's an issue with the resemble lib when all the rectangles are 0,0,0,0, it will see this as a full
-            // blockout of the image and the comparison will succeed with 0 % difference.
-            // Additionally, rectangles with either width or height equal to 0 will result in an entire axis being ignored
-            // due to how resemble handles falsy values. Filter those out up front.
+            // Filter out zero-dimension rectangles: a 0,0,0,0 rect would block out the entire image,
+            // and rects with width or height of 0 produce undefined axis behaviour. Remove them upfront.
             webStatusAddressToolBarOptions = webStatusAddressToolBarOptions
                 .filter((rectangle) => !(rectangle.x === 0 && rectangle.y === 0 && rectangle.width === 0 && rectangle.height === 0))
                 .filter((rectangle) => rectangle.width > 0 && rectangle.height > 0);
@@ -512,8 +515,8 @@ export async function prepareIgnoreRectangles(options) {
             try {
                 // For iOS: block out home bar
                 if (!isAndroid && deviceRectangles.homeBar.height > 0) {
-                    const image = await Jimp.read(actualFilePath);
-                    const imageHeightDevicePixels = image.bitmap.height;
+                    const image = decodeImage(readFileSync(actualFilePath));
+                    const imageHeightDevicePixels = image.height;
                     const imageHeightCssPixels = imageHeightDevicePixels / devicePixelRatio;
                     // Adjust home bar X position relative to the viewport (full page image only contains viewport)
                     const viewportXCssPixels = deviceRectangles.viewport.x;

package/dist/pixelmatch/compare.interfaces.d.ts

@@ -0,0 +1,43 @@
+import type { BaseBoundingBox, BaseCoordinates } from '../base.interfaces.js';
+import type { RawImage } from '../utils/imageUtils.js';
+export interface CompareData {
+    /** The mismatch percentage like 0.12345567 */
+    rawMisMatchPercentage: number;
+    /** The mismatch percentage like 0.12 */
+    misMatchPercentage: number;
+    /** Raw RGBA pixel data of the diff composited on the actual screenshot, with dimensions */
+    getRawPixels: () => RawImage;
+    /** The diff image encoded as a PNG buffer */
+    getBuffer: () => Promise<Buffer>;
+    /** The bounds of the diff area */
+    diffBounds: BaseBoundingBox;
+    /** The analysis time in milliseconds */
+    analysisTime: number;
+    /** The diff pixels location(s) and color(s) */
+    diffPixels: BaseCoordinates[];
+}
+type Box = {
+    /** Left boundary of the box */
+    left: number;
+    /** Top boundary of the box */
+    top: number;
+    /** Right boundary of the box */
+    right: number;
+    /** Bottom boundary of the box */
+    bottom: number;
+};
+type OutputSettings = {
+    /** Box area to ignore during comparison */
+    ignoredBoxes?: Box[] | undefined;
+};
+export type ComparisonIgnoreOption = 'nothing' | 'less' | 'antialiasing' | 'colors' | 'alpha';
+export interface ComparisonOptions {
+    /** Output settings for the comparison */
+    output?: OutputSettings | undefined;
+    /** Whether to scale images to the same size before comparison */
+    scaleToSameSize?: boolean | undefined;
+    /** What aspects to ignore during comparison */
+    ignore?: ComparisonIgnoreOption | ComparisonIgnoreOption[] | undefined;
+}
+export {};
+//# sourceMappingURL=compare.interfaces.d.ts.map

package/dist/pixelmatch/compare.interfaces.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compare.interfaces.d.ts","sourceRoot":"","sources":["../../src/pixelmatch/compare.interfaces.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAA;AAC7E,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAA;AAEtD,MAAM,WAAW,WAAW;IACxB,8CAA8C;IAC9C,qBAAqB,EAAE,MAAM,CAAC;IAC9B,wCAAwC;IACxC,kBAAkB,EAAE,MAAM,CAAC;IAC3B,2FAA2F;IAC3F,YAAY,EAAE,MAAM,QAAQ,CAAC;IAC7B,6CAA6C;IAC7C,SAAS,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;IACjC,kCAAkC;IAClC,UAAU,EAAE,eAAe,CAAC;IAC5B,wCAAwC;IACxC,YAAY,EAAE,MAAM,CAAC;IACrB,+CAA+C;IAC/C,UAAU,EAAE,eAAe,EAAE,CAAC;CACjC;AAED,KAAK,GAAG,GAAG;IACP,+BAA+B;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,8BAA8B;IAC9B,GAAG,EAAE,MAAM,CAAC;IACZ,gCAAgC;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,iCAAiC;IACjC,MAAM,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF,KAAK,cAAc,GAAG;IAClB,2CAA2C;IAC3C,YAAY,CAAC,EAAE,GAAG,EAAE,GAAG,SAAS,CAAC;CACpC,CAAC;AAEF,MAAM,MAAM,sBAAsB,GAAG,SAAS,GAAG,MAAM,GAAG,cAAc,GAAG,QAAQ,GAAG,OAAO,CAAC;AAE9F,MAAM,WAAW,iBAAiB;IAC9B,yCAAyC;IACzC,MAAM,CAAC,EAAE,cAAc,GAAG,SAAS,CAAC;IACpC,iEAAiE;IACjE,eAAe,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACtC,+CAA+C;IAC/C,MAAM,CAAC,EAAE,sBAAsB,GAAG,sBAAsB,EAAE,GAAG,SAAS,CAAC;CAC1E"}

package/dist/pixelmatch/compareImages.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compareImages.d.ts","sourceRoot":"","sources":["../../src/pixelmatch/compareImages.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,iBAAiB,EAA0B,MAAM,yBAAyB,CAAA;AAqErG,wBAA8B,aAAa,CACvC,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,iBAAiB,GAC3B,OAAO,CAAC,WAAW,CAAC,CA0HtB"}

package/dist/pixelmatch/compareImages.js

@@ -0,0 +1,173 @@
+import pixelmatch from 'pixelmatch';
+import { decodeImage, resizeBilinear, encodeImage } from '../utils/imageUtils.js';
+function resolveIgnoreList(ignore) {
+    if (!ignore) {
+        return [];
+    }
+    return Array.isArray(ignore) ? ignore : [ignore];
+}
+function toPixelmatchOptions(ignoreList) {
+    if (ignoreList.includes('nothing')) {
+        return { threshold: 0, includeAA: true };
+    }
+    if (ignoreList.includes('less')) {
+        // 16/255 per channel in resemble maps roughly to ~6.3% of max YIQ distance
+        return { threshold: 0.063, includeAA: false };
+    }
+    // 'antialiasing', 'alpha', 'colors' and the default.
+    // Resemble's ignoreAntialiasing uses 32/255 per-channel tolerance which
+    // corresponds to ~0.13 in YIQ perceptual distance. Using 0.1 is stricter
+    // and causes invisible sub-pixel differences to register as failures.
+    return { threshold: 0.13, includeAA: false };
+}
+function grayscalePixels(pixels, totalPixels) {
+    for (let i = 0; i < totalPixels * 4; i += 4) {
+        const luma = Math.round(0.299 * pixels[i] + 0.587 * pixels[i + 1] + 0.114 * pixels[i + 2]);
+        pixels[i] = luma;
+        pixels[i + 1] = luma;
+        pixels[i + 2] = luma;
+    }
+}
+function opaqueAlphaChannel(pixels, totalPixels) {
+    for (let i = 3; i < totalPixels * 4; i += 4) {
+        pixels[i] = 255;
+    }
+}
+// Pad a raw RGBA pixel buffer to a larger canvas size, placing the source at
+// position (0, 0) and filling the remaining area with opaque white.
+// Pad source at (0, 0) and fill the remaining area with opaque white.
+function padToSize(src, srcW, srcH, dstW, dstH) {
+    const dst = Buffer.alloc(dstW * dstH * 4, 255); // opaque white
+    for (let y = 0; y < srcH; y++) {
+        src.copy(dst, y * dstW * 4, y * srcW * 4, (y + 1) * srcW * 4);
+    }
+    return dst;
+}
+function zeroIgnoredBoxes(pixels, width, boxes) {
+    for (const box of boxes) {
+        for (let y = box.top; y <= box.bottom; y++) {
+            for (let x = box.left; x <= box.right; x++) {
+                const offset = (y * width + x) * 4;
+                pixels[offset] = 0;
+                pixels[offset + 1] = 0;
+                pixels[offset + 2] = 0;
+                pixels[offset + 3] = 0;
+            }
+        }
+    }
+}
+export default async function compareImages(image1, image2, options) {
+    const start = Date.now();
+    let img1 = decodeImage(image1);
+    let img2 = decodeImage(image2);
+    if (options.scaleToSameSize) {
+        const size1 = img1.width * img1.height;
+        const size2 = img2.width * img2.height;
+        if (size1 > size2) {
+            img2 = resizeBilinear(img2, img1.width, img1.height);
+        }
+        else if (size2 > size1) {
+            img1 = resizeBilinear(img1, img2.width, img2.height);
+        }
+    }
+    // Determine the target canvas size (max of both dimensions).
+    const width = Math.max(img1.width, img2.width);
+    const height = Math.max(img1.height, img2.height);
+    const totalPixels = width * height;
+    // Copy bitmap data into mutable buffers, padding smaller images at (0,0)
+    // with opaque white so content is not shifted by centering.
+    const pixels1 = img1.width === width && img1.height === height
+        ? Buffer.from(img1.data)
+        : padToSize(Buffer.from(img1.data), img1.width, img1.height, width, height);
+    const pixels2 = img2.width === width && img2.height === height
+        ? Buffer.from(img2.data)
+        : padToSize(Buffer.from(img2.data), img2.width, img2.height, width, height);
+    // Snapshot the original actual pixels before any comparison transforms (grayscale,
+    // alpha-opaque, zero-out). The diff image uses this as its background so the real
+    // screenshot content is always visible, including inside blockout regions.
+    const displayPixels2 = Buffer.from(pixels2);
+    const ignoreList = resolveIgnoreList(options.ignore);
+    if (ignoreList.includes('colors')) {
+        grayscalePixels(pixels1, totalPixels);
+        grayscalePixels(pixels2, totalPixels);
+    }
+    if (ignoreList.includes('alpha')) {
+        opaqueAlphaChannel(pixels1, totalPixels);
+        opaqueAlphaChannel(pixels2, totalPixels);
+    }
+    const ignoredBoxes = options.output?.ignoredBoxes ?? [];
+    if (ignoredBoxes.length > 0) {
+        zeroIgnoredBoxes(pixels1, width, ignoredBoxes);
+        zeroIgnoredBoxes(pixels2, width, ignoredBoxes);
+    }
+    const { threshold, includeAA } = toPixelmatchOptions(ignoreList);
+    const outputPixels = new Uint8Array(totalPixels * 4);
+    // Use magenta [255, 0, 255] for both diff and AA pixels.
+    const diffCount = pixelmatch(pixels1, pixels2, outputPixels, width, height, {
+        threshold,
+        includeAA,
+        diffColor: [255, 0, 255],
+        aaColor: [255, 0, 255],
+    });
+    // Collect diff pixel coordinates from the output buffer.
+    // Both diff and AA pixels are drawn in magenta [255, 0, 255]; grayscale pixels are matches.
+    const diffPixels = [];
+    let left = width;
+    let top = height;
+    let right = 0;
+    let bottom = 0;
+    for (let i = 0; i < outputPixels.length; i += 4) {
+        if (outputPixels[i] === 255 && outputPixels[i + 1] === 0 && outputPixels[i + 2] === 255) {
+            const pixelIndex = i / 4;
+            const x = pixelIndex % width;
+            const y = Math.floor(pixelIndex / width);
+            diffPixels.push({ x, y });
+            if (x < left) {
+                left = x;
+            }
+            if (x > right) {
+                right = x;
+            }
+            if (y < top) {
+                top = y;
+            }
+            if (y > bottom) {
+                bottom = y;
+            }
+        }
+    }
+    const diffBounds = diffPixels.length > 0
+        ? { left, top, right, bottom }
+        : { left: width, top: height, right: 0, bottom: 0 };
+    // Single-pass blend: paint diff pixels (magenta) on top of the actual screenshot.
+    // pixels2 is already in memory and normalised to the canvas size, so no extra decode needed.
+    const getRawPixels = () => {
+        const data = new Uint8Array(totalPixels * 4);
+        for (let i = 0; i < data.length; i += 4) {
+            if (outputPixels[i] === 255 && outputPixels[i + 1] === 0 && outputPixels[i + 2] === 255) {
+                data[i] = 255;
+                data[i + 1] = 0;
+                data[i + 2] = 255;
+                data[i + 3] = 255;
+            }
+            else {
+                data[i] = displayPixels2[i];
+                data[i + 1] = displayPixels2[i + 1];
+                data[i + 2] = displayPixels2[i + 2];
+                data[i + 3] = displayPixels2[i + 3];
+            }
+        }
+        return { data, width, height };
+    };
+    const getBuffer = async () => encodeImage(getRawPixels());
+    const rawMisMatchPercentage = (diffCount / totalPixels) * 100;
+    return {
+        rawMisMatchPercentage,
+        misMatchPercentage: Number(rawMisMatchPercentage.toFixed(2)),
+        getRawPixels,
+        getBuffer,
+        diffBounds,
+        analysisTime: Date.now() - start,
+        diffPixels,
+    };
+}

package/dist/pixelmatch/compareImages.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=compareImages.test.d.ts.map

package/dist/pixelmatch/compareImages.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compareImages.test.d.ts","sourceRoot":"","sources":["../../src/pixelmatch/compareImages.test.ts"],"names":[],"mappings":""}

package/dist/pixelmatch/compareImages.test.js

@@ -0,0 +1,262 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+vi.mock('pixelmatch', () => ({
+    default: vi.fn()
+}));
+vi.mock('../utils/imageUtils.js', () => {
+    const makeImage = (width = 100, height = 100) => ({
+        data: new Uint8Array(width * height * 4).fill(128),
+        width,
+        height,
+    });
+    return {
+        decodeImage: vi.fn().mockImplementation(() => makeImage()),
+        resizeBilinear: vi.fn().mockImplementation((_img, w, h) => makeImage(w, h)),
+        encodeImage: vi.fn().mockReturnValue(Buffer.from('png-data')),
+    };
+});
+import compareImages from './compareImages.js';
+import pixelmatch from 'pixelmatch';
+import * as imageUtils from '../utils/imageUtils.js';
+const pixelmatchFn = vi.mocked(pixelmatch);
+const decodeImageFn = vi.mocked(imageUtils.decodeImage);
+const resizeBilinearFn = vi.mocked(imageUtils.resizeBilinear);
+describe('pixelmatch adapter - compareImages', () => {
+    beforeEach(() => {
+        vi.clearAllMocks();
+        decodeImageFn.mockReturnValue({ data: new Uint8Array(100 * 100 * 4).fill(128), width: 100, height: 100 });
+    });
+    describe('basic comparison', () => {
+        it('returns zero mismatch percentage when images are identical', async () => {
+            pixelmatchFn.mockImplementation(() => 0);
+            const result = await compareImages(Buffer.from('img1'), Buffer.from('img2'), {});
+            expect(result.rawMisMatchPercentage).toBe(0);
+            expect(result.misMatchPercentage).toBe(0);
+            expect(result.diffPixels).toHaveLength(0);
+        });
+        it('returns correct mismatch percentage for a known diff count', async () => {
+            // 100x100 = 10000 total pixels, 100 diff pixels = 1%
+            pixelmatchFn.mockImplementation(() => 100);
+            const result = await compareImages(Buffer.from('img1'), Buffer.from('img2'), {});
+            expect(result.rawMisMatchPercentage).toBeCloseTo(1, 5);
+            expect(result.misMatchPercentage).toBe(1);
+        });
+        it('returns analysisTime greater than or equal to 0', async () => {
+            pixelmatchFn.mockImplementation(() => 0);
+            const result = await compareImages(Buffer.from('img1'), Buffer.from('img2'), {});
+            expect(result.analysisTime).toBeGreaterThanOrEqual(0);
+        });
+        it('resolves getBuffer to a Buffer', async () => {
+            pixelmatchFn.mockImplementation(() => 0);
+            const result = await compareImages(Buffer.from('img1'), Buffer.from('img2'), {});
+            const buf = await result.getBuffer();
+            expect(Buffer.isBuffer(buf)).toBe(true);
+        });
+        it('getRawPixels paints diff pixels magenta and keeps actual pixels for matches', async () => {
+            const actual = new Uint8Array(100 * 100 * 4).fill(200); // distinctive actual colour
+            decodeImageFn
+                .mockReturnValueOnce({ data: new Uint8Array(100 * 100 * 4).fill(128), width: 100, height: 100 }) // baseline
+                .mockReturnValueOnce({ data: actual, width: 100, height: 100 }); // actual
+            pixelmatchFn.mockImplementation((_img1, _img2, output) => {
+                // Mark pixel at (0,0) as a diff (magenta)
+                output[0] = 255;
+                output[1] = 0;
+                output[2] = 255;
+                output[3] = 255;
+                // Pixel at (1,0) remains 0 - match
+                return 1;
+            });
+            const result = await compareImages(Buffer.from('img1'), Buffer.from('img2'), {});
+            const raw = result.getRawPixels();
+            // Diff pixel → magenta
+            expect(raw.data[0]).toBe(255);
+            expect(raw.data[1]).toBe(0);
+            expect(raw.data[2]).toBe(255);
+            expect(raw.data[3]).toBe(255);
+            // Match pixel → actual screenshot value (200)
+            expect(raw.data[4]).toBe(200);
+            expect(raw.data[5]).toBe(200);
+            expect(raw.data[6]).toBe(200);
+            expect(raw.width).toBe(100);
+            expect(raw.height).toBe(100);
+        });
+    });
+    describe('diffPixels and diffBounds', () => {
+        it('collects magenta pixels as diff pixel coordinates', async () => {
+            pixelmatchFn.mockImplementation((_img1, _img2, output, width) => {
+                // Place a magenta pixel at x=5, y=3
+                const pos = (3 * width + 5) * 4;
+                output[pos] = 255;
+                output[pos + 1] = 0;
+                output[pos + 2] = 255;
+                output[pos + 3] = 255;
+                return 1;
+            });
+            const result = await compareImages(Buffer.from('img1'), Buffer.from('img2'), {});
+            expect(result.diffPixels).toHaveLength(1);
+            expect(result.diffPixels[0]).toEqual({ x: 5, y: 3 });
+        });
+        it('does not count grayscale matching pixels as diff pixels', async () => {
+            pixelmatchFn.mockImplementation((_img1, _img2, output, width) => {
+                const pos = (2 * width + 10) * 4;
+                output[pos] = 200;
+                output[pos + 1] = 200;
+                output[pos + 2] = 200;
+                output[pos + 3] = 255;
+                return 0;
+            });
+            const result = await compareImages(Buffer.from('img1'), Buffer.from('img2'), {});
+            expect(result.diffPixels).toHaveLength(0);
+        });
+        it('computes correct diffBounds from multiple diff pixels', async () => {
+            pixelmatchFn.mockImplementation((_img1, _img2, output, width) => {
+                const mark = (x, y) => {
+                    const pos = (y * width + x) * 4;
+                    output[pos] = 255;
+                    output[pos + 1] = 0;
+                    output[pos + 2] = 255;
+                    output[pos + 3] = 255;
+                };
+                mark(10, 5);
+                mark(30, 20);
+                mark(20, 10);
+                return 3;
+            });
+            const result = await compareImages(Buffer.from('img1'), Buffer.from('img2'), {});
+            expect(result.diffBounds).toEqual({ left: 10, top: 5, right: 30, bottom: 20 });
+        });
+        it('returns sentinel diffBounds when there are no diff pixels', async () => {
+            pixelmatchFn.mockImplementation(() => 0);
+            const result = await compareImages(Buffer.from('img1'), Buffer.from('img2'), {});
+            expect(result.diffBounds.left).toBeGreaterThan(result.diffBounds.right);
+            expect(result.diffBounds.top).toBeGreaterThan(result.diffBounds.bottom);
+        });
+    });
+    describe('ignore option mapping', () => {
+        it('passes threshold=0 and includeAA=true for ignore: nothing', async () => {
+            pixelmatchFn.mockImplementation(() => 0);
+            await compareImages(Buffer.from('img1'), Buffer.from('img2'), { ignore: 'nothing' });
+            expect(pixelmatchFn).toHaveBeenCalledWith(expect.anything(), expect.anything(), expect.anything(), expect.any(Number), expect.any(Number), expect.objectContaining({ threshold: 0, includeAA: true }));
+        });
+        it('passes threshold=0.063 and includeAA=false for ignore: less', async () => {
+            pixelmatchFn.mockImplementation(() => 0);
+            await compareImages(Buffer.from('img1'), Buffer.from('img2'), { ignore: 'less' });
+            expect(pixelmatchFn).toHaveBeenCalledWith(expect.anything(), expect.anything(), expect.anything(), expect.any(Number), expect.any(Number), expect.objectContaining({ threshold: 0.063, includeAA: false }));
+        });
+        it('passes threshold=0.13 and includeAA=false for ignore: antialiasing', async () => {
+            pixelmatchFn.mockImplementation(() => 0);
+            await compareImages(Buffer.from('img1'), Buffer.from('img2'), { ignore: 'antialiasing' });
+            expect(pixelmatchFn).toHaveBeenCalledWith(expect.anything(), expect.anything(), expect.anything(), expect.any(Number), expect.any(Number), expect.objectContaining({ threshold: 0.13, includeAA: false }));
+        });
+        it('passes threshold=0.13 and includeAA=false when no ignore option is given', async () => {
+            pixelmatchFn.mockImplementation(() => 0);
+            await compareImages(Buffer.from('img1'), Buffer.from('img2'), {});
+            expect(pixelmatchFn).toHaveBeenCalledWith(expect.anything(), expect.anything(), expect.anything(), expect.any(Number), expect.any(Number), expect.objectContaining({ threshold: 0.13, includeAA: false }));
+        });
+        it('accepts ignore as an array and uses the highest-priority mode', async () => {
+            pixelmatchFn.mockImplementation(() => 0);
+            await compareImages(Buffer.from('img1'), Buffer.from('img2'), {
+                ignore: ['antialiasing', 'less']
+            });
+            expect(pixelmatchFn).toHaveBeenCalledWith(expect.anything(), expect.anything(), expect.anything(), expect.any(Number), expect.any(Number), expect.objectContaining({ threshold: 0.063 }));
+        });
+    });
+    describe('pixel transformations', () => {
+        it('grayscales both pixel arrays when ignore includes colors', async () => {
+            let capturedPixels1;
+            pixelmatchFn.mockImplementation((img1) => {
+                capturedPixels1 = new Uint8Array(img1);
+                return 0;
+            });
+            await compareImages(Buffer.from('img1'), Buffer.from('img2'), { ignore: 'colors' });
+            // After grayscale, R=G=B for every pixel (luma of 128,128,128 = 128)
+            expect(capturedPixels1[0]).toBe(capturedPixels1[1]);
+            expect(capturedPixels1[1]).toBe(capturedPixels1[2]);
+        });
+        it('sets all alpha channels to 255 when ignore includes alpha', async () => {
+            // Use image data with alpha < 255
+            decodeImageFn.mockReturnValue({
+                data: new Uint8Array(100 * 100 * 4).fill(0), // all zeros, including alpha
+                width: 100,
+                height: 100,
+            });
+            let capturedPixels1;
+            pixelmatchFn.mockImplementation((img1) => {
+                capturedPixels1 = new Uint8Array(img1);
+                return 0;
+            });
+            await compareImages(Buffer.from('img1'), Buffer.from('img2'), { ignore: 'alpha' });
+            // After opaqueAlphaChannel, every 4th byte should be 255
+            expect(capturedPixels1[3]).toBe(255);
+            expect(capturedPixels1[7]).toBe(255);
+        });
+        it('pads img2 to canvas size when img1 is larger', async () => {
+            decodeImageFn
+                .mockReturnValueOnce({ data: new Uint8Array(100 * 100 * 4).fill(128), width: 100, height: 100 })
+                .mockReturnValueOnce({ data: new Uint8Array(50 * 50 * 4).fill(64), width: 50, height: 50 });
+            pixelmatchFn.mockImplementation(() => 0);
+            await compareImages(Buffer.from('img1'), Buffer.from('img2'), {});
+            // Canvas is 100×100; img2 (50×50) is padded to fill it
+            expect(pixelmatchFn).toHaveBeenCalledWith(expect.any(Object), expect.any(Object), expect.any(Uint8Array), 100, 100, expect.any(Object));
+        });
+        it('pads img1 to canvas size when img2 is larger', async () => {
+            decodeImageFn
+                .mockReturnValueOnce({ data: new Uint8Array(50 * 50 * 4).fill(64), width: 50, height: 50 })
+                .mockReturnValueOnce({ data: new Uint8Array(100 * 100 * 4).fill(128), width: 100, height: 100 });
+            pixelmatchFn.mockImplementation(() => 0);
+            await compareImages(Buffer.from('img1'), Buffer.from('img2'), {});
+            // Canvas is 100×100; img1 (50×50) is padded to fill it
+            expect(pixelmatchFn).toHaveBeenCalledWith(expect.any(Object), expect.any(Object), expect.any(Uint8Array), 100, 100, expect.any(Object));
+        });
+    });
+    describe('ignoredBoxes', () => {
+        it('zeroes out the specified box regions in both pixel arrays before comparison', async () => {
+            let capturedImg1;
+            let capturedImg2;
+            pixelmatchFn.mockImplementation((img1, img2) => {
+                capturedImg1 = new Uint8Array(img1);
+                capturedImg2 = new Uint8Array(img2);
+                return 0;
+            });
+            await compareImages(Buffer.from('img1'), Buffer.from('img2'), {
+                output: {
+                    ignoredBoxes: [{ left: 0, top: 0, right: 0, bottom: 0 }]
+                }
+            });
+            expect(capturedImg1[0]).toBe(0);
+            expect(capturedImg1[1]).toBe(0);
+            expect(capturedImg1[2]).toBe(0);
+            expect(capturedImg1[3]).toBe(0);
+            expect(capturedImg2[0]).toBe(0);
+        });
+    });
+    describe('scaleToSameSize', () => {
+        it('calls resizeBilinear on the smaller image when images differ in size', async () => {
+            decodeImageFn
+                .mockReturnValueOnce({ data: new Uint8Array(100 * 100 * 4), width: 100, height: 100 })
+                .mockReturnValueOnce({ data: new Uint8Array(50 * 50 * 4), width: 50, height: 50 });
+            pixelmatchFn.mockImplementation(() => 0);
+            await compareImages(Buffer.from('img1'), Buffer.from('img2'), { scaleToSameSize: true });
+            expect(resizeBilinearFn).toHaveBeenCalledTimes(1);
+            expect(resizeBilinearFn).toHaveBeenCalledWith(expect.objectContaining({ width: 50, height: 50 }), 100, 100);
+        });
+        it('resizes img1 when img2 is larger', async () => {
+            decodeImageFn
+                .mockReturnValueOnce({ data: new Uint8Array(50 * 50 * 4), width: 50, height: 50 })
+                .mockReturnValueOnce({ data: new Uint8Array(100 * 100 * 4), width: 100, height: 100 });
+            pixelmatchFn.mockImplementation(() => 0);
+            await compareImages(Buffer.from('img1'), Buffer.from('img2'), { scaleToSameSize: true });
+            expect(resizeBilinearFn).toHaveBeenCalledTimes(1);
+            expect(resizeBilinearFn).toHaveBeenCalledWith(expect.objectContaining({ width: 50, height: 50 }), 100, 100);
+        });
+        it('does not call resizeBilinear when scaleToSameSize is false', async () => {
+            pixelmatchFn.mockImplementation(() => 0);
+            await compareImages(Buffer.from('img1'), Buffer.from('img2'), { scaleToSameSize: false });
+            expect(resizeBilinearFn).not.toHaveBeenCalled();
+        });
+        it('does not call resizeBilinear when images are the same size', async () => {
+            pixelmatchFn.mockImplementation(() => 0);
+            await compareImages(Buffer.from('img1'), Buffer.from('img2'), { scaleToSameSize: true });
+            expect(resizeBilinearFn).not.toHaveBeenCalled();
+        });
+    });
+});

package/dist/utils/imageUtils.d.ts

@@ -0,0 +1,17 @@
+export interface RawImage {
+    data: Uint8Array;
+    width: number;
+    height: number;
+}
+export declare function decodeImage(buffer: Buffer): RawImage;
+export declare function encodeImage(img: RawImage): Buffer;
+export declare function toBase64Png(img: RawImage): string;
+export declare function createCanvas(width: number, height: number, r?: number, g?: number, b?: number, a?: number): RawImage;
+export declare function cropImage(img: RawImage, x: number, y: number, w: number, h: number): RawImage;
+export declare function compositeImage(base: RawImage, overlay: RawImage, offsetX: number, offsetY: number, opacity?: number): void;
+export declare function resizeBilinear(img: RawImage, newW: number, newH: number): RawImage;
+export declare function rotate90CW(img: RawImage): RawImage;
+export declare function rotate90CCW(img: RawImage): RawImage;
+export declare function rotate180(img: RawImage): RawImage;
+export declare function setOpacity(img: RawImage, opacity: number): void;
+//# sourceMappingURL=imageUtils.d.ts.map

package/dist/utils/imageUtils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"imageUtils.d.ts","sourceRoot":"","sources":["../../src/utils/imageUtils.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,QAAQ;IACrB,IAAI,EAAE,UAAU,CAAA;IAChB,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,MAAM,CAAA;CACjB;AAsCD,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,QAAQ,CAOpD;AAED,wBAAgB,WAAW,CAAC,GAAG,EAAE,QAAQ,GAAG,MAAM,CAEjD;AAED,wBAAgB,WAAW,CAAC,GAAG,EAAE,QAAQ,GAAG,MAAM,CAEjD;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,SAAI,EAAE,CAAC,SAAI,EAAE,CAAC,SAAI,EAAE,CAAC,SAAI,GAAG,QAAQ,CAWhG;AAED,wBAAgB,SAAS,CAAC,GAAG,EAAE,QAAQ,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,QAAQ,CAQ7F;AAGD,wBAAgB,cAAc,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,SAAI,GAAG,IAAI,CAuBrH;AAED,wBAAgB,cAAc,CAAC,GAAG,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,QAAQ,CAmClF;AAID,wBAAgB,UAAU,CAAC,GAAG,EAAE,QAAQ,GAAG,QAAQ,CAiBlD;AAID,wBAAgB,WAAW,CAAC,GAAG,EAAE,QAAQ,GAAG,QAAQ,CAiBnD;AAED,wBAAgB,SAAS,CAAC,GAAG,EAAE,QAAQ,GAAG,QAAQ,CAYjD;AAGD,wBAAgB,UAAU,CAAC,GAAG,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAI/D"}