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

package/src/assertions/assertions.ts

@@ -0,0 +1,661 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+import { existsSync, mkdirSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+import pixelmatch from "pixelmatch";
+import { PNG } from "pngjs";
+
+import {
+    DEFAULT_SCREENSHOT_THRESHOLD,
+    ENV_VAR,
+    PIXELMATCH_COLOR_THRESHOLD,
+    TREE_DIFF_SNIPPET_MAX_CHARS,
+    TREE_SUMMARY_MAX_CHARS,
+    TREE_SUMMARY_MAX_DEPTH
+} from "../constants";
+import {
+    BaselineMissingError,
+    FocusedNodeMismatchError,
+    NodeNotFoundError,
+    ScreenshotBaselineMissingError,
+    ScreenshotDimensionsMismatchError,
+    ScreenshotMismatchError,
+    TreeMismatchError
+} from "../errors";
+import type { AppUiNode, NodePredicate, ScreenshotMatchOptions, TreeMatchOptions } from "../types";
+import { assertBaselineUpdatesAllowed, updateBaselinesRequested } from "./baseline-env-guard";
+import { atomicWriteFileSync, canvasSizeToResolution, resolveBaselinePath } from "./baselines";
+import { getScreenshotDiffRoot } from "./screenshot-artifacts";
+import type { AlignOffset, PixelRect } from "./screenshot-diff";
+import {
+    buildAlignedPair,
+    findBestAlignOffset,
+    placeDiffOnCanvas,
+    validateAlignTolerance,
+    validateMasks
+} from "./screenshot-diff";
+
+// ---------------------------------------------------------------------------
+// Predicate matching
+// ---------------------------------------------------------------------------
+
+/**
+ * True iff `node` satisfies every populated field of `predicate`.
+ * `tag` exact, `attr` partial (per `(k, v)`), `focused` exact.
+ *
+ * `id` aliases to `attrs.name`: ECP serializes SceneGraph `id` as
+ * the XML `name` attribute, but JSX/XML source uses `id` so we accept
+ * it transparently (matching `name` directly still works).
+ *
+ * Empty predicate `{}` matches every node.
+ */
+export function matchesPredicate(node: AppUiNode, predicate: NodePredicate): boolean {
+    if (predicate.tag !== undefined && node.tag !== predicate.tag) return false;
+    if (predicate.focused !== undefined && node.focused !== predicate.focused) return false;
+    if (predicate.attr) {
+        for (const key of Object.keys(predicate.attr)) {
+            const actual = key === "id" ? (node.attrs.id ?? node.attrs.name) : node.attrs[key];
+            if (actual !== predicate.attr[key]) return false;
+        }
+    }
+    return true;
+}
+
+// ---------------------------------------------------------------------------
+// Tree traversal
+// ---------------------------------------------------------------------------
+
+/**
+ * Non-throwing variant of `findNode`. Internal use only — not
+ * re-exported from `src/index.ts`; external callers use `findNode`
+ * (throws with context) or `findAllNodes`.
+ */
+export function tryFindNode(tree: AppUiNode, predicate: NodePredicate): AppUiNode | null {
+    const stack: AppUiNode[] = [tree];
+    while (stack.length > 0) {
+        const node = stack.pop()!;
+        if (matchesPredicate(node, predicate)) return node;
+        // Reverse-push so document-order "first match wins" holds.
+        for (let i = node.children.length - 1; i >= 0; i--) {
+            stack.push(node.children[i]!);
+        }
+    }
+    return null;
+}
+
+/** First node matching `predicate`. Throws `NodeNotFoundError` if none. */
+export function findNode(tree: AppUiNode, predicate: NodePredicate): AppUiNode {
+    const found = tryFindNode(tree, predicate);
+    if (found) return found;
+    const summary = summarizeTree(tree);
+    throw new NodeNotFoundError(
+        `No node matched predicate ${JSON.stringify(predicate)}. ` +
+            `Tree summary (first ${TREE_SUMMARY_MAX_DEPTH} levels, truncated):\n${summary}`,
+        predicate,
+        summary
+    );
+}
+
+/** All nodes matching `predicate`, document order. Empty array if none. */
+export function findAllNodes(tree: AppUiNode, predicate: NodePredicate): AppUiNode[] {
+    const out: AppUiNode[] = [];
+    const stack: AppUiNode[] = [tree];
+    while (stack.length > 0) {
+        const node = stack.pop()!;
+        if (matchesPredicate(node, predicate)) out.push(node);
+        for (let i = node.children.length - 1; i >= 0; i--) {
+            stack.push(node.children[i]!);
+        }
+    }
+    return out;
+}
+
+/**
+ * Deepest focused node in the tree. SceneGraph propagates `focused`
+ * up the ancestor chain so a naive DFS returns the root-most match
+ * (typically the outer `<screen>`); we descend the focus chain to the
+ * leaf to match tester intent. Throws `NodeNotFoundError` when no
+ * node is focused (a legitimate transient state worth distinguishing
+ * from a generic no-match).
+ */
+export function findFocusedNode(tree: AppUiNode): AppUiNode {
+    const entry = tryFindNode(tree, { focused: true });
+    if (!entry) {
+        const summary = summarizeTree(tree);
+        throw new NodeNotFoundError(`No focused node in tree. Tree summary:\n${summary}`, { focused: true }, summary);
+    }
+    let node = entry;
+    while (true) {
+        const focusedChild = node.children.find(c => c.focused);
+        if (!focusedChild) return node;
+        node = focusedChild;
+    }
+}
+
+/**
+ * Asserts the focused node matches `predicate`. Throws
+ * `NodeNotFoundError` if nothing is focused, or `FocusedNodeMismatchError`
+ * on predicate mismatch.
+ */
+export function expectFocused(tree: AppUiNode, predicate: NodePredicate): void {
+    const focused = findFocusedNode(tree);
+    if (matchesPredicate(focused, predicate)) return;
+    const summary = summarizeNode(focused);
+    throw new FocusedNodeMismatchError(
+        `Focused node does not match predicate ${JSON.stringify(predicate)}. ` + `Focused node: ${summary}`,
+        predicate,
+        summary
+    );
+}
+
+// ---------------------------------------------------------------------------
+// Tree summarization (used inside error messages)
+// ---------------------------------------------------------------------------
+
+/**
+ * Render `tree` as indented pseudo-XML, truncated at `maxDepth`
+ * (children beyond → `[N children]`) and `maxChars`. Diagnostic
+ * format, not a round-trippable serialization.
+ */
+export function summarizeTree(
+    tree: AppUiNode,
+    maxDepth: number = TREE_SUMMARY_MAX_DEPTH,
+    maxChars: number = TREE_SUMMARY_MAX_CHARS
+): string {
+    const lines: string[] = [];
+    function walk(node: AppUiNode, depth: number): void {
+        const indent = "  ".repeat(depth);
+        const attrBits = Object.entries(node.attrs)
+            .slice(0, 4)
+            .map(([k, v]) => `${k}="${truncate(v, 40)}"`)
+            .join(" ");
+        const head = attrBits ? `<${node.tag} ${attrBits}>` : `<${node.tag}>`;
+        lines.push(`${indent}${head}`);
+        if (depth >= maxDepth && node.children.length > 0) {
+            lines.push(`${indent}  [${node.children.length} children]`);
+            return;
+        }
+        for (const child of node.children) walk(child, depth + 1);
+    }
+    walk(tree, 0);
+    const out = lines.join("\n");
+    if (out.length <= maxChars) return out;
+    const cut = out.slice(0, maxChars);
+    return `${cut}\n… (${out.length - maxChars} more chars)`;
+}
+
+/** One-line projection of a node: tag + up to 4 attrs. Used in focus-mismatch errors. */
+function summarizeNode(node: AppUiNode): string {
+    const attrBits = Object.entries(node.attrs)
+        .slice(0, 4)
+        .map(([k, v]) => `${k}="${truncate(v, 40)}"`)
+        .join(" ");
+    return attrBits ? `<${node.tag} ${attrBits}>` : `<${node.tag}>`;
+}
+
+function truncate(s: string, n: number): string {
+    return s.length <= n ? s : `${s.slice(0, n - 1)}…`;
+}
+
+// ---------------------------------------------------------------------------
+// expectTree — baseline comparison
+// ---------------------------------------------------------------------------
+
+export interface TreeAssertion {
+    toMatchBaseline(baselinePath: string, opts?: TreeMatchOptions): Promise<void>;
+}
+
+export interface ScreenshotAssertion {
+    toMatchBaseline(baselinePath: string, opts?: ScreenshotMatchOptions): Promise<void>;
+}
+
+/**
+ * Baseline projection of an `AppUiNode`. `bounds` and `focused` are
+ * dropped: they're derivable from `attrs` and a 1px layout shift
+ * would otherwise rewrite every node's `bounds`.
+ */
+interface SerializedNode {
+    tag: string;
+    attrs: Record<string, string>;
+    children: SerializedNode[];
+}
+
+/**
+ * Device-emitted attributes that are never stable across deploys and
+ * must always be stripped from baselines, independent of the caller's
+ * `exclude`. `rcid` is SceneGraph's render-component id: a per-session
+ * counter that is `0` on a clean first deploy but increments whenever a
+ * node is re-created — e.g. when the deploy-guard retries a flaky
+ * install. Pinning it would make every tree baseline fail spuriously
+ * after a single deploy retry, so it is excluded by default (the same
+ * way `bounds`/`focused` are dropped by living outside `attrs`).
+ */
+const VOLATILE_BASELINE_ATTRS: readonly string[] = ["rcid"];
+
+/**
+ * Serialize `node` to a stable baseline shape: attrs sorted, excludes
+ * stripped recursively, children kept in DOM order (semantically
+ * meaningful for focus/tab order and stacking). Volatile device attrs
+ * (`VOLATILE_BASELINE_ATTRS`) are always stripped in addition to the
+ * caller-supplied `exclude`. A node whose tag is in `excludeChildrenOf`
+ * is kept but serialized as a leaf, hiding internals the app does not
+ * own (native chrome that is restructured between firmware builds).
+ */
+function serializeForBaseline(
+    node: AppUiNode,
+    exclude: readonly string[],
+    excludeChildrenOf: readonly string[]
+): SerializedNode {
+    const excludeSet = new Set<string>([...VOLATILE_BASELINE_ATTRS, ...exclude]);
+    const leafTags = new Set<string>(excludeChildrenOf);
+    function walk(n: AppUiNode): SerializedNode {
+        const attrs: Record<string, string> = {};
+        for (const key of Object.keys(n.attrs).sort()) {
+            if (excludeSet.has(key)) continue;
+            attrs[key] = n.attrs[key]!;
+        }
+        return {
+            tag: n.tag,
+            attrs,
+            children: leafTags.has(n.tag) ? [] : n.children.map(walk)
+        };
+    }
+    return walk(node);
+}
+
+function inferTreeResolution(node: AppUiNode): ReturnType<typeof canvasSizeToResolution> {
+    const stack: AppUiNode[] = [node];
+    while (stack.length > 0) {
+        const current = stack.pop()!;
+        const resolution = canvasSizeToResolution(current.bounds.width, current.bounds.height);
+        if (resolution) {
+            return resolution;
+        }
+        for (let i = 0; i < current.children.length; i++) {
+            stack.push(current.children[i]!);
+        }
+    }
+    return null;
+}
+
+/**
+ * DOM baseline assertion. Reads/writes under
+ * `<baselineRoot>/{hd|fhd}/<baselinePath>`. Full app trees route by
+ * observed canvas bounds; subtrees fall back to the active client's
+ * `videoMode` or `DEVICE_TEST_RESOLUTION`.
+ */
+export function expectTree(node: AppUiNode): TreeAssertion {
+    return {
+        async toMatchBaseline(baselinePath: string, opts?: TreeMatchOptions): Promise<void> {
+            const serialized = serializeForBaseline(node, opts?.exclude ?? [], opts?.excludeChildrenOf ?? []);
+            const json = stableJsonStringify(serialized);
+
+            const inferredResolution = inferTreeResolution(node);
+            const { absolutePath, resolution, videoMode } = resolveBaselinePath(
+                baselinePath,
+                inferredResolution ? { resolution: inferredResolution } : undefined
+            );
+
+            const updating = updateBaselinesRequested();
+
+            if (!existsSync(absolutePath)) {
+                if (updating) {
+                    assertBaselineUpdatesAllowed();
+                    mkdirSync(dirname(absolutePath), { recursive: true });
+                    atomicWriteFileSync(absolutePath, `${json}\n`);
+                    return;
+                }
+                throw new BaselineMissingError(
+                    `Baseline file missing: ${absolutePath}. ` +
+                        `Re-run with ${ENV_VAR.UPDATE_BASELINES}=1 to create it ` +
+                        `(resolution=${resolution}${videoMode ? `, videoMode=${videoMode}` : ""}).`,
+                    absolutePath,
+                    resolution,
+                    videoMode
+                );
+            }
+
+            const existing = readFileSync(absolutePath, "utf8");
+            // Re-stringify to canonicalise hand-edits (trailing
+            // newline / attr-order drift).
+            let parsedExisting: unknown;
+            try {
+                parsedExisting = JSON.parse(existing);
+            } catch (err) {
+                const errMsg = err instanceof Error ? err.message : String(err);
+                throw new TreeMismatchError(
+                    `Baseline at ${absolutePath} is not valid JSON: ${errMsg}. ` +
+                        `Delete it and re-run with ${ENV_VAR.UPDATE_BASELINES}=1 to regenerate.`,
+                    {
+                        baselinePath: absolutePath,
+                        firstDiff: "$",
+                        expectedSnippet: truncate(existing, TREE_DIFF_SNIPPET_MAX_CHARS),
+                        actualSnippet: truncate(json, TREE_DIFF_SNIPPET_MAX_CHARS)
+                    }
+                );
+            }
+            const expectedJson = stableJsonStringify(parsedExisting);
+
+            if (expectedJson === json) return;
+
+            if (updating) {
+                assertBaselineUpdatesAllowed();
+                atomicWriteFileSync(absolutePath, `${json}\n`);
+                return;
+            }
+
+            const diff = firstJsonDiff(parsedExisting, serialized);
+            throw new TreeMismatchError(
+                `Tree does not match baseline ${absolutePath} at ${diff.path}.\n` +
+                    `expected: ${diff.expectedSnippet}\n` +
+                    `actual:   ${diff.actualSnippet}\n` +
+                    `Run with ${ENV_VAR.UPDATE_BASELINES}=1 after reviewing to accept the change.`,
+                {
+                    baselinePath: absolutePath,
+                    firstDiff: diff.path,
+                    expectedSnippet: diff.expectedSnippet,
+                    actualSnippet: diff.actualSnippet
+                }
+            );
+        }
+    };
+}
+
+/** Identity translation: the first (and usually only) attempt. */
+const NO_ALIGN_OFFSET: AlignOffset = { dx: 0, dy: 0 };
+
+/**
+ * PNG baseline assertion. Compares `png` against
+ * `<baselineRoot>/{hd|fhd}/<baselinePath>` via `pixelmatch`.
+ *
+ * Errors:
+ * - Missing baseline + no `UPDATE_BASELINES=1` → `ScreenshotBaselineMissingError`.
+ * - Dimension mismatch → `ScreenshotDimensionsMismatchError` (no diff written).
+ * - Malformed `opts.alignTolerance` → `ScreenshotAlignToleranceError`.
+ * - Mismatch ratio > threshold → `ScreenshotMismatchError` with
+ *   diff PNG written under `getScreenshotDiffRoot()`.
+ *
+ * Masks (`opts.mask`) zero pixels in both images and are excluded
+ * from the ratio denominator. `opts.threshold` is the aggregate
+ * mismatch ratio; the per-pixel YIQ cutoff is a fixed internal
+ * constant (`PIXELMATCH_COLOR_THRESHOLD`) callers can't shift.
+ *
+ * `opts.alignTolerance` lets the capture be translated by a few pixels
+ * to absorb device-dependent re-centering of firmware-drawn surfaces.
+ * It is evaluated only after the untranslated comparison has already
+ * exceeded `threshold`, so it can rescue a failing assertion but never
+ * relax a passing one, and adds no work on the happy path.
+ */
+export function expectScreenshot(png: Buffer): ScreenshotAssertion {
+    return {
+        async toMatchBaseline(baselinePath: string, opts?: ScreenshotMatchOptions): Promise<void> {
+            const threshold = opts?.threshold ?? DEFAULT_SCREENSHOT_THRESHOLD;
+            const rawMasks = opts?.mask ?? [];
+            const actualPng = PNG.sync.read(png);
+            const inferredResolution = canvasSizeToResolution(actualPng.width, actualPng.height);
+            const { absolutePath, resolution } = resolveBaselinePath(
+                baselinePath,
+                inferredResolution ? { resolution: inferredResolution } : undefined
+            );
+            const updating = updateBaselinesRequested();
+
+            // Missing baseline branch.
+            if (!existsSync(absolutePath)) {
+                if (updating) {
+                    assertBaselineUpdatesAllowed();
+                    mkdirSync(dirname(absolutePath), { recursive: true });
+                    atomicWriteFileSync(absolutePath, png);
+                    return;
+                }
+                throw new ScreenshotBaselineMissingError(
+                    `Baseline PNG missing: ${absolutePath}. ` +
+                        `Re-run with ${ENV_VAR.UPDATE_BASELINES}=1 to create it ` +
+                        `(resolution=${resolution}).`,
+                    absolutePath,
+                    resolution
+                );
+            }
+
+            // Parse both PNGs. pngjs throws on invalid bytes — let that
+            // bubble up so corrupted baselines surface as a distinct
+            // parse error (not a fake "mismatch").
+            const baselineBuf = readFileSync(absolutePath);
+            const baselinePng = PNG.sync.read(baselineBuf);
+
+            // Dimension mismatch: pixelmatch REQUIRES equal sizes, and
+            // a diff PNG at mismatched sizes would be meaningless. We
+            // raise a distinct error (no diff written) so the reporter
+            // can tell "the baseline is stale / device resolution
+            // changed" apart from "a few pixels drifted".
+            if (baselinePng.width !== actualPng.width || baselinePng.height !== actualPng.height) {
+                if (updating) {
+                    assertBaselineUpdatesAllowed();
+                    atomicWriteFileSync(absolutePath, png);
+                    return;
+                }
+                throw new ScreenshotDimensionsMismatchError(
+                    `Screenshot dimensions differ from baseline ${absolutePath}: ` +
+                        `baseline ${baselinePng.width}x${baselinePng.height}, ` +
+                        `actual ${actualPng.width}x${actualPng.height}. ` +
+                        `No diff PNG written — pixelmatch cannot compare at different sizes. ` +
+                        `Re-run with ${ENV_VAR.UPDATE_BASELINES}=1 after verifying the resolution change is intentional.`,
+                    {
+                        baselinePath: absolutePath,
+                        resolution,
+                        baseline: { w: baselinePng.width, h: baselinePng.height },
+                        actual: { w: actualPng.width, h: actualPng.height }
+                    }
+                );
+            }
+
+            const w = baselinePng.width;
+            const h = baselinePng.height;
+            // Malformed masks throw ScreenshotMaskError (caller bug);
+            // partially-OOB regions clamp to canvas.
+            const masks = validateMasks(rawMasks, { w, h });
+            // Validated up front, not lazily in the failure path, so a
+            // malformed tolerance is loud on a passing run too.
+            const alignTolerance = validateAlignTolerance(opts?.alignTolerance);
+            const totalPixels = w * h;
+
+            // Compare at one candidate translation. Masking happens on
+            // crops rather than in place, so every attempt sees pristine
+            // pixels — pre-zeroing the originals would make a translated
+            // attempt read zeroed capture pixels against real baseline
+            // pixels along every mask edge.
+            const compareAt = (
+                offset: AlignOffset
+            ): { mismatchedPixels: number; ratio: number; diff: PNG; window: PixelRect } => {
+                const pair = buildAlignedPair(baselinePng, actualPng, masks, offset);
+                const { width, height } = pair.window;
+                const diff = new PNG({ width, height });
+                // `PIXELMATCH_COLOR_THRESHOLD` is a fixed per-pixel YIQ
+                // cutoff; caller-facing `threshold` only governs the
+                // aggregate ratio below.
+                const mismatchedPixels = pixelmatch(pair.baseline.data, pair.actual.data, diff.data, width, height, {
+                    threshold: PIXELMATCH_COLOR_THRESHOLD,
+                    includeAA: false
+                });
+                // Denominator = comparable pixels only: the overlap
+                // window minus its masked pixels. Floor at 1 to avoid
+                // div-by-zero on a fully-masked canvas.
+                const denominator = Math.max(1, width * height - pair.maskedPixels);
+                return { mismatchedPixels, ratio: mismatchedPixels / denominator, diff, window: pair.window };
+            };
+
+            let best = compareAt(NO_ALIGN_OFFSET);
+            const unalignedRatio = best.ratio;
+            let alignment: AlignOffset | undefined;
+
+            // Consulted only once the untranslated comparison has
+            // failed, so `alignTolerance` can rescue a failing assertion
+            // but never loosen a passing one — and costs nothing on the
+            // happy path.
+            if (best.ratio > threshold && alignTolerance) {
+                const candidate = findBestAlignOffset(baselinePng, actualPng, masks, alignTolerance);
+                if (candidate) {
+                    const shifted = compareAt(candidate);
+                    if (shifted.ratio < best.ratio) {
+                        best = shifted;
+                        alignment = candidate;
+                    }
+                }
+            }
+
+            const { mismatchedPixels, ratio } = best;
+            if (ratio <= threshold) return;
+
+            if (updating) {
+                assertBaselineUpdatesAllowed();
+                atomicWriteFileSync(absolutePath, png);
+                return;
+            }
+
+            // Persist the diff PNG before throwing so CI reporters
+            // can attach the artifact even if the error is swallowed.
+            const diffRoot = getScreenshotDiffRoot();
+            const diffFilename = buildDiffFilename(baselinePath);
+            const diffPath = join(diffRoot, diffFilename);
+            mkdirSync(diffRoot, { recursive: true });
+            const diffBuf = PNG.sync.write(placeDiffOnCanvas(best.diff, { w, h }, best.window));
+            atomicWriteFileSync(diffPath, diffBuf);
+
+            // A non-zero alignment that still failed means the surface
+            // both moved and changed; reporting the untranslated ratio
+            // too separates "drifted past the tolerance" from "genuinely
+            // different content".
+            const alignmentNote = alignment
+                ? ` Best alignment dx=${alignment.dx}, dy=${alignment.dy} ` +
+                  `(untranslated ratio was ${unalignedRatio.toFixed(5)}).`
+                : "";
+
+            throw new ScreenshotMismatchError(
+                `Screenshot does not match baseline ${absolutePath}: ` +
+                    `${mismatchedPixels}/${totalPixels} pixels differ ` +
+                    `(unmasked ratio ${ratio.toFixed(5)} > threshold ${threshold}).` +
+                    `${alignmentNote} ` +
+                    `Diff: ${diffPath}. ` +
+                    `Run with ${ENV_VAR.UPDATE_BASELINES}=1 after reviewing to accept the change.`,
+                {
+                    baselinePath: absolutePath,
+                    resolution,
+                    actual: { w, h },
+                    mismatchedPixels,
+                    totalPixels,
+                    ratio,
+                    threshold,
+                    diffPath,
+                    ...(alignment ? { alignment } : {})
+                }
+            );
+        }
+    };
+}
+
+/**
+ * Flatten a relative baseline path into a single diff filename:
+ * `/` → `--`, `.diff` infix before extension. Extensionless paths
+ * get `.diff.png` appended.
+ */
+function buildDiffFilename(relBaselinePath: string): string {
+    const flattened = relBaselinePath.replace(/^\/+/, "").replace(/\//g, "--");
+    const dotIdx = flattened.lastIndexOf(".");
+    if (dotIdx <= 0) return `${flattened}.diff.png`;
+    const stem = flattened.slice(0, dotIdx);
+    const ext = flattened.slice(dotIdx + 1);
+    return `${stem}.diff.${ext}`;
+}
+
+// ---------------------------------------------------------------------------
+// Stable JSON serialization + minimal diff
+// ---------------------------------------------------------------------------
+
+/**
+ * Deterministic JSON serialization with sorted object keys. Arrays
+ * keep their order (DOM order is semantic). Used to produce canonical
+ * baseline strings so byte-level comparison is correct.
+ */
+function stableJsonStringify(value: unknown): string {
+    return JSON.stringify(normalize(value), null, 2);
+}
+
+function normalize(value: unknown): unknown {
+    if (Array.isArray(value)) return value.map(normalize);
+    if (value && typeof value === "object") {
+        const obj = value as Record<string, unknown>;
+        const out: Record<string, unknown> = {};
+        for (const key of Object.keys(obj).sort()) out[key] = normalize(obj[key]);
+        return out;
+    }
+    return value;
+}
+
+/**
+ * First JSONPath-ish location where `expected`/`actual` differ, plus
+ * truncated snippets. Not a general-purpose diff; just an actionable
+ * pointer for the error message.
+ */
+function firstJsonDiff(
+    expected: unknown,
+    actual: SerializedNode
+): { path: string; expectedSnippet: string; actualSnippet: string } {
+    function snippet(v: unknown): string {
+        // `JSON.stringify(undefined)` returns the value `undefined`
+        // (not a string), which then trips `truncate` and was being
+        // mis-reported as `<unserializable>`. A missing attribute on
+        // one side of the diff is the common case (e.g. a device that
+        // emits a non-deterministic, layout-derived attr only on some
+        // runs), so name it explicitly instead of the scary fallback.
+        if (v === undefined) return "undefined";
+        try {
+            return truncate(JSON.stringify(v), TREE_DIFF_SNIPPET_MAX_CHARS);
+        } catch {
+            return "<unserializable>";
+        }
+    }
+    function walk(e: unknown, a: unknown, path: string): ReturnType<typeof firstJsonDiff> | null {
+        if (e === a) return null;
+        if (typeof e !== typeof a || e === null || a === null) {
+            return { path, expectedSnippet: snippet(e), actualSnippet: snippet(a) };
+        }
+        if (Array.isArray(e) || Array.isArray(a)) {
+            if (!Array.isArray(e) || !Array.isArray(a)) {
+                return { path, expectedSnippet: snippet(e), actualSnippet: snippet(a) };
+            }
+            const max = Math.max(e.length, a.length);
+            for (let i = 0; i < max; i++) {
+                if (i >= e.length || i >= a.length) {
+                    return {
+                        path: `${path}[${i}]`,
+                        expectedSnippet: snippet(e[i]),
+                        actualSnippet: snippet(a[i])
+                    };
+                }
+                const nested = walk(e[i], a[i], `${path}[${i}]`);
+                if (nested) return nested;
+            }
+            return null;
+        }
+        if (typeof e === "object" && typeof a === "object") {
+            const eo = e as Record<string, unknown>;
+            const ao = a as Record<string, unknown>;
+            const keys = new Set([...Object.keys(eo), ...Object.keys(ao)]);
+            for (const key of [...keys].sort()) {
+                const nested = walk(eo[key], ao[key], `${path}.${key}`);
+                if (nested) return nested;
+            }
+            return null;
+        }
+        return { path, expectedSnippet: snippet(e), actualSnippet: snippet(a) };
+    }
+    const hit = walk(expected, actual, "$");
+    if (hit) return hit;
+    // Unreachable: caller only invokes us after stringified forms
+    // already differ. Sentinel for typecheck.
+    return {
+        path: "$",
+        expectedSnippet: snippet(expected),
+        actualSnippet: snippet(actual)
+    };
+}