@roku-sdk/device-test-client 0.0.0-stage → 2.19.0

package/src/assertions/screenshot-diff.ts

@@ -0,0 +1,447 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+/**
+ * Pure mask + diff helpers, shared by `captureStableScreenshot` and
+ * `expectScreenshot`. Leaf module (no I/O, no client coupling).
+ *
+ * `MaskRegion` coords are raw pixels of the resolved canvas (no dpi
+ * scaling); baselines are committed per-resolution.
+ */
+
+import { PNG } from "pngjs";
+
+import { ALIGN_TOLERANCE_MAX_PX } from "../constants";
+import { ScreenshotAlignToleranceError, ScreenshotMaskError } from "../errors";
+import type { AlignTolerance, MaskRegion } from "../types";
+
+/**
+ * Normalize mask regions: floor coords/sizes (so a region never
+ * grows beyond intent), throw on zero-area or fully-OOB, clamp
+ * partial-OOB to the canvas intersection. The clamp lets a test
+ * authored against FHD survive an HD run, but the clamped region
+ * covers different absolute content on each resolution — callers
+ * needing resolution-specific masks must gate on `videoMode`.
+ */
+export function validateMasks(masks: MaskRegion[] | undefined, canvas: { w: number; h: number }): MaskRegion[] {
+    if (!masks || masks.length === 0) return [];
+    const out: MaskRegion[] = [];
+    for (const raw of masks) {
+        const x = Math.floor(raw.x);
+        const y = Math.floor(raw.y);
+        const w = Math.floor(raw.width);
+        const h = Math.floor(raw.height);
+
+        if (w <= 0 || h <= 0) {
+            throw new ScreenshotMaskError(
+                `Invalid mask region: width=${w}, height=${h}. ` +
+                    `Width and height must both be positive integers after flooring.`,
+                { region: raw, canvas, reason: "zero-area" }
+            );
+        }
+        // Fully OOB: region has no intersection with the canvas
+        // (pixels are half-open on right/bottom).
+        if (x + w <= 0 || y + h <= 0 || x >= canvas.w || y >= canvas.h) {
+            throw new ScreenshotMaskError(
+                `Mask region is fully outside the ${canvas.w}x${canvas.h} canvas: ` +
+                    `{x:${raw.x}, y:${raw.y}, width:${raw.width}, height:${raw.height}}.`,
+                { region: raw, canvas, reason: "out-of-bounds" }
+            );
+        }
+        const clampedX = Math.max(0, x);
+        const clampedY = Math.max(0, y);
+        const clampedRight = Math.min(canvas.w, x + w);
+        const clampedBottom = Math.min(canvas.h, y + h);
+        out.push({
+            x: clampedX,
+            y: clampedY,
+            width: clampedRight - clampedX,
+            height: clampedBottom - clampedY
+        });
+    }
+    return out;
+}
+
+/**
+ * Overwrite masked pixels with a solid RGBA fill. `fill` is 32-bit
+ * little-endian (byte 0 = R, 1 = G, 2 = B, 3 = A). `0x00000000` is
+ * transparent black — the default so diff PNGs show masked regions
+ * as a neutral patch. Caller passes validated regions; OOB regions
+ * are also clamped here defensively.
+ */
+export function applyMaskInPlace(png: PNG, masks: MaskRegion[], fill: number): void {
+    if (masks.length === 0) return;
+    const w = png.width;
+    const h = png.height;
+    const r = fill & 0xff;
+    const g = (fill >>> 8) & 0xff;
+    const b = (fill >>> 16) & 0xff;
+    const a = (fill >>> 24) & 0xff;
+    const data = png.data;
+    for (const m of masks) {
+        const x0 = Math.max(0, m.x);
+        const y0 = Math.max(0, m.y);
+        const x1 = Math.min(w, m.x + m.width);
+        const y1 = Math.min(h, m.y + m.height);
+        for (let y = y0; y < y1; y++) {
+            let off = (y * w + x0) * 4;
+            for (let x = x0; x < x1; x++) {
+                data[off] = r;
+                data[off + 1] = g;
+                data[off + 2] = b;
+                data[off + 3] = a;
+                off += 4;
+            }
+        }
+    }
+}
+
+/**
+ * Pixel-by-pixel comparison outside the mask. We don't short-circuit
+ * on first miss: `ScreenshotNotStableError.lastDiffCount` surfaces
+ * how close the app was to settling (3 vs 9000 is a very different
+ * diagnosis). Dimension mismatch returns total disagreement
+ * defensively; ECP always returns same-resolution captures.
+ */
+export function pngsEqualOutsideMask(
+    a: PNG,
+    b: PNG,
+    masks: MaskRegion[]
+): { equal: boolean; diffCount: number; firstDiffPoint?: { x: number; y: number } } {
+    if (a.width !== b.width || a.height !== b.height) {
+        const diffCount = Math.max(a.width * a.height, b.width * b.height);
+        return { equal: false, diffCount };
+    }
+    const w = a.width;
+    const h = a.height;
+    const pixelCount = w * h;
+    const maskedAt = buildMaskBitmap(masks, w, h);
+
+    let diffCount = 0;
+    let firstDiffPoint: { x: number; y: number } | undefined;
+    const ad = a.data;
+    const bd = b.data;
+    for (let i = 0; i < pixelCount; i++) {
+        if (maskedAt[i]) continue;
+        const off = i * 4;
+        if (
+            ad[off] !== bd[off] ||
+            ad[off + 1] !== bd[off + 1] ||
+            ad[off + 2] !== bd[off + 2] ||
+            ad[off + 3] !== bd[off + 3]
+        ) {
+            diffCount += 1;
+            if (!firstDiffPoint) {
+                firstDiffPoint = { x: i % w, y: Math.floor(i / w) };
+            }
+        }
+    }
+    return { equal: diffCount === 0, diffCount, firstDiffPoint };
+}
+
+/**
+ * Unique pixels covered by validated+clamped mask regions
+ * (overlaps not double-counted). Denominator for the mismatch ratio.
+ */
+export function countMaskedPixels(masks: MaskRegion[], canvas: { w: number; h: number }): number {
+    if (masks.length === 0) return 0;
+    const bitmap = buildMaskBitmap(masks, canvas.w, canvas.h);
+    let count = 0;
+    for (let i = 0; i < bitmap.length; i++) {
+        if (bitmap[i]) count += 1;
+    }
+    return count;
+}
+
+/** 1-byte-per-pixel mask bitmap; O(sum of region areas) build. */
+export function buildMaskBitmap(masks: MaskRegion[], w: number, h: number): Uint8Array {
+    const bitmap = new Uint8Array(w * h);
+    for (const m of masks) {
+        const x0 = Math.max(0, m.x);
+        const y0 = Math.max(0, m.y);
+        const x1 = Math.min(w, m.x + m.width);
+        const y1 = Math.min(h, m.y + m.height);
+        for (let y = y0; y < y1; y++) {
+            const rowStart = y * w;
+            for (let x = x0; x < x1; x++) {
+                bitmap[rowStart + x] = 1;
+            }
+        }
+    }
+    return bitmap;
+}
+
+// ---------------------------------------------------------------------------
+// Alignment search
+// ---------------------------------------------------------------------------
+
+/**
+ * Whole-pixel translation applied to the capture: baseline pixel
+ * `(x, y)` is scored against capture pixel `(x + dx, y + dy)`.
+ */
+export interface AlignOffset {
+    dx: number;
+    dy: number;
+}
+
+/** Resolved per-axis search radius; both values are >= 0 integers. */
+export interface ResolvedAlignTolerance {
+    x: number;
+    y: number;
+}
+
+/**
+ * Validate and resolve `alignTolerance`. Returns `null` when there is
+ * nothing to search (option absent, or both axes zero) so callers can
+ * skip the search entirely. Both axes are validated before the
+ * no-op check, so `{ y: -1 }` throws rather than being ignored.
+ */
+export function validateAlignTolerance(raw: AlignTolerance | undefined): ResolvedAlignTolerance | null {
+    if (!raw) return null;
+    const x = validateAlignAxis("x", raw.x ?? 0);
+    const y = validateAlignAxis("y", raw.y ?? 0);
+    if (x === 0 && y === 0) return null;
+    return { x, y };
+}
+
+function validateAlignAxis(axis: "x" | "y", value: number): number {
+    const fail = (reason: "not-an-integer" | "negative" | "over-cap", detail: string): never => {
+        throw new ScreenshotAlignToleranceError(`Invalid alignTolerance.${axis}=${value}: ${detail}`, {
+            axis,
+            value,
+            max: ALIGN_TOLERANCE_MAX_PX,
+            reason
+        });
+    };
+    if (!Number.isInteger(value)) {
+        fail("not-an-integer", "must be an integer number of pixels.");
+    }
+    if (value < 0) {
+        fail("negative", "must not be negative; the radius applies in both directions.");
+    }
+    if (value > ALIGN_TOLERANCE_MAX_PX) {
+        fail(
+            "over-cap",
+            `exceeds the ${ALIGN_TOLERANCE_MAX_PX}px cap. A larger window would let the ` +
+                `comparator align genuinely different content; re-capture the baseline instead.`
+        );
+    }
+    return value;
+}
+
+/**
+ * Every offset in the tolerance box except `(0, 0)`, ordered smallest
+ * translation first: by Manhattan distance, then by magnitude on each
+ * axis, then by sign. The caller scores all of them and keeps the first
+ * minimum, so this order is what makes ties break deterministically and
+ * in favour of the least movement. The comparator is total, so the
+ * sequence does not depend on the engine's sort stability.
+ */
+export function alignmentCandidates(tol: ResolvedAlignTolerance): AlignOffset[] {
+    const out: AlignOffset[] = [];
+    for (let dy = -tol.y; dy <= tol.y; dy++) {
+        for (let dx = -tol.x; dx <= tol.x; dx++) {
+            if (dx === 0 && dy === 0) continue;
+            // A zero-tolerance axis yields `-0`, which would reach
+            // `ScreenshotMismatchError.context`; normalize to plain 0.
+            out.push({ dx: dx === 0 ? 0 : dx, dy: dy === 0 ? 0 : dy });
+        }
+    }
+    out.sort(
+        (a, b) =>
+            Math.abs(a.dx) + Math.abs(a.dy) - (Math.abs(b.dx) + Math.abs(b.dy)) ||
+            Math.abs(a.dy) - Math.abs(b.dy) ||
+            Math.abs(a.dx) - Math.abs(b.dx) ||
+            a.dy - b.dy ||
+            a.dx - b.dx
+    );
+    return out;
+}
+
+/**
+ * Pixel rectangle. Structurally a `MaskRegion`, but kept distinct so a
+ * comparison window is never mistaken for something being hidden.
+ */
+export interface PixelRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+
+/**
+ * Rectangle of baseline pixels that has a counterpart in the capture
+ * once the capture is translated by `offset`. `x`/`y` are the window's
+ * top-left in baseline coordinates; the trailing `|dx|` columns and
+ * `|dy|` rows have no counterpart and are dropped.
+ *
+ * Degenerate for an offset at least as large as the canvas, so callers
+ * that iterate candidates must skip non-positive windows.
+ */
+export function alignedWindow(offset: AlignOffset, canvas: { w: number; h: number }): PixelRect {
+    const x = Math.max(0, -offset.dx);
+    const y = Math.max(0, -offset.dy);
+    return {
+        x,
+        y,
+        width: Math.min(canvas.w, canvas.w - offset.dx) - x,
+        height: Math.min(canvas.h, canvas.h - offset.dy) - y
+    };
+}
+
+/**
+ * Cheap exact-byte mismatch ratio for one candidate offset, used only
+ * to RANK offsets. Exact equality is stricter than pixelmatch's YIQ
+ * cutoff, so the two metrics can in principle disagree on which offset
+ * is best; ranking by this one keeps the search a few milliseconds per
+ * candidate instead of a full pixelmatch pass. The verdict is never
+ * taken from here — the caller re-runs pixelmatch at the winning offset
+ * — so a disagreement can only settle for a marginally worse offset,
+ * never turn a real mismatch into a pass.
+ *
+ * `maskBitmap` is in baseline canvas coordinates (see
+ * `buildMaskBitmap`) and is reused across candidates.
+ *
+ * `ratio` is `Infinity` when the offset leaves nothing to compare
+ * (degenerate window, or every remaining pixel masked), so such an
+ * offset can never win the search by scoring a vacuous zero.
+ */
+export function scoreAlignOffset(
+    baseline: PNG,
+    actual: PNG,
+    maskBitmap: Uint8Array,
+    offset: AlignOffset
+): { diffCount: number; comparable: number; ratio: number } {
+    const w = baseline.width;
+    const win = alignedWindow(offset, { w, h: baseline.height });
+    const bd = baseline.data;
+    const ad = actual.data;
+
+    let diffCount = 0;
+    let comparable = 0;
+    for (let y = win.y; y < win.y + win.height; y++) {
+        const baseRow = y * w;
+        const actualRow = (y + offset.dy) * w;
+        for (let x = win.x; x < win.x + win.width; x++) {
+            if (maskBitmap[baseRow + x]) continue;
+            comparable += 1;
+            const bo = (baseRow + x) * 4;
+            const ao = (actualRow + x + offset.dx) * 4;
+            if (
+                bd[bo] !== ad[ao] ||
+                bd[bo + 1] !== ad[ao + 1] ||
+                bd[bo + 2] !== ad[ao + 2] ||
+                bd[bo + 3] !== ad[ao + 3]
+            ) {
+                diffCount += 1;
+            }
+        }
+    }
+    return {
+        diffCount,
+        comparable,
+        ratio: comparable > 0 ? diffCount / comparable : Number.POSITIVE_INFINITY
+    };
+}
+
+/**
+ * Best-scoring offset in the tolerance box, or `null` when the box is
+ * empty or every offset leaves nothing to compare. Ranking only — the
+ * caller must still run the authoritative comparison at the returned
+ * offset, and may assume the offset yields a non-degenerate window.
+ *
+ * Starting `bestRatio` at `Infinity` is what excludes the degenerate
+ * offsets that `scoreAlignOffset` scores as `Infinity`; a strict `<`
+ * keeps the first (smallest) offset on ties.
+ */
+export function findBestAlignOffset(
+    baseline: PNG,
+    actual: PNG,
+    masks: MaskRegion[],
+    tol: ResolvedAlignTolerance
+): AlignOffset | null {
+    const maskBitmap = buildMaskBitmap(masks, baseline.width, baseline.height);
+    let best: AlignOffset | null = null;
+    let bestRatio = Number.POSITIVE_INFINITY;
+    for (const candidate of alignmentCandidates(tol)) {
+        const { ratio } = scoreAlignOffset(baseline, actual, maskBitmap, candidate);
+        if (ratio < bestRatio) {
+            bestRatio = ratio;
+            best = candidate;
+        }
+    }
+    return best;
+}
+
+/**
+ * Crop both images to `alignedWindow(offset)` — the capture read at
+ * its translated position — and zero the masked pixels in both, ready
+ * for `pixelmatch`. Masks are authored in baseline canvas coordinates
+ * and so land on the intended content in the baseline and on its
+ * translated counterpart in the capture.
+ *
+ * `offset` must yield a non-degenerate `alignedWindow` — the identity
+ * offset always does, and `findBestAlignOffset` never returns one that
+ * does not.
+ */
+export function buildAlignedPair(
+    baseline: PNG,
+    actual: PNG,
+    masks: MaskRegion[],
+    offset: AlignOffset
+): { baseline: PNG; actual: PNG; window: PixelRect; maskedPixels: number } {
+    const w = baseline.width;
+    const win = alignedWindow(offset, { w, h: baseline.height });
+    const croppedBaseline = new PNG({ width: win.width, height: win.height });
+    const croppedActual = new PNG({ width: win.width, height: win.height });
+
+    for (let row = 0; row < win.height; row++) {
+        const destStart = row * win.width * 4;
+        const baseStart = ((win.y + row) * w + win.x) * 4;
+        const actualStart = ((win.y + row + offset.dy) * w + win.x + offset.dx) * 4;
+        baseline.data.copy(croppedBaseline.data, destStart, baseStart, baseStart + win.width * 4);
+        actual.data.copy(croppedActual.data, destStart, actualStart, actualStart + win.width * 4);
+    }
+
+    // Translate masks from canvas space into the window's frame; both
+    // crops already carry their own offset, so one translation serves
+    // both. Zero-area intersections are dropped rather than validated
+    // again — the regions were validated against the full canvas.
+    const windowMasks: MaskRegion[] = [];
+    for (const m of masks) {
+        const x0 = Math.max(0, m.x - win.x);
+        const y0 = Math.max(0, m.y - win.y);
+        const x1 = Math.min(win.width, m.x + m.width - win.x);
+        const y1 = Math.min(win.height, m.y + m.height - win.y);
+        if (x1 <= x0 || y1 <= y0) continue;
+        windowMasks.push({ x: x0, y: y0, width: x1 - x0, height: y1 - y0 });
+    }
+    applyMaskInPlace(croppedBaseline, windowMasks, 0x00000000);
+    applyMaskInPlace(croppedActual, windowMasks, 0x00000000);
+
+    return {
+        baseline: croppedBaseline,
+        actual: croppedActual,
+        window: win,
+        maskedPixels: countMaskedPixels(windowMasks, { w: win.width, h: win.height })
+    };
+}
+
+/**
+ * Lift a window-sized diff back onto a full canvas at the window's
+ * baseline coordinates, so diff-PNG coordinates always line up with
+ * the baseline. Rows/columns outside the window had no counterpart to
+ * compare and stay transparent.
+ */
+export function placeDiffOnCanvas(windowDiff: PNG, canvas: { w: number; h: number }, window: PixelRect): PNG {
+    if (window.x === 0 && window.y === 0 && windowDiff.width === canvas.w && windowDiff.height === canvas.h) {
+        return windowDiff;
+    }
+    const full = new PNG({ width: canvas.w, height: canvas.h });
+    full.data.fill(0);
+    for (let row = 0; row < window.height; row++) {
+        const srcStart = row * window.width * 4;
+        const destStart = ((window.y + row) * canvas.w + window.x) * 4;
+        windowDiff.data.copy(full.data, destStart, srcStart, srcStart + window.width * 4);
+    }
+    return full;
+}