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

package/src/jest/global-setup.ts

@@ -0,0 +1,133 @@
+// 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);
+
+        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}`);
+        }
+    };
+}