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

package/src/jest/install-hooks.ts

@@ -0,0 +1,488 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+import { setActiveClient, setBaselineRoot } from "../assertions/baselines";
+import { setScreenshotDiffRoot } from "../assertions/screenshot-artifacts";
+import { RkClient } from "../client/client";
+import {
+    getFatalReason,
+    getUnhealthyReason,
+    isDeviceFatal,
+    isDeviceHealthy,
+    resetDeviceHealth
+} from "../client/health";
+import {
+    DEVICE_ENV_GLOBAL_KEY,
+    DEVICE_ONLINE_DEFAULT_TIMEOUT_MS,
+    DEVICE_ONLINE_POLL_INTERVAL_MS,
+    DEVICE_RECOVERY_DEFAULT_RETRIES
+} from "../constants";
+import { setDeviceEnvFile } from "../device/device-env-sync";
+import { DeviceUnhealthyError } from "../errors";
+import type { DeviceLogSink } from "../logs/device-log-sink";
+import { attachToBuffer, openDeviceLogSink } from "../logs/device-log-sink";
+
+/** Options for `installDeviceTestHooks`. */
+export interface InstallDeviceTestHooksOptions {
+    /**
+     * `RkClient` for log-session auto-start. Omitting skips auto-start
+     * with a console warning. Ignored when `startLogSession: false`.
+     */
+    client?: RkClient;
+    /** Opt-out for `beforeAll` log-session attach. Defaults to `true`. */
+    startLogSession?: boolean;
+    /**
+     * Diff PNG output root. Defaults to
+     * `<cwd>/test-results/diffs` via the module-level setter.
+     */
+    diffRoot?: string;
+    /**
+     * Baselines directory. Defaults to `DEVICE_TEST_BASELINES` env or
+     * `<cwd>/baselines`.
+     */
+    baselineRoot?: string;
+    /**
+     * `device-env.json` path. Defaults to
+     * `<cwd>/test-results/device-env.json`. Registered at install time
+     * so the sync `readCachedDeviceInfoSync` helper used by
+     * registration-time precondition wrappers resolves consistently.
+     */
+    deviceEnvFile?: string;
+    /**
+     * `test-results/` directory. Enables the artifact streams
+     * (`device.log` sink + `failures/` bundles) and is exposed to
+     * `DeviceTestEnvironment` via `DEVICE_ENV_GLOBAL_KEY.TEST_RESULTS_DIR`.
+     */
+    testResultsDir?: string;
+    /**
+     * Opt-out for per-failure bundle capture. The `device.log` sink
+     * stays active regardless; this only gates the failure bundle pipeline.
+     */
+    captureFailureBundles?: boolean;
+    /**
+     * Crash-recovery policy. When enabled, the next `beforeEach` after
+     * a failure blocks on `waitForDeviceOnline` and clears the health
+     * flag on success (paired with `jest.retryTimes`). Requires
+     * `client`; silently demoted to disabled otherwise.
+     */
+    deviceRecovery?: DeviceRecoveryOptions | false;
+}
+
+export interface DeviceRecoveryOptions {
+    /** Master switch; defaults to `true` when `client` is provided. */
+    enabled?: boolean;
+    /** Per-test retry budget; 0 disables retries. */
+    retryTimes?: number;
+    /** Recovery `waitForDeviceOnline` budget. */
+    waitForOnlineTimeoutMs?: number;
+    /** Recovery probe interval. */
+    pollIntervalMs?: number;
+}
+
+/**
+ * Tag a hook callback with a stable name and register via `beforeAll`.
+ * Tests look up the captured callback by `Function.prototype.name` so a
+ * future hook addition cannot silently break index-pinned assertions.
+ */
+function namedBeforeAll(name: string, fn: () => unknown): void {
+    Object.defineProperty(fn, "name", { value: name, configurable: true });
+    beforeAll(fn);
+}
+
+/** Symmetric counterpart to `namedBeforeAll` for `afterAll` hooks. */
+function namedAfterAll(name: string, fn: () => unknown): void {
+    Object.defineProperty(fn, "name", { value: name, configurable: true });
+    afterAll(fn);
+}
+
+/** Stable hook-name registry for test-side `findBeforeAllByName` lookups. */
+export const HOOK_NAMES = {
+    DIFF_ROOT: "deviceTestHooks:diffRoot",
+    DEVICE_INFO_CACHE: "deviceTestHooks:deviceInfoCache",
+    LOG_SESSION_ATTACH: "deviceTestHooks:logSessionAttach",
+    LOG_SESSION_DETACH: "deviceTestHooks:logSessionDetach"
+} as const;
+
+/**
+ * Module-level latch that flips on the first successful
+ * `installDeviceTestHooks` call. A second call WITHIN THE SAME
+ * MODULE INSTANCE would double-register `beforeAll` / `beforeEach` /
+ * `afterAll` hooks AND re-issue `jest.retryTimes`, doubling the
+ * per-test retry budget. The first symptom is mysterious "this
+ * test ran four times" reports; the second is doubled log
+ * subscribes leaking memory.
+ *
+ * IMPORTANT — scope is per-test-file, NOT per-Node-process:
+ *
+ *   Jest creates a fresh module registry for every test file, even
+ *   under `--runInBand`. `setupFilesAfterEnv` re-evaluates the setup
+ *   script for each file, which re-imports this module → `HAS_INSTALLED`
+ *   starts as `false` on every file. That is intentional: every test
+ *   file legitimately needs its own `beforeAll(ensureLogSession)`
+ *   because Jest's `beforeAll` is file-scoped.
+ *
+ *   What this latch DOES protect against, then, is a duplicate
+ *   registration WITHIN THE SAME FILE — almost always a misconfigured
+ *   `setupFilesAfterEnv` array that lists the setup script twice, or
+ *   a downstream consumer that imports + calls `installDeviceTestHooks`
+ *   in addition to the standard setup file.
+ *
+ * Intentional design choices:
+ *   - Warn-and-no-op (not throw): identical observable behaviour
+ *     keeps CI green during the first run while the operator
+ *     investigates the duplicate registration.
+ *   - `__resetForTests` exists ONLY for the package's own unit
+ *     tests; production code MUST NOT touch it.
+ */
+let HAS_INSTALLED = false;
+
+/**
+ * Test-only: clear the install latch so a unit test can call
+ * `installDeviceTestHooks` again and observe its hook registrations.
+ * Underscored to discourage accidental import in production.
+ */
+export function __resetInstallDeviceTestHooksForTests(): void {
+    HAS_INSTALLED = false;
+}
+
+/**
+ * Registers per-worker Jest hooks. Must be called from
+ * `setupFilesAfterEnv` so Jest's lifecycle globals are in scope.
+ *
+ * Install-time (synchronous): `setBaselineRoot` / `setDeviceEnvFile` /
+ * `setActiveClient` (registration-time wrappers read these from
+ * top-level test code, before `beforeAll` fires); `TEST_RESULTS_DIR` /
+ * `CAPTURE_ENABLED` globals (read by `DeviceTestEnvironment`); and
+ * `jest.retryTimes(...)` when recovery is enabled.
+ *
+ * Hooks: `beforeAll` for diff-root, log-session attach (subscribes the
+ * `device.log` sink BEFORE `ensureLogSession` so no replay line is
+ * dropped); `beforeEach` cascade guard (sync without recovery, async
+ * `waitForDeviceOnline` with); `afterAll` log-session detach (unsubs
+ * sink first, then `disposeLogSession` — does NOT call `/logs/stop`,
+ * which `createGlobalTeardown` owns); `afterEach` no-op (per-test
+ * failure artifacts are owned by `DeviceTestEnvironment.handleTestEvent`).
+ */
+export function installDeviceTestHooks(opts: InstallDeviceTestHooksOptions = {}): void {
+    if (HAS_INSTALLED) {
+        // Loud no-op: see HAS_INSTALLED comment above for rationale.
+        // Set RK_ALLOW_REINSTALL_HOOKS=1 only when intentionally
+        // exercising hook registration twice (e.g. test harness).
+        if (process.env.RK_ALLOW_REINSTALL_HOOKS !== "1") {
+            console.warn(
+                "[device-test-client] installDeviceTestHooks() called more than once in the same Node process. " +
+                    "Ignoring the second call to avoid double-registering Jest hooks (which would double the per-test " +
+                    "retry budget and leak duplicate log subscribers). Check that `setupFilesAfterEnv` lists this " +
+                    "package's setup file only once. Set RK_ALLOW_REINSTALL_HOOKS=1 to bypass."
+            );
+            return;
+        }
+    }
+    HAS_INSTALLED = true;
+    const startLogSession = opts.startLogSession !== false;
+    const captureFailureBundles = opts.captureFailureBundles !== false;
+    const recovery = resolveRecoveryConfig(opts);
+
+    // Synchronous install-time registration: registration-time wrappers
+    // (`itOnDevice` / `describeOnDevice`) read these from top-level test
+    // code, which Jest evaluates BEFORE `beforeAll` fires.
+    if (opts.baselineRoot !== undefined) {
+        setBaselineRoot(opts.baselineRoot);
+    }
+    if (opts.deviceEnvFile !== undefined) {
+        setDeviceEnvFile(opts.deviceEnvFile);
+    }
+    if (opts.client) {
+        setActiveClient(opts.client);
+    }
+
+    // No `beforeAll(resetDeviceHealth)`: the recovery `beforeEach`
+    // below has the only correct cross-suite semantics (probe before
+    // reset). A `beforeAll` reset would either bypass the probe or
+    // mask the operator signal.
+
+    // Diff-root in its own `beforeAll` so screenshot-only suites get it
+    // even without a log-session client.
+    if (opts.diffRoot !== undefined) {
+        const diffRoot = opts.diffRoot;
+        namedBeforeAll(HOOK_NAMES.DIFF_ROOT, () => {
+            setScreenshotDiffRoot(diffRoot);
+        });
+    }
+
+    if (opts.client) {
+        const client = opts.client;
+        namedBeforeAll(HOOK_NAMES.DEVICE_INFO_CACHE, async () => {
+            if (!client.cachedDeviceInfo()) {
+                await client.queryDeviceInfo();
+            }
+        });
+    }
+
+    // Expose `testResultsDir` to `DeviceTestEnvironment` via globals;
+    // env reads at `teardown`, so install-time write is visible in time.
+    if (captureFailureBundles && opts.testResultsDir !== undefined) {
+        const testResultsDir = opts.testResultsDir;
+        (globalThis as Record<string, unknown>)[DEVICE_ENV_GLOBAL_KEY.TEST_RESULTS_DIR] = testResultsDir;
+    }
+
+    // Set synchronously so the first `test_fn_failure` event already
+    // observes the final value.
+    (globalThis as Record<string, unknown>)[DEVICE_ENV_GLOBAL_KEY.CAPTURE_ENABLED] = captureFailureBundles;
+
+    if (startLogSession && opts.client) {
+        const client = opts.client;
+        // Closure-scoped so multiple `installDeviceTestHooks` calls
+        // with different configs don't share state.
+        let sink: DeviceLogSink | null = null;
+        let unsubscribe: (() => void) | null = null;
+
+        namedBeforeAll(HOOK_NAMES.LOG_SESSION_ATTACH, async () => {
+            // Order matters: subscribe BEFORE `ensureLogSession()` so the
+            // replay batch and any live lines land in `device.log`. The
+            // buffer is constructed eagerly so `client.logBuffer()` is
+            // safe before `ensureStarted()`.
+            if (opts.testResultsDir !== undefined) {
+                try {
+                    sink = openDeviceLogSink(opts.testResultsDir, client.deviceIp);
+                    unsubscribe = attachToBuffer(sink, client.logBuffer());
+                    (globalThis as Record<string, unknown>)[DEVICE_ENV_GLOBAL_KEY.LOG_SINK] = sink;
+                } catch (err) {
+                    // Non-fatal: CI loses `device.log` for this run but
+                    // the suite still proceeds.
+                    console.warn(
+                        `[device-test-client] device.log sink failed to open: ${(err as Error).message}. ` +
+                            `Run artifacts will be incomplete.`
+                    );
+                }
+            }
+
+            try {
+                await client.ensureLogSession();
+            } catch (err) {
+                // Non-fatal: the first log-assertion call retries and
+                // surfaces the same error with full context.
+                console.warn(
+                    `[device-test-client] ensureLogSession() failed in beforeAll: ${(err as Error).message}. ` +
+                        `Log assertions will retry on first call.`
+                );
+            }
+        });
+
+        namedAfterAll(HOOK_NAMES.LOG_SESSION_DETACH, async () => {
+            // Unsubscribe FIRST so in-flight appends don't write to a
+            // stream that's about to flush.
+            if (unsubscribe) {
+                try {
+                    unsubscribe();
+                } catch {
+                    // best-effort
+                }
+                unsubscribe = null;
+            }
+            if (sink) {
+                try {
+                    await sink.close();
+                } catch {
+                    // best-effort
+                }
+                sink = null;
+            }
+            try {
+                client.disposeLogSession();
+            } catch {
+                // best-effort
+            }
+        });
+    }
+
+    // Synchronous so tests declared in the same `setupFilesAfterEnv`
+    // pass observe the budget. `jest` may be undefined under ts-jest
+    // unit-tests of this module — guard.
+    if (
+        recovery.enabled &&
+        recovery.retryTimes > 0 &&
+        typeof jest !== "undefined" &&
+        typeof jest.retryTimes === "function"
+    ) {
+        // `logErrorsBeforeRetry: true` distinguishes "flaky" from
+        // "genuinely broken" by surfacing per-attempt errors.
+        jest.retryTimes(recovery.retryTimes, { logErrorsBeforeRetry: true });
+    }
+
+    // Recovery OFF keeps `beforeEach` sync so unit tests that invoke
+    // the captured hook directly observe throw-on-sync behaviour.
+    if (recovery.enabled && recovery.client) {
+        beforeEach(async () => {
+            // FATAL latch is checked FIRST and unconditionally — before the
+            // soft-health early-return below. Jest gives every test FILE a
+            // fresh module registry (even under `--runInBand`), so the
+            // module-local `deviceHealthy` resets to `true` at the start of
+            // each file; gating on `isDeviceHealthy()` first would
+            // early-return on that fresh-file path and never consult the
+            // latch. `isDeviceFatal()` rehydrates from the on-disk sentinel
+            // (see health.ts), the only state that survives the reset, so a
+            // wedge proved by an earlier file aborts this file's tests
+            // immediately instead of probing + retrying a VM that can never
+            // foreground a channel. A fatally-wedged VM still answers
+            // `/query/device-info`, so the liveness probe below would
+            // FALSELY "recover" it — recovery is skipped by design and the
+            // instance must be recycled at the lease/runner layer.
+            if (isDeviceFatal()) {
+                const reason = getFatalReason() ?? getUnhealthyReason() ?? "unknown";
+                throw new DeviceUnhealthyError(
+                    `Aborting test: device is fatally wedged — ${reason}. ` +
+                        `It answers ECP/installer liveness probes but will not foreground a ` +
+                        `sideloaded channel, so device recovery is skipped (it cannot help). ` +
+                        `The device host must be recycled. Remaining tests in this worker ` +
+                        `abort-fast. Per-failure diagnostics are written to ` +
+                        `test-results/failures/<sanitised-test-path>/ — the FIRST failure in the ` +
+                        `bundle carries the root cause.`,
+                    reason
+                );
+            }
+            if (isDeviceHealthy()) return;
+            const reason = getUnhealthyReason() ?? "unknown";
+            // If `/query/device-info` answers, clear the flag and let
+            // `jest.retryTimes` re-execute the crashing test.
+            const waitResult = await tryWaitForDeviceOnline(recovery);
+            if (waitResult.ok) {
+                console.warn(
+                    `[device-test-client] Device recovered after "${reason}" ` +
+                        `(attempts=${waitResult.attempts}, elapsedMs=${waitResult.elapsedMs}). ` +
+                        `Clearing unhealthy flag and continuing.`
+                );
+                resetDeviceHealth();
+                return;
+            }
+            // Fall through to the cascade error, but enrich it so the
+            // reviewer sees WHY recovery didn't help.
+            throw new DeviceUnhealthyError(
+                `Aborting test: device marked unhealthy — ${reason}. ` +
+                    `Recovery attempted via waitForDeviceOnline and failed ` +
+                    `after ${waitResult.elapsedMs}ms (${waitResult.attempts} probes): ` +
+                    `${waitResult.errorMessage}. Remaining tests in this worker will ` +
+                    `abort-fast. Per-failure diagnostics are written to ` +
+                    `test-results/failures/<sanitised-test-path>/ — the ` +
+                    `FIRST failure in the bundle carries the root cause.`,
+                reason
+            );
+        });
+    } else {
+        beforeEach(() => {
+            // Cross-file FATAL latch first (see the recovery branch above
+            // for why order matters): `isDeviceFatal()` rehydrates from the
+            // on-disk sentinel, so a wedge proved by an earlier test file
+            // aborts this fresh file even though its module-local
+            // `deviceHealthy` reset to `true`. The dedicated message names
+            // the wedge so triage doesn't mistake it for an ordinary
+            // cascade.
+            if (isDeviceFatal()) {
+                const fatalReason = getFatalReason() ?? getUnhealthyReason() ?? "unknown";
+                throw new DeviceUnhealthyError(
+                    `Aborting test: device is fatally wedged — ${fatalReason}. ` +
+                        `It answers ECP/installer liveness probes but will not foreground a ` +
+                        `sideloaded channel; retrying cannot recover it. The device host ` +
+                        `must be recycled. Remaining tests in this worker abort-fast. Per-failure ` +
+                        `diagnostics are written to test-results/failures/<sanitised-test-path>/ ` +
+                        `— the FIRST failure in the bundle carries the root cause.`,
+                    fatalReason
+                );
+            }
+            if (isDeviceHealthy()) return;
+            // The cascade error's stack points HERE, not at the test
+            // that broke the device — surface the per-failure bundle
+            // path inline so reviewers find the root-cause artifacts.
+            const reason = getUnhealthyReason() ?? "unknown";
+            throw new DeviceUnhealthyError(
+                `Aborting test: device marked unhealthy — ${reason}. ` +
+                    `Remaining tests in this worker will also abort-fast to ` +
+                    `prevent cascading failures. Per-failure diagnostics ` +
+                    `(screenshot, dom-tree, recent logs, error) are written to ` +
+                    `test-results/failures/<sanitised-test-path>/ — the ` +
+                    `FIRST failure in the bundle carries the root cause.`,
+                reason
+            );
+        });
+    }
+
+    afterEach(() => {
+        // No-op anchor. Per-test failure artifacts are written by
+        // `DeviceTestEnvironment.handleTestEvent` since `afterEach`
+        // cannot observe failure state without a side-channel flag.
+    });
+}
+
+/** Internal: fully-resolved recovery config. */
+interface ResolvedRecoveryConfig {
+    enabled: boolean;
+    retryTimes: number;
+    waitForOnlineTimeoutMs: number;
+    pollIntervalMs: number;
+    client?: RkClient;
+}
+
+/**
+ * Normalise `deviceRecovery` into a concrete config. Opt-in: defaults
+ * OFF (legacy fast-fail cascade). "Enabled but no client" silently
+ * demotes to disabled rather than throwing — the client is often
+ * wired in later in the same `jest-setup.ts`.
+ */
+function resolveRecoveryConfig(opts: InstallDeviceTestHooksOptions): ResolvedRecoveryConfig {
+    const client = opts.client;
+    const raw = opts.deviceRecovery;
+    if (raw === false || raw === undefined) {
+        return {
+            enabled: false,
+            retryTimes: 0,
+            waitForOnlineTimeoutMs: DEVICE_ONLINE_DEFAULT_TIMEOUT_MS,
+            pollIntervalMs: DEVICE_ONLINE_POLL_INTERVAL_MS,
+            client
+        };
+    }
+    const enabledRequested = raw.enabled ?? true;
+    const enabled = enabledRequested && client !== undefined;
+    return {
+        enabled,
+        retryTimes: raw.retryTimes ?? DEVICE_RECOVERY_DEFAULT_RETRIES,
+        waitForOnlineTimeoutMs: raw.waitForOnlineTimeoutMs ?? DEVICE_ONLINE_DEFAULT_TIMEOUT_MS,
+        pollIntervalMs: raw.pollIntervalMs ?? DEVICE_ONLINE_POLL_INTERVAL_MS,
+        client
+    };
+}
+
+interface RecoveryAttemptResult {
+    ok: boolean;
+    attempts: number;
+    elapsedMs: number;
+    errorMessage: string;
+}
+
+/**
+ * Wrap `waitForDeviceOnline` with a never-throw result shape so a
+ * recovery-layer bug cannot evict the original cascade message.
+ */
+async function tryWaitForDeviceOnline(cfg: ResolvedRecoveryConfig): Promise<RecoveryAttemptResult> {
+    const startedAt = Date.now();
+    if (!cfg.client) {
+        return { ok: false, attempts: 0, elapsedMs: 0, errorMessage: "no client configured" };
+    }
+    try {
+        await cfg.client.waitForDeviceOnline({
+            timeoutMs: cfg.waitForOnlineTimeoutMs,
+            intervalMs: cfg.pollIntervalMs
+        });
+        return { ok: true, attempts: 1, elapsedMs: Date.now() - startedAt, errorMessage: "" };
+    } catch (err) {
+        const attempts =
+            typeof err === "object" && err && "context" in err
+                ? ((err as { context?: { attempts?: number } }).context?.attempts ?? 0)
+                : 0;
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            ok: false,
+            attempts,
+            elapsedMs: Date.now() - startedAt,
+            errorMessage: message
+        };
+    }
+}

package/src/jest/jest-setup.ts

@@ -0,0 +1,53 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+/**
+ * Barrel re-exports — `jest-setup.ts` was historically the single
+ * module hosting every Jest orchestration symbol shipped by this
+ * package. The implementations now live in cohesive leaf modules:
+ *
+ *   - `artifacts.ts`        — `cleanArtifacts`, `assertSupportedVideoMode`,
+ *                             `writeDeviceEnvSnapshot`, `logDeviceDiagnostic`.
+ *   - `lease-provisioning.ts` — `readLeaseProvisioning` (lease-recorded
+ *                             provenance folded into `device-env.json`).
+ *   - `global-setup.ts`     — `createGlobalSetup`, `GlobalSetupOptions`.
+ *   - `global-teardown.ts`  — `createGlobalTeardown`, `CreateGlobalTeardownOptions`.
+ *   - `install-hooks.ts`    — `installDeviceTestHooks`, `InstallDeviceTestHooksOptions`.
+ *   - `baseline-env-guard.ts` — `assertBaselineUpdatesAllowed`, `isCi`.
+ *   - `telemetry.ts`        — device-lease log line + JUnit `<properties>` writer.
+ *
+ * This file preserves the original import surface so existing callers
+ * (`device-tests/setup.ts`, `__tests__/jest-setup.test.ts`, and any
+ * downstream consumer) continue to work unchanged. New code should
+ * import directly from the leaf modules above.
+ */
+
+export { assertBaselineUpdatesAllowed, isCi } from "../assertions/baseline-env-guard";
+export { assertSupportedVideoMode, cleanArtifacts, logDeviceDiagnostic, writeDeviceEnvSnapshot } from "./artifacts";
+export type { DeviceEnvSnapshot } from "./artifacts";
+export { readLeaseProvisioning } from "../device/lease-provisioning";
+export type { LeaseProvisioning } from "../device/lease-provisioning";
+export { createGlobalSetup } from "./global-setup";
+export type { GlobalSetupOptions } from "./global-setup";
+export { createGlobalTeardown } from "./global-teardown";
+export type { CreateGlobalTeardownOptions } from "./global-teardown";
+export { installDeviceTestHooks } from "./install-hooks";
+export type { InstallDeviceTestHooksOptions } from "./install-hooks";
+export {
+    buildAcquireEvent,
+    buildJUnitTelemetryProperties,
+    buildReleaseEvent,
+    DEFAULT_PROVIDER_KIND,
+    DEFAULT_SHARD_NAME,
+    DEVICE_LEASE_LOG_PREFIX,
+    emitDeviceLeaseLog,
+    formatDeviceLeaseLog,
+    resolveTelemetry,
+    writeJUnitTelemetryPropertiesFile
+} from "./telemetry";
+export type {
+    DeviceLeaseAcquireEvent,
+    DeviceLeaseEvent,
+    DeviceLeaseReleaseEvent,
+    DeviceLeaseTelemetry,
+    JUnitTelemetryProperties
+} from "./telemetry";