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

package/src/jest/failure-artifacts.ts

@@ -0,0 +1,169 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+/**
+ * Pure-fs helpers for writing per-failure bundles to
+ * `<root>/failures/<sanitized>/`. Each sub-write is independent
+ * (best-effort): a failing `screenshot.png` write doesn't block
+ * the others. Leaf module — no `client.ts`/`assertions.ts` imports.
+ */
+
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { FAILURE_ARTIFACT_FILE, FAILURES_DIR } from "../constants";
+import type { LogEntry } from "../logs/log-buffer";
+
+/**
+ * Join `[describe..., testName]` into a single filesystem-safe
+ * directory name. Each part: non-`[A-Za-z0-9._-]` → `-`, runs
+ * collapsed, edges trimmed. Parts joined with `--` so reviewers
+ * can recover describe boundaries by eye. Falls back to
+ * `"unnamed-test"` for empty input.
+ */
+export function sanitizeTestPath(parts: readonly string[]): string {
+    const cleaned = parts.map(sanitizePart).filter(p => p.length > 0);
+    if (cleaned.length === 0) return "unnamed-test";
+    return cleaned.join("--");
+}
+
+function sanitizePart(s: string): string {
+    return s
+        .replace(/[^A-Za-z0-9._-]+/g, "-")
+        .replace(/-+/g, "-")
+        .replace(/^-+|-+$/g, "");
+}
+
+/** Create `<testResultsDir>/failures/` and return its absolute path. */
+export function ensureFailuresDir(testResultsDir: string): string {
+    const dir = join(testResultsDir, FAILURES_DIR);
+    mkdirSync(dir, { recursive: true });
+    return dir;
+}
+
+/**
+ * Inputs for a single failure bundle. Every field may be null —
+ * a client unavailable at teardown still gets an `error.txt`.
+ */
+export interface FailureBundleInput {
+    screenshot: Buffer | null;
+    domTree: unknown;
+    /** Empty array is valid and writes an empty `recent-logs.txt`. */
+    recentLogs: ReadonlyArray<Pick<LogEntry, "seq" | "line">> | null;
+    /** `LogStreamHealth` snapshot for transport-leg attribution. */
+    streamHealth?: Record<string, unknown> | null;
+    error: unknown;
+}
+
+/**
+ * Per-bundle write outcome. Caller surfaces a single warn instead
+ * of letting per-write errors propagate into Jest teardown.
+ */
+export interface FailureBundleWriteResult {
+    written: string[];
+    failed: Array<{ artifact: string; cause: Error }>;
+}
+
+/**
+ * Write every available artifact to `dir`. Each sub-write is
+ * independently try/caught (best-effort). `error.txt` is always
+ * attempted — a bundle with only `error.txt` is still useful.
+ */
+export function writeFailureBundle(dir: string, input: FailureBundleInput): FailureBundleWriteResult {
+    const written: string[] = [];
+    const failed: Array<{ artifact: string; cause: Error }> = [];
+
+    try {
+        mkdirSync(dir, { recursive: true });
+    } catch (err) {
+        // mkdir failure → all artifacts fail uniformly; one entry.
+        failed.push({ artifact: "mkdir", cause: toError(err) });
+        return { written, failed };
+    }
+
+    if (input.screenshot) {
+        const name = FAILURE_ARTIFACT_FILE.SCREENSHOT;
+        try {
+            writeFileSync(join(dir, name), input.screenshot);
+            written.push(name);
+        } catch (err) {
+            failed.push({ artifact: "screenshot", cause: toError(err) });
+        }
+    }
+
+    if (input.domTree !== null && input.domTree !== undefined) {
+        const name = FAILURE_ARTIFACT_FILE.DOM_TREE;
+        try {
+            const body = `${JSON.stringify(input.domTree, null, 2)}\n`;
+            writeFileSync(join(dir, name), body, "utf8");
+            written.push(name);
+        } catch (err) {
+            failed.push({ artifact: "dom-tree", cause: toError(err) });
+        }
+    }
+
+    if (input.recentLogs !== null) {
+        const name = FAILURE_ARTIFACT_FILE.RECENT_LOGS;
+        try {
+            const body = formatRecentLogs(input.recentLogs);
+            writeFileSync(join(dir, name), body, "utf8");
+            written.push(name);
+        } catch (err) {
+            failed.push({ artifact: "recent-logs", cause: toError(err) });
+        }
+    }
+
+    if (input.streamHealth !== null && input.streamHealth !== undefined) {
+        const name = FAILURE_ARTIFACT_FILE.STREAM_HEALTH;
+        try {
+            const body = `${JSON.stringify(input.streamHealth, null, 2)}\n`;
+            writeFileSync(join(dir, name), body, "utf8");
+            written.push(name);
+        } catch (err) {
+            failed.push({ artifact: "stream-health", cause: toError(err) });
+        }
+    }
+
+    const errorName = FAILURE_ARTIFACT_FILE.ERROR;
+    try {
+        writeFileSync(join(dir, errorName), `${stringifyError(input.error)}\n`, "utf8");
+        written.push(errorName);
+    } catch (err) {
+        failed.push({ artifact: "error", cause: toError(err) });
+    }
+
+    return { written, failed };
+}
+
+function formatRecentLogs(logs: ReadonlyArray<Pick<LogEntry, "seq" | "line">>): string {
+    if (logs.length === 0) return "";
+    return `${logs.map(e => `${e.seq}\t${e.line}`).join("\n")}\n`;
+}
+
+/**
+ * Render `err` for `error.txt`. Duck-types on `.stack`/`.message`
+ * because Jest VM-sandbox errors don't pass `instanceof Error`
+ * across the realm boundary; `JSON.stringify` would omit `.stack`.
+ * Precedence: stack > name: message > string > JSON > String().
+ */
+function stringifyError(err: unknown): string {
+    if (typeof err === "string") return err;
+    if (err !== null && typeof err === "object") {
+        const e = err as { stack?: unknown; message?: unknown; name?: unknown };
+        if (typeof e.stack === "string" && e.stack.length > 0) {
+            return e.stack;
+        }
+        if (typeof e.message === "string" && e.message.length > 0) {
+            const name = typeof e.name === "string" && e.name.length > 0 ? e.name : "Error";
+            return `${name}: ${e.message}`;
+        }
+    }
+    try {
+        return JSON.stringify(err, null, 2);
+    } catch {
+        return String(err);
+    }
+}
+
+function toError(err: unknown): Error {
+    return err instanceof Error ? err : new Error(String(err));
+}

package/src/jest/global-setup.ts

@@ -0,0 +1,137 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+/**
+ * `createGlobalSetup` — factory for Jest's `globalSetup` config.
+ * Runs once per suite, in its own process, before any worker
+ * imports a test file. `jest-setup.ts` re-exports for API
+ * compatibility.
+ */
+
+import { join } from "node:path";
+
+import { assertBaselineUpdatesAllowed } from "../assertions/baseline-env-guard";
+import { createDefaultClient } from "../client/factory";
+import { ARTIFACT_FILE, ENV_VAR, ROKU_LOG_PORT } from "../constants";
+import { persistDeviceIp, resolveActiveDeviceIp } from "../device/device-resolver";
+import { readLeaseProvisioning } from "../device/lease-provisioning";
+import {
+    assertSupportedVideoMode,
+    cleanArtifacts,
+    logDeviceDiagnostic,
+    trimTrailingSlash,
+    writeDeviceEnvSnapshot
+} from "./artifacts";
+import {
+    buildAcquireEvent,
+    emitDeviceLeaseLog,
+    resolveTelemetry,
+    writeJUnitTelemetryPropertiesFile
+} from "./telemetry";
+
+export interface GlobalSetupOptions {
+    /** Absolute path to the consumer's `test-results/` directory. */
+    testResultsDir: string;
+}
+
+/**
+ * ECP budget for the startup readiness gate, deliberately tighter than
+ * the client-wide `DEVICE_ONLINE_DEFAULT_TIMEOUT_MS` (which is sized for
+ * crash/reboot recovery mid-run). By the time `globalSetup` runs the
+ * lease layer has already waited for ECP, so a device that still isn't
+ * answering is misconfigured or powered off — failing in 30s keeps that
+ * diagnosis fast for local runs instead of hanging for minutes.
+ */
+const STARTUP_ECP_TIMEOUT_MS = 30_000;
+
+/**
+ * Build the `globalSetup` function:
+ *   1. Reject `UPDATE_BASELINES=1` in CI.
+ *   2. Clean stale artifacts (keeps `.gitkeep`).
+ *   3. Resolve device IP and persist `test-results/.device-ip`
+ *      (workers read synchronously). Also exports `RK_DEVICE_IP`.
+ *   4. Block until the device answers ECP *and* accepts TCP on the
+ *      sideload installer port; validate `videoMode`.
+ *   5. Persist `device-env.json` — the ECP snapshot plus the lease's
+ *      provisioning provenance; workers seed cache from it.
+ *   6. Log one-line diagnostic.
+ *   7. Reset + start `rk server` log session (best-effort; a
+ *      missing daemon is logged not thrown).
+ *   8. Emit the `[device-lease]` acquire log line and write the
+ *      JUnit per-`<testcase>` properties file (`device-id`,
+ *      `shard-name`, `providerKind`). Done LAST so a failure in
+ *      the device-readiness path (steps 3–7) short-circuits before
+ *      we publish a "we successfully took ownership" telemetry
+ *      record. The matching release line is emitted by
+ *      `globalTeardown`.
+ */
+export function createGlobalSetup(opts: GlobalSetupOptions): () => Promise<void> {
+    return async function globalSetup(): Promise<void> {
+        assertBaselineUpdatesAllowed();
+        cleanArtifacts(opts.testResultsDir);
+
+        // A run through a deployment driver has no physical device to
+        // resolve, probe, or lease; each worker builds its own host.
+        if (process.env[ENV_VAR.RK_DEVICE_DRIVER_MODULE]) return;
+
+        const ip = await resolveActiveDeviceIp();
+        await persistDeviceIp(opts.testResultsDir, ip);
+        process.env[ENV_VAR.RK_DEVICE_IP] = ip;
+
+        const client = createDefaultClient({ deviceIp: ip });
+        // Gate on ECP *and* the sideload installer, not ECP alone. ECP is
+        // the first port Roku OS brings up; the installer trails it, so a
+        // single `/query/device-info` says nothing about whether the very
+        // first `plugin_install` of the run will be accepted. Paying the
+        // wait here makes the cost visible and shared, instead of dumping
+        // it on whichever suite happens to be scheduled first.
+        const info = await client.waitForDeviceFullyReady({ ecpTimeoutMs: STARTUP_ECP_TIMEOUT_MS });
+        assertSupportedVideoMode(info.videoMode);
+        const provisioning = await readLeaseProvisioning();
+        writeDeviceEnvSnapshot(opts.testResultsDir, info, provisioning);
+        logDeviceDiagnostic(info, provisioning);
+
+        await resetAndStartLogSession(client.getServerUrl(), ip);
+
+        // Telemetry must come AFTER device readiness so we never
+        // publish an acquire record for a run that is about to
+        // throw at startup (skewed wall-time + device-utilization
+        // baselines downstream).
+        const telemetry = resolveTelemetry({ deviceId: ip });
+        writeJUnitTelemetryPropertiesFile(join(opts.testResultsDir, ARTIFACT_FILE.JUNIT_CASE_PROPERTIES), telemetry);
+        emitDeviceLeaseLog(buildAcquireEvent(telemetry));
+    };
+}
+
+/**
+ * `/logs/stop` (idempotent) + `/logs/start` so every worker SSE
+ * subscriber sees an identical starting buffer. Swallows transport
+ * errors so suites without log assertions still run.
+ */
+async function resetAndStartLogSession(serverUrl: string, deviceIp: string): Promise<void> {
+    const stopUrl = `${trimTrailingSlash(serverUrl)}/logs/stop`;
+    const startUrl = `${trimTrailingSlash(serverUrl)}/logs/start`;
+    const body = JSON.stringify({ device: deviceIp, port: ROKU_LOG_PORT });
+    const jsonHeaders = { "Content-Type": "application/json" };
+    try {
+        // Idempotent stop. Only warn on transport failures so a
+        // misconfigured daemon shows up in CI output.
+        await fetch(stopUrl, { method: "POST", headers: jsonHeaders, body }).catch(err => {
+            console.warn(`[device-test-client] /logs/stop failed (ignored): ${err.message}`);
+        });
+        const res = await fetch(startUrl, {
+            method: "POST",
+            headers: jsonHeaders,
+            body
+        });
+        if (!res.ok && res.status !== 400) {
+            console.warn(
+                `[device-test-client] /logs/start returned ${res.status} — log assertions may not work this run.`
+            );
+        }
+    } catch (err) {
+        console.warn(
+            `[device-test-client] rk server unreachable at ${serverUrl} (${(err as Error).message}); ` +
+                `log assertions will fail fast on first use.`
+        );
+    }
+}

package/src/jest/global-teardown.ts

@@ -0,0 +1,132 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+/**
+ * `createGlobalTeardown` — factory for the function a consumer passes
+ * to Jest's `globalTeardown` config key.
+ *
+ * Extracted from `jest-setup.ts` so the `globalTeardown` wiring lives
+ * alongside `global-setup.ts` as a mirror pair. `jest-setup.ts`
+ * re-exports `createGlobalTeardown` and `CreateGlobalTeardownOptions`
+ * for API compatibility.
+ */
+
+import { ECP_PORT } from "@roku-sdk/tooling/src/device-test-helpers";
+
+import { resolveServerUrl } from "../client/server-url";
+import { ENV_VAR, ROKU_LOG_PORT } from "../constants";
+import { trimTrailingSlash } from "./artifacts";
+import { buildReleaseEvent, emitDeviceLeaseLog, resolveTelemetry } from "./telemetry";
+
+/**
+ * Options for `createGlobalTeardown`.
+ */
+export interface CreateGlobalTeardownOptions {
+    /** Override the `rk server` URL (defaults to the shared resolver). */
+    serverUrl?: string;
+    /** Override the device IP (defaults to `RK_DEVICE_IP`). */
+    deviceIp?: string;
+    /**
+     * Whether to send ECP `/keypress/Home` to the device at the end of
+     * the run so the sideloaded dev channel exits to the home screen
+     * instead of being left on the last test's scene.
+     *
+     * Defaults to `true` because leaving the channel active between
+     * runs is an almost-universal papercut: the next `buildAndDeploy`
+     * sideloads over a live channel (slightly slower install + noisier
+     * logs), the device's screen burns the last fixture until the user
+     * intervenes, and if the last test tripped an uncaught effect the
+     * channel keeps emitting log lines after the Jest process exits.
+     * Best-effort — teardown never throws on transport failure, the
+     * same contract as the `/logs/stop` POST below.
+     *
+     * Set to `false` if you explicitly want to inspect the last
+     * scene on the device after the run (e.g. manual screenshot
+     * debugging).
+     */
+    exitToHome?: boolean;
+}
+
+/**
+ * Builds the function passed to Jest's `globalTeardown`. Three jobs:
+ *
+ *   1. Emit the `[device-lease]` release log line (telemetry).
+ *      Done FIRST so the dashboard gets a release record even if
+ *      the best-effort I/O steps below stall on a half-dead
+ *      device and the process is reaped externally.
+ *   2. Send ECP `/keypress/Home` to the device so the sideloaded dev
+ *      channel exits to the home screen. Avoids leaving the last
+ *      test's fixture on-screen between runs. Default-on; opt out
+ *      via `opts.exitToHome = false`. See `CreateGlobalTeardownOptions.exitToHome`
+ *      for the rationale.
+ *   3. Stop the `rk server` log session started in `createGlobalSetup`
+ *      so the daemon's connection to the device is released between
+ *      suites.
+ *
+ * Steps 2 and 3 are best-effort — errors are logged, not thrown.
+ * Teardown must not fail the run (Jest exits non-zero if it does,
+ * masking the real test status).
+ *
+ * Step 2 → 3 order: Home first, then `/logs/stop`. Exiting the
+ * channel while the log tail is still attached lets the
+ * `AppExitInitiate` beacon show up in the session buffer, which is
+ * occasionally useful for post-mortem debugging if a suite fails;
+ * the subsequent `/logs/stop` cleanly releases the SSE regardless.
+ */
+export function createGlobalTeardown(opts: CreateGlobalTeardownOptions = {}): () => Promise<void> {
+    return async function globalTeardown(): Promise<void> {
+        // Shared resolver (see `server-url.ts`) — same precedence as
+        // `RkClient` so the teardown hits the same daemon the worker
+        // talked to during the suite, including the `.roku/
+        // rk-server.json` discovery path.
+        const serverUrl = resolveServerUrl({ serverUrl: opts.serverUrl });
+        const deviceIp = opts.deviceIp ?? process.env[ENV_VAR.RK_DEVICE_IP];
+        // No `deviceIp` ⇒ globalSetup never published an acquire
+        // record (it threw before step 8) ⇒ no symmetric release
+        // record to emit. Skipping keeps the acquire/release pair
+        // invariant for downstream telemetry.
+        if (!deviceIp) return;
+
+        // Emit the release log line FIRST. Best-effort I/O below
+        // (ECP `Home`, `/logs/stop`) can stall on a half-dead
+        // device; emitting first guarantees the dashboard gets a
+        // release record even if those calls hang to their
+        // timeouts and the process is reaped externally. See
+        // `globalSetup` for the symmetric ordering rationale on
+        // the acquire side.
+        emitDeviceLeaseLog(buildReleaseEvent(resolveTelemetry({ deviceId: deviceIp })));
+
+        if (opts.exitToHome !== false) {
+            // Direct ECP — no queue, no retry. The dev channel is
+            // exiting either way; a transient network blip just means
+            // it stays active until the next run's `buildAndDeploy`
+            // replaces it. Short timeout so a dead device never stalls
+            // Jest's exit.
+            const homeUrl = `http://${deviceIp}:${ECP_PORT}/keypress/Home`;
+            try {
+                const controller = new AbortController();
+                const timer = setTimeout(() => controller.abort(), 2_000);
+                try {
+                    await fetch(homeUrl, {
+                        method: "POST",
+                        signal: controller.signal
+                    });
+                } finally {
+                    clearTimeout(timer);
+                }
+            } catch (err) {
+                console.warn(`[device-test-client] globalTeardown: POST ${homeUrl} failed: ${(err as Error).message}`);
+            }
+        }
+
+        const url = `${trimTrailingSlash(serverUrl)}/logs/stop`;
+        try {
+            await fetch(url, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify({ device: deviceIp, port: ROKU_LOG_PORT })
+            });
+        } catch (err) {
+            console.warn(`[device-test-client] globalTeardown: POST ${url} failed: ${(err as Error).message}`);
+        }
+    };
+}