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

package/src/device/device-class.ts

@@ -0,0 +1,57 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+/**
+ * `modelName` → coarse performance tier for precondition gating.
+ * Separate from `DeviceInfo.deviceClass` (which is a form-factor
+ * classifier). Hand-maintained because the model→tier mapping is
+ * not algorithmic. Unknown models → `"unknown"` so preconditions
+ * fail closed.
+ */
+
+export type DeviceClass = "high-end" | "mid-range" | "low-end" | "unknown";
+
+/**
+ * Normalise for table lookup: lowercase, trim, strip `"roku "`
+ * prefix so `"Roku Ultra"` and `"Ultra"` resolve identically.
+ */
+function normalizeModel(modelName: string): string {
+    const lower = modelName.trim().toLowerCase();
+    return lower.startsWith("roku ") ? lower.slice("roku ".length) : lower;
+}
+
+/**
+ * Static `modelName` → tier table. Conservative: prefer `"unknown"`
+ * for new models until they're manually classified.
+ */
+const MODEL_CLASS_TABLE: ReadonlyMap<string, DeviceClass> = new Map([
+    ["express", "low-end"],
+    ["express 4k", "mid-range"],
+    ["express 4k+", "mid-range"],
+    ["streaming stick", "low-end"],
+    ["streaming stick+", "mid-range"],
+    ["streaming stick 4k", "mid-range"],
+    ["streaming stick 4k+", "mid-range"],
+    ["premiere", "mid-range"],
+    ["premiere+", "mid-range"],
+    ["ultra", "high-end"],
+    ["ultra lt", "mid-range"],
+    // Roku TVs keyed by the strings ECP actually reports.
+    ["roku tv", "mid-range"],
+    ["4k roku tv", "mid-range"],
+    ["roku ultra lt", "mid-range"],
+    ["reference rsg-4k", "high-end"],
+    ["reference rsg-hd", "low-end"],
+    ["streambar", "low-end"],
+    ["streambar pro", "mid-range"],
+    ["wireless soundbar", "mid-range"]
+]);
+
+/**
+ * Map `modelName` to a tier. Pure (no I/O, no state).
+ * `"unknown"` for unmapped models so preconditions fail closed.
+ */
+export function getDeviceClass(modelName: string): DeviceClass {
+    if (!modelName) return "unknown";
+    const hit = MODEL_CLASS_TABLE.get(normalizeModel(modelName));
+    return hit ?? "unknown";
+}

package/src/device/device-env-sync.ts

@@ -0,0 +1,58 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+/**
+ * Synchronous `DeviceInfo` accessor backed by
+ * `test-results/device-env.json` (written by `globalSetup`).
+ *
+ * `itOnDevice`/`describeOnDevice` evaluate preconditions at
+ * registration time — before any `beforeAll` has fired, so the
+ * live `RkClient` has no cached info yet. Reading from disk is the
+ * simplest shape that preserves the "one ECP round-trip per suite"
+ * contract.
+ *
+ * Missing file → return null (caller falls back to "register
+ * normally", no skip) so a fresh clone boots cleanly.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { ARTIFACT_FILE } from "../constants";
+import { TEST_RESULTS_DIR_NAME } from "../paths";
+import type { DeviceInfo } from "../types";
+
+// Path resolved lazily from cwd so a `chdir` before hooks still
+// lands correctly. Consumers override via `setDeviceEnvFile()` to
+// anchor on `__dirname` (robust to worker cwd changes).
+let overridePath: string | null = null;
+
+export function setDeviceEnvFile(absPath: string): void {
+    overridePath = absPath;
+}
+
+export function getDeviceEnvFile(): string {
+    return overridePath ?? join(process.cwd(), TEST_RESULTS_DIR_NAME, ARTIFACT_FILE.DEVICE_ENV);
+}
+
+/**
+ * Read and parse `device-env.json`. Returns null when missing or
+ * unparseable so precondition evaluators see "no cache" consistently.
+ * Synchronous because `itOnDevice`/`describeOnDevice` can't await.
+ */
+export function readCachedDeviceInfoSync(): DeviceInfo | null {
+    const file = getDeviceEnvFile();
+    if (!existsSync(file)) return null;
+    try {
+        const raw = readFileSync(file, "utf8");
+        const parsed = JSON.parse(raw) as DeviceInfo;
+        if (!parsed || typeof parsed !== "object") return null;
+        return parsed;
+    } catch {
+        return null;
+    }
+}
+
+/** Test-only reset for the `setDeviceEnvFile` override. */
+export function resetDeviceEnvFileOverride(): void {
+    overridePath = null;
+}

package/src/device/device-resolver-sync.ts

@@ -0,0 +1,43 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+/**
+ * Device IP resolution — sync side (worker-safe).
+ *
+ * Intentionally has no `@roku-sdk/tooling` imports: the tooling's
+ * device-store module is ESM and breaks CommonJS consumers at load
+ * time via `import.meta.url`. Keep this file import-light.
+ */
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { DEVICE_IP_CACHE_FILE, ENV_VAR } from "../constants";
+import { RkClientError } from "../errors";
+
+/**
+ * Return the device IP to use from:
+ *   1. `RK_DEVICE_IP` env var, then
+ *   2. `testResultsDir/.device-ip` written by `globalSetup`.
+ *
+ * Throws `RkClientError(RK_DEVICE_IP_UNRESOLVED)` otherwise.
+ */
+export function resolveDeviceIpSync(testResultsDir?: string): string {
+    const envIp = process.env[ENV_VAR.RK_DEVICE_IP];
+    if (envIp && envIp.length > 0) return envIp;
+
+    if (testResultsDir) {
+        try {
+            const cached = readFileSync(join(testResultsDir, DEVICE_IP_CACHE_FILE), "utf8").trim();
+            if (cached.length > 0) return cached;
+        } catch (err) {
+            const code = (err as NodeJS.ErrnoException).code;
+            if (code !== "ENOENT") throw err;
+        }
+    }
+
+    throw new RkClientError(
+        `Unable to resolve a Roku device IP. Set ${ENV_VAR.RK_DEVICE_IP}=<ip> or ensure ` +
+            `the suite's global-setup has run and written ${DEVICE_IP_CACHE_FILE}.`,
+        "RK_DEVICE_IP_UNRESOLVED"
+    );
+}

package/src/device/device-resolver.ts

@@ -0,0 +1,141 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+/**
+ * Async device IP resolution. Split from the sync resolver so
+ * `createDefaultClient` never transitively loads
+ * `@roku-sdk/tooling`'s ESM `devices-store` (top-level
+ * `import.meta.url`) under CommonJS consumers like ts-jest.
+ *
+ * Flow: `globalSetup` calls `resolveActiveDeviceIp()` and persists
+ * via `persistDeviceIp`; worker processes read the persisted IP
+ * synchronously through `device-resolver-sync.ts`.
+ *
+ * Resolution precedence (later wins on conflict):
+ *   0. (Layer 0) `RK_DEVICE_LEASE_ID` — read the lease file
+ *      `.roku/leases/<id>.json` and use its `ip`. This is the
+ *      canonical CI path for provider-backed pools; the provider writes the
+ *      lease at acquire-time and pins the consumer at boot.
+ *   1. `RK_DEVICE_IP` — partner-side override. Still WINS on
+ *      conflict so existing partner pipelines that pin an IP
+ *      keep working byte-for-byte after this file lands.
+ *   2. `.roku/` active device → first registered device.
+ *
+ * IMPORTANT: `RK_DEVICE_IP` deliberately wins over a lease file.
+ * Rationale:
+ *   - Partner pipelines have set `RK_DEVICE_IP` for years; flipping
+ *     precedence would silently break them when an unrelated lease
+ *     file from a prior interactive `rk device lease acquire` is
+ *     still on disk.
+ *   - The internal CI path always sets `RK_DEVICE_LEASE_ID` AND
+ *     leaves `RK_DEVICE_IP` unset, so the lease-file path "wins"
+ *     in practice without any precedence ambiguity.
+ */
+
+import { promises as fs } from "node:fs";
+import { join } from "node:path";
+
+import { leaseFilePath, readLeaseFile } from "@roku-sdk/tooling/src/device-pool/lease-writer";
+import { loadListMergedDevices } from "@roku-sdk/tooling/src/device-test-helpers";
+
+import { DEVICE_IP_CACHE_FILE, ENV_VAR } from "../constants";
+import { RkClientError } from "../errors";
+
+// `loadListMergedDevices` lives on the tooling side (in
+// `@roku-sdk/tooling/device-test-helpers`) so the deep-require path
+// is owned by the package whose internals it references. Static
+// import of `devices-store` would pull in `get-config.ts` (top-level
+// `import.meta.url`) which is illegal under our CommonJS tsconfig;
+// the helper defers resolution to runtime via `require()`.
+
+export { resolveDeviceIpSync } from "./device-resolver-sync";
+
+/**
+ * Layer 0 lookup: read the lease file the device-pool provider wrote
+ * for this job and return its `ip` if usable.
+ *
+ * Returns `undefined` (not throws) on every recoverable miss — env
+ * unset, lease dir missing, file corrupt — so a higher precedence
+ * layer (`RK_DEVICE_IP`) or a lower one (`.roku/` active) can still
+ * resolve a valid IP. The one fatal case is "env says use lease X
+ * but no other layer has an IP either"; that surfaces at the bottom
+ * of `resolveActiveDeviceIp` as the existing `RK_DEVICE_IP_UNRESOLVED`
+ * error, which already has the actionable remediation steps.
+ *
+ * We deliberately do NOT mutate `.roku/roku-dev-config.json` or
+ * `rk-server` state — the lease file is the single source of truth,
+ * and `rk-server` (when started in a job with `RK_DEVICE_LEASE_ID`
+ * set) reads through the same file directly. This is what makes the
+ * parallel-CI model safe: workspace-singleton state cannot race.
+ */
+async function resolveFromLeaseFile(cwd: string): Promise<string | undefined> {
+    const leaseId = process.env[ENV_VAR.RK_DEVICE_LEASE_ID];
+    if (!leaseId || leaseId.length === 0) return undefined;
+    const leaseDir = process.env[ENV_VAR.RK_DEVICE_LEASE_DIR] ?? join(cwd, ".roku", "leases");
+    try {
+        const lease = await readLeaseFile(leaseId, leaseDir);
+        if (typeof lease.ip === "string" && lease.ip.length > 0) {
+            return lease.ip;
+        }
+        return undefined;
+    } catch {
+        // `readLeaseFile` throws `DevicePoolError(INVALID_LEASE_FILE)`
+        // on ENOENT / malformed JSON / schema mismatch. We treat that
+        // as "Layer 0 didn't resolve" and let the higher / lower
+        // layers continue. A truly broken lease file is logged louder
+        // by the CLI verbs that wrote it (acquire/reap); the resolver
+        // is not the right place to surface that.
+        return undefined;
+    }
+}
+
+/**
+ * Resolve the device IP. See file-level doc-block for the precedence
+ * order. Throws `RkClientError(RK_DEVICE_IP_UNRESOLVED)` with an
+ * actionable message when no layer yields an IP.
+ */
+export async function resolveActiveDeviceIp(cwd: string = process.cwd()): Promise<string> {
+    const envIp = process.env[ENV_VAR.RK_DEVICE_IP];
+    if (envIp && envIp.length > 0) return envIp;
+
+    const leaseIp = await resolveFromLeaseFile(cwd);
+    if (leaseIp) return leaseIp;
+
+    const listMergedDevices = loadListMergedDevices();
+    const { devices, activeId, activeRceId } = await listMergedDevices(cwd);
+    if (activeRceId) {
+        throw new RkClientError(
+            `The active device ${activeRceId} is a Roku Cloud Emulator device; device tests run on LAN devices only. ` +
+                `Set ${ENV_VAR.RK_DEVICE_IP}=<ip> or run \`rk device set-active <lan-device>\`.`,
+            "DEVICE_KIND_UNSUPPORTED"
+        );
+    }
+    if (activeId) {
+        const active = devices.find(d => d.id === activeId);
+        if (active?.ip) return active.ip;
+    }
+
+    if (devices.length > 0 && devices[0]?.ip) return devices[0].ip;
+
+    throw new RkClientError(
+        `Unable to resolve a Roku device IP. Set ${ENV_VAR.RK_DEVICE_IP}=<ip>, ` +
+            `set ${ENV_VAR.RK_DEVICE_LEASE_ID}=<leaseId> after \`rk device lease acquire --target <ipv4>\` ` +
+            `(no \`rk device add\` required for raw IPs), or run \`rk device add <ip>\` in the workspace, ` +
+            `then re-run the suite. IPv6 and hostnames are not supported by the local pool.`,
+        "RK_DEVICE_IP_UNRESOLVED"
+    );
+}
+
+// Re-export `leaseFilePath` so consumers (e.g. `rk-server`) that
+// need to construct the same path as the resolver have a single
+// source of truth. Avoids two implementations drifting on
+// `.roku/leases/<id>.json` layout.
+export { leaseFilePath };
+
+/**
+ * Write the resolved IP into `testResultsDir/.device-ip` so worker
+ * processes (spawned after globalSetup) can read it synchronously.
+ */
+export async function persistDeviceIp(testResultsDir: string, ip: string): Promise<void> {
+    await fs.mkdir(testResultsDir, { recursive: true });
+    await fs.writeFile(join(testResultsDir, DEVICE_IP_CACHE_FILE), ip, "utf8");
+}

package/src/device/lease-provisioning.ts

@@ -0,0 +1,54 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+/**
+ * Provisioning facts the device-pool provider recorded on the lease.
+ *
+ * These describe how the device was *prepared*, which no ECP query can
+ * answer: `/query/device-info` reports the running `ui-software` version
+ * but not which OS image produced it. `globalSetup` folds them into the
+ * `device-env.json` artifact so a red CI run carries its own provenance.
+ *
+ * The lease file — not an env var — is the source of truth. Provider-owned
+ * env vars are Roku-internal and deliberately unknown to this package; the
+ * lease is the generic, already-sanctioned hand-off (the same one
+ * `device-resolver.ts` reads the IP from), and it records what the provider
+ * *actually* booted rather than what CI *asked* for.
+ *
+ * Every miss degrades to `{}`: no lease (local desk run), a provider that
+ * flashes nothing (`local`, say), a corrupt file, or an older provider
+ * that predates the rider. The artifact simply omits the field — absence
+ * means "unknown", never "none".
+ */
+
+import { join } from "node:path";
+
+import { readLeaseFile } from "@roku-sdk/tooling/src/device-pool/lease-writer";
+
+import { ENV_VAR, LEASE_FIELD } from "../constants";
+
+export interface LeaseProvisioning {
+    /** See `LEASE_FIELD.ROOTFS_ARTIFACTORY_PATH`. Absent when unknown. */
+    rootfsArtifactoryPath?: string;
+}
+
+/**
+ * Read the provisioning riders off this job's lease. Never throws — a
+ * diagnostics-only artifact field must not be able to fail a suite that
+ * would otherwise pass.
+ */
+export async function readLeaseProvisioning(cwd: string = process.cwd()): Promise<LeaseProvisioning> {
+    const leaseId = process.env[ENV_VAR.RK_DEVICE_LEASE_ID];
+    if (!leaseId || leaseId.length === 0) return {};
+    const leaseDir = process.env[ENV_VAR.RK_DEVICE_LEASE_DIR] ?? join(cwd, ".roku", "leases");
+    try {
+        const lease = await readLeaseFile(leaseId, leaseDir);
+        const rootfs = (lease as Record<string, unknown>)[LEASE_FIELD.ROOTFS_ARTIFACTORY_PATH];
+        return typeof rootfs === "string" && rootfs.length > 0 ? { rootfsArtifactoryPath: rootfs } : {};
+    } catch {
+        // `readLeaseFile` throws on ENOENT / malformed JSON / schema
+        // mismatch. The IP resolver already ran against the same file and
+        // reports a genuinely broken lease far more loudly than a
+        // provenance field ever should, so stay silent here.
+        return {};
+    }
+}