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

package/src/assertions/baseline-env-guard.ts

@@ -0,0 +1,43 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+/**
+ * Stateless env guards for baseline writes. Leaf module: must not
+ * import from `client.ts`, `assertions.ts`, or `jest-setup.ts` to
+ * break the circular import that arose when assertions needed a CI
+ * guard reachable via jest-setup.
+ */
+
+import { ENV_VAR } from "../constants";
+
+// Symmetric across `CI` and `UPDATE_BASELINES` so the bash
+// pre-flight and this code-side guard agree on what "set" means.
+const TRUTHY_VALUES: ReadonlySet<string> = new Set(["1", "true", "yes"]);
+
+function isTruthyEnv(raw: string | undefined): boolean {
+    if (raw === undefined || raw === "") return false;
+    return TRUTHY_VALUES.has(raw.toLowerCase());
+}
+
+export function isCi(): boolean {
+    return isTruthyEnv(process.env[ENV_VAR.CI]);
+}
+
+/**
+ * True iff `UPDATE_BASELINES` is set to a truthy spelling
+ * (`1`/`true`/`yes`, case-insensitive).
+ */
+export function updateBaselinesRequested(): boolean {
+    return isTruthyEnv(process.env[ENV_VAR.UPDATE_BASELINES]);
+}
+
+/**
+ * Throws if `UPDATE_BASELINES` is set in CI. Mirrors the bash
+ * pre-flight in `.gitlab-ci.yml`.
+ */
+export function assertBaselineUpdatesAllowed(): void {
+    if (isCi() && updateBaselinesRequested()) {
+        throw new Error(
+            `${ENV_VAR.UPDATE_BASELINES}=1 is not allowed in CI. ` + "Update baselines locally and commit them."
+        );
+    }
+}

package/src/assertions/baselines.ts

@@ -0,0 +1,178 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+/**
+ * Baseline path resolver. Module-level state (vs class) because
+ * `expectTree` has no convenient DI point and Jest runs one
+ * RkClient per worker.
+ *
+ * Resolution subdir precedence:
+ *   1. Active client + recognised `videoMode` → mapped resolution
+ *      (env override deliberately NOT consulted here).
+ *   2. Active client + unrecognised `videoMode` → throw
+ *      `BaselineResolutionError({reason:"unsupported-videoMode"})`.
+ *      We refuse env fallback so firmware drift fails fast.
+ *   3. No active client → consult `DEVICE_TEST_RESOLUTION`.
+ */
+
+import { randomBytes } from "node:crypto";
+import { renameSync, unlinkSync, writeFileSync } from "node:fs";
+
+import { BASELINE_RESOLUTION_DIR, ENV_VAR } from "../constants";
+import { BaselineResolutionError } from "../errors";
+import type { DeviceInfo } from "../types";
+
+/** Minimal `RkClient` shape; avoids a circular import. */
+export interface ActiveClientLike {
+    cachedDeviceInfo(): DeviceInfo | null;
+}
+
+export type BaselineResolution = "hd" | "fhd";
+
+let baselineRoot: string | null = null;
+let activeClient: ActiveClientLike | null = null;
+
+/** Register the absolute path to the consumer's `baselines/` directory. */
+export function setBaselineRoot(absPath: string): void {
+    baselineRoot = absPath;
+}
+
+/**
+ * Register the shared `RkClient` so baseline resolution can read its
+ * cached `videoMode`. Pass `null` to clear.
+ */
+export function setActiveClient(client: ActiveClientLike | null): void {
+    activeClient = client;
+}
+
+/**
+ * Map `DeviceInfo.videoMode` to baseline subdir: 720p → hd, 1080p →
+ * fhd. Returns null for unknown modes.
+ */
+export function videoModeToResolution(videoMode: string): BaselineResolution | null {
+    if (videoMode === "720p" || videoMode === "720p60") return "hd";
+    if (videoMode === "1080p" || videoMode === "1080p60") return "fhd";
+    return null;
+}
+
+/**
+ * Map an observed canvas size to the matching baseline subdir. This is
+ * intentionally separate from `videoModeToResolution`: fixture apps that
+ * do not set `ui_resolutions=fhd` can render/capture at 1280x720 even on
+ * a device whose output video mode reports 1080p.
+ */
+export function canvasSizeToResolution(width: number, height: number): BaselineResolution | null {
+    if (width === 1280 && height === 720) return "hd";
+    if (width === 1920 && height === 1080) return "fhd";
+    return null;
+}
+
+/**
+ * Resolve `{hd|fhd}` subdir per precedence at top of module.
+ * Throws `BaselineResolutionError` with a discriminated `reason`
+ * for each failure mode.
+ */
+export function resolveResolution(): {
+    resolution: BaselineResolution;
+    videoMode: string | undefined;
+} {
+    // Precedence 1/2: active client is the authoritative signal.
+    if (activeClient) {
+        const info = activeClient.cachedDeviceInfo() ?? null;
+        const videoMode = info?.videoMode ?? "";
+        if (videoMode) {
+            const res = videoModeToResolution(videoMode);
+            if (res) return { resolution: res, videoMode };
+            throw new BaselineResolutionError(
+                `Cannot resolve baseline resolution: active RkClient reports ` +
+                    `unsupported videoMode "${videoMode}". Supported values: ` +
+                    `720p, 720p60, 1080p, 1080p60. To bypass the active client ` +
+                    `(e.g. for an ad-hoc smoke run), first call ` +
+                    `setActiveClient(null) and then set ` +
+                    `${ENV_VAR.DEVICE_TEST_RESOLUTION}=hd|fhd. The env ` +
+                    `override is intentionally ignored while a client is ` +
+                    `registered so unsupported firmware modes fail fast ` +
+                    `instead of silently using the wrong baseline subdir.`,
+                { videoMode, reason: "unsupported-videoMode" }
+            );
+        }
+        // Cache empty/blank: treat as "no signal" and fall through.
+        // Rare; globalSetup seeds the cache before tests run.
+    }
+
+    // Precedence 3: env override.
+    const envRaw = process.env[ENV_VAR.DEVICE_TEST_RESOLUTION];
+    if (envRaw === undefined || envRaw === "") {
+        throw new BaselineResolutionError(
+            `Cannot resolve baseline resolution: no active RkClient with ` +
+                `cached DeviceInfo.videoMode, and ${ENV_VAR.DEVICE_TEST_RESOLUTION} ` +
+                `is not set. Register the client via setActiveClient(client) ` +
+                `in your setup file, or export ` +
+                `${ENV_VAR.DEVICE_TEST_RESOLUTION}=hd|fhd for ad-hoc runs.`,
+            { reason: "no-active-client-and-no-env" }
+        );
+    }
+    if (envRaw !== "hd" && envRaw !== "fhd") {
+        throw new BaselineResolutionError(
+            `Cannot resolve baseline resolution: ` +
+                `${ENV_VAR.DEVICE_TEST_RESOLUTION}="${envRaw}" is not a valid ` +
+                `value. Supported: "hd", "fhd".`,
+            { reason: "invalid-env-value" }
+        );
+    }
+    return { resolution: envRaw, videoMode: undefined };
+}
+
+/**
+ * Atomic write via tmp-file + same-dir rename. Tmp suffix is
+ * pid+random so concurrent writers can't clobber each other's tmp
+ * and a crashed writer can't leave a stale tmp another writer would
+ * rename over. Cleanup targets the unique tmp this invocation
+ * created. Accepts string (utf8) or Buffer (binary).
+ */
+export function atomicWriteFileSync(absPath: string, contents: string | Buffer): void {
+    const tmp = `${absPath}.${process.pid}.${randomBytes(4).toString("hex")}.tmp`;
+    try {
+        if (typeof contents === "string") {
+            writeFileSync(tmp, contents, "utf8");
+        } else {
+            writeFileSync(tmp, contents);
+        }
+        renameSync(tmp, absPath);
+    } catch (err) {
+        try {
+            unlinkSync(tmp);
+        } catch {
+            // best-effort cleanup
+        }
+        throw err;
+    }
+}
+
+/**
+ * Absolute on-disk path for a baseline fragment.
+ * Root precedence: `setBaselineRoot()` > `DEVICE_TEST_BASELINES` env
+ * > `<cwd>/baselines`. Subdir comes from `resolveResolution()`.
+ */
+export function resolveBaselinePath(
+    baselinePath: string,
+    opts?: { resolution?: BaselineResolution; videoMode?: string }
+): {
+    absolutePath: string;
+    resolution: BaselineResolution;
+    videoMode: string | undefined;
+} {
+    const root = baselineRoot ?? process.env[ENV_VAR.DEVICE_TEST_BASELINES] ?? `${process.cwd()}/baselines`;
+    const { resolution, videoMode } = opts?.resolution
+        ? { resolution: opts.resolution, videoMode: opts.videoMode }
+        : resolveResolution();
+    const subdir = BASELINE_RESOLUTION_DIR[resolution];
+    const cleaned = baselinePath.replace(/^\/+/, "");
+    const absolutePath = `${root}/${subdir}/${cleaned}`;
+    return { absolutePath, resolution, videoMode };
+}
+
+/** Test-only: clear module state. Not re-exported from `index.ts`. */
+export function __resetBaselineStateForTests(): void {
+    baselineRoot = null;
+    activeClient = null;
+}

package/src/assertions/screenshot-artifacts.ts

@@ -0,0 +1,39 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+/**
+ * Module-level diff-root for screenshot failure PNGs. Leaf module
+ * (no `client.ts`/`assertions.ts` imports) so both `assertions.ts`
+ * and `jest-setup.ts` can read/write it without circular imports.
+ *
+ * Precedence: explicit `setScreenshotDiffRoot()` wins; otherwise
+ * `<process.cwd()>/test-results/diffs` resolved lazily on read.
+ */
+
+import { join } from "node:path";
+
+import { SCREENSHOT_DIFF_DIR } from "../constants";
+
+let diffRoot: string | null = null;
+
+/**
+ * Register the absolute directory for screenshot diff PNGs.
+ * Caller should resolve to an absolute path so workers with
+ * divergent cwds still write into the same directory.
+ */
+export function setScreenshotDiffRoot(absPath: string): void {
+    diffRoot = absPath;
+}
+
+/**
+ * Configured diff root, or `<cwd>/test-results/diffs` lazily so
+ * `process.chdir()` between setup and test doesn't stale the path.
+ */
+export function getScreenshotDiffRoot(): string {
+    if (diffRoot !== null) return diffRoot;
+    return join(process.cwd(), SCREENSHOT_DIFF_DIR);
+}
+
+/** Test-only: clear module state. Not re-exported from `index.ts`. */
+export function __resetScreenshotDiffRootForTests(): void {
+    diffRoot = null;
+}