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

package/src/constants.ts

@@ -0,0 +1,471 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+import type { EcpCategory } from "./types";
+
+export const ENV_VAR = {
+    /** Set to `"true"` or `"1"` by CI runners. */
+    CI: "CI",
+    /** Set to `"1"` to overwrite committed baselines on the next run. */
+    UPDATE_BASELINES: "UPDATE_BASELINES",
+    /** Override the default inter-key delay (ms) for `client.keysequence`. */
+    KEY_DELAY: "DEVICE_TEST_KEY_DELAY",
+    /**
+     * Explicit override for the target Roku device IP. When set, bypasses
+     * `.roku/` active-device resolution. Must be a local-network IPv4.
+     */
+    RK_DEVICE_IP: "RK_DEVICE_IP",
+    /**
+     * Roku developer-mode password. Set together with `RK_DEVICE_IP`
+     * to bypass `.roku/roku-dev-config.json`. A partial pair is a
+     * misconfiguration and fails loudly with `DeployFailedError`
+     * (silent fallback would mask the partial-config case).
+     */
+    RK_DEVICE_PASSWORD: "RK_DEVICE_PASSWORD",
+    /**
+     * Absolute path override for the baselines root directory. Primary
+     * mechanism is `setBaselineRoot()`; this env var is the one-off
+     * escape hatch for scripts run outside the configured Jest setup.
+     */
+    DEVICE_TEST_BASELINES: "DEVICE_TEST_BASELINES",
+    /**
+     * Resolution override (`"hd"` | `"fhd"`) for baseline-directory
+     * selection when no active `RkClient` has a cached `DeviceInfo`
+     * (e.g. ad-hoc CLI use). Ignored once a client has been registered
+     * via `setActiveClient()`.
+     */
+    DEVICE_TEST_RESOLUTION: "DEVICE_TEST_RESOLUTION",
+    /**
+     * Base URL of the `rk server` daemon. Canonical shape is
+     * `http://host:port/api`; bare `http://host:port` is also accepted
+     * (normalizer appends `/api`). Defaults to `DEFAULT_RK_SERVER_URL`.
+     */
+    RK_SERVER_URL: "RK_SERVER_URL",
+    /**
+     * Per-call idle timeout (ms) for the `POST /api/build` SSE stream.
+     * Caps sidecar wedges at a recoverable per-call failure instead
+     * of eating the whole CI job. Override when cold esbuild init on
+     * constrained CI runners exceeds the default
+     * `BUILD_SSE_IDLE_TIMEOUT_DEFAULT_MS`. Invalid values warn and
+     * fall back to the default — startup must never crash on a typo.
+     */
+    BUILD_SSE_IDLE_TIMEOUT_MS: "RK_BUILD_SSE_IDLE_TIMEOUT_MS",
+    /**
+     * Identifier for the GitLab CI shard / job slice running this
+     * suite (e.g. "runtime", "components"). Surfaced in JUnit
+     * `<properties>` and the `[device-lease]` log so post-hoc
+     * telemetry can correlate per-shard wall time and device usage.
+     *
+     * Defaults to `"default"` when unset so JUnit consumers and
+     * dashboards never render an empty value (an empty value is
+     * indistinguishable from a missing property in most viewers).
+     *
+     * Forms part of the parallel-device telemetry baseline and is
+     * consumed verbatim by the parallel-shard JUnit naming. Defining
+     * it here lets the env-allowlist reference the same name without
+     * churn.
+     */
+    RK_SHARD_NAME: "RK_SHARD_NAME",
+    /**
+     * Identifier for the device-pool provider that supplied the
+     * device for this run (e.g. `"local"`, `"cloud"`).
+     * Surfaced in JUnit `<properties>` and the `[device-lease]`
+     * log so telemetry can attribute regressions to a specific
+     * provider tier.
+     *
+     * **Forward-compat note.** The original spec called for a
+     * hardcoded `"local"` literal at this stage. We plumb an env
+     * var with a `"local"` default instead so:
+     *   - Baseline runs emit the same value (no behavioral
+     *     diff against the spec).
+     *   - Provider-backed pools can set this
+     *     env var from their CLI without retrofitting
+     *     `device-test-client`.
+     *
+     * If the provider seam ends up choosing a different injection
+     * mechanism (e.g. `ResolvedConfig.pool` via a runtime setter),
+     * this env var becomes dead and should be removed.
+     */
+    RK_PROVIDER_KIND: "RK_PROVIDER_KIND",
+    /**
+     * ULID of the device-pool lease the current test process should
+     * read its target IP + passwordRef from. When set, the resolver's
+     * **Layer 0** reads `.roku/leases/<id>.json`, Zod-validates it
+     * through `DeviceLeaseSchema`, and returns the embedded `ip` /
+     * resolved `passwordRef`.
+     *
+     * Precedence inside the resolver (later overrides earlier):
+     *   1. (Layer 0) `RK_DEVICE_LEASE_ID` — set by `rk device lease
+     *      acquire`; the canonical CI path for provider-backed pools.
+     *   2. `RK_DEVICE_IP` — partner-side explicit override; STILL
+     *      wins on conflict so we don't surprise partner pipelines.
+     *   3. `.roku/` active device → first registered device (today's
+     *      behavior).
+     *
+     * Forms the producer side of the parallel-CI model. The acquiring
+     * provider writes the lease file; this env var pins
+     * the consumer at boot to the correct lease without reading
+     * any workspace-singleton state (`.roku/roku-dev-config.json`
+     * cannot be safely shared across parallel jobs).
+     */
+    RK_DEVICE_LEASE_ID: "RK_DEVICE_LEASE_ID",
+
+    /**
+     * Directory holding lease files, defaulting to `<cwd>/.roku/leases`.
+     * Set by CI (and `scripts/run-shards-on-devices.sh`) so a job running
+     * from a subdirectory still finds the lease the acquire step wrote.
+     *
+     * Every reader must resolve it identically — two readers disagreeing on
+     * the directory silently read two different leases.
+     */
+    RK_DEVICE_LEASE_DIR: "RK_DEVICE_LEASE_DIR"
+} as const;
+
+/** Default delay between successive ECP keypresses, in milliseconds. */
+export const DEFAULT_KEY_DELAY = 100;
+
+/**
+ * Default per-request ECP timeout for non-capture calls. 10s (not 5s)
+ * because `/launch/dev` against an Instant-Resume manifest can take
+ * several seconds on slow hardware before returning 200.
+ */
+export const DEFAULT_REQUEST_TIMEOUT_MS = 10_000;
+
+/**
+ * Retry backoff after a transient ECP failure (5xx or timeout). Callers
+ * see a single retry; if the second attempt fails the original error
+ * propagates.
+ */
+export const ECP_RETRY_BACKOFF_MS = 500;
+
+/**
+ * Per-category minimum gap (ms) between the END of the previous call
+ * and the START of the next. `app-ui` 200ms (waitForNode cadence),
+ * `capture` 500ms (expensive); other categories 0 (still serialized).
+ */
+export const ECP_INTERVAL_MS: Readonly<Record<EcpCategory, number>> = {
+    "query-appui": 200,
+    "query-device-info": 0,
+    "query-active-app": 0,
+    keypress: 0,
+    launch: 0,
+    capture: 500
+};
+
+/** Video modes the framework recognises. Anything else fails fast at startup. */
+export const SUPPORTED_VIDEO_MODES: ReadonlySet<string> = new Set(["720p", "720p60", "1080p", "1080p60"]);
+
+// ---------------------------------------------------------------------------
+// Device recovery (crash / reboot resilience)
+// ---------------------------------------------------------------------------
+
+/**
+ * Default budget for `waitForDeviceOnline`. Roku crash-recovery
+ * (reboot + home-screen mount + ECP responder) lands in 60–120s on
+ * reference hardware; 180s covers cold-boot on Roku Express without
+ * letting a permanent outage hang silently.
+ */
+export const DEVICE_ONLINE_DEFAULT_TIMEOUT_MS = 180_000;
+
+/**
+ * Probe interval inside `waitForDeviceOnline`. Sub-second cadence has
+ * been observed to starve `/logs/*` transitions on the rk-server side
+ * (single-threaded ECP responder during the crash window).
+ */
+export const DEVICE_ONLINE_POLL_INTERVAL_MS = 2_000;
+
+/**
+ * Default budget for the installer-port (HTTP/80) phase of
+ * `waitForDeviceFullyReady`. The installer is what `rk` POSTs the
+ * sideload package to, and on reference hardware it lags ECP recovery
+ * by a few seconds after a crash/reboot — long enough that probing only
+ * `/query/device-info` (port 8060) and immediately retrying a deploy
+ * yields the misleading "Device is not reachable on the network"
+ * diagnostic. 60s covers the observed lag with headroom while still
+ * keeping the overall guard budget bounded.
+ */
+export const INSTALLER_PORT_PROBE_DEFAULT_TIMEOUT_MS = 60_000;
+
+/**
+ * Probe interval for the installer-port arm of
+ * `waitForDeviceFullyReady`. 1s is fast enough to catch the typical
+ * 2–10s post-ECP installer recovery window without flooding the device
+ * with TCP SYNs while it is still booting.
+ */
+export const INSTALLER_PORT_PROBE_INTERVAL_MS = 1_000;
+
+/**
+ * Per-attempt TCP-connect timeout for the installer-port probe. Mirrors
+ * `tcpProbe`'s default in `@roku-sdk/tooling`; surfaced here so tests
+ * and callers can reason about probe latency without crossing package
+ * boundaries.
+ */
+export const INSTALLER_PORT_TCP_TIMEOUT_MS = 1_500;
+
+/**
+ * Test-level retries for device recovery. Higher counts mask real
+ * regressions; lower counts leave first-observed crashes unrecovered.
+ */
+export const DEVICE_RECOVERY_DEFAULT_RETRIES = 3;
+
+/**
+ * Default post-sideload readiness deadline. Covers cold-start on the
+ * slowest reference hardware (Express ~3s, Ultra ~1s) with headroom
+ * for GC/HDCP stalls. Pass `readinessTimeout` explicitly for slower fixtures.
+ */
+export const READINESS_TIMEOUT_MS = 10_000;
+
+/**
+ * Sleep between readiness probes on the `/query/active-app` arm
+ * (which has a 0ms queue gap). Avoids DoS-ing the device during
+ * sideload transitions.
+ */
+export const READINESS_POLL_INTERVAL_MS = 200;
+
+/**
+ * Consecutive predicate passes before declaring ready. Two catches
+ * crashes shortly after first render (observed `EXIT_APP_ERROR` ~300ms
+ * after splash); higher counts add deploy latency for diminishing
+ * returns since later `assertAppAlive` calls cover longer windows.
+ */
+export const READINESS_CONFIRM_POLLS = 2;
+
+/**
+ * Fraction of the readiness budget tolerating post-launch home-screen
+ * responses before a previously-observed app is treated as
+ * `crashed-after-ready`. `/launch/dev` returns 200 before firmware
+ * swaps the active app (~200–500ms transition), and InstantOn can
+ * briefly bounce through Home after first render. A never-observed app
+ * is classified only at the full readiness timeout; slow cold sideloads
+ * can remain on Home longer than this grace window and still launch.
+ */
+export const HOME_SCREEN_GRACE_FRACTION = 0.25;
+
+/**
+ * Absolute floor for the home-screen grace window. Without it, a
+ * sub-second readiness budget would compute a grace below the
+ * `/launch/dev` → off-home transition and false-positive.
+ */
+export const HOME_SCREEN_GRACE_MIN_MS = 500;
+
+/**
+ * Tag names of root-level system dialogs (e.g. "Display type detection").
+ * Matching on tag at the root rules out app-authored `Dialog` subclasses
+ * (those live inside a mounted Scene, not as root siblings).
+ */
+export const SYSTEM_DIALOG_TAGS: ReadonlySet<string> = new Set([
+    "Dialog",
+    "StandardMessageDialog",
+    "StandardDialog",
+    "ProblemDialog",
+    "KeyboardDialog",
+    "PinEntryDialog"
+]);
+
+/**
+ * Default `waitForNode` cadence; matches the `/query/app-ui` queue gap
+ * so polling lands naturally on the queue's rhythm.
+ */
+export const WAIT_FOR_NODE_DEFAULT_INTERVAL_MS = 200;
+
+/** Max serialized depth in `summarizeTree`; deeper subtrees become `[N children]`. */
+export const TREE_SUMMARY_MAX_DEPTH = 3;
+
+/** Hard cap on `summarizeTree` output length. */
+export const TREE_SUMMARY_MAX_CHARS = 2000;
+
+/** Snippet length for expected/actual JSON values in `TreeMismatchError`. */
+export const TREE_DIFF_SNIPPET_MAX_CHARS = 200;
+
+/** Baseline directory name per-resolution. */
+export const BASELINE_RESOLUTION_DIR = {
+    hd: "hd",
+    fhd: "fhd"
+} as const;
+
+/** Filenames written under each consumer's `test-results/` directory. */
+export const ARTIFACT_FILE = {
+    DEVICE_ENV: "device-env.json",
+    JUNIT: "junit.xml",
+    DEVICE_LOG: "device.log",
+    /**
+     * CommonJS file written by the telemetry helper that the
+     * `jest-junit` reporter `require()`s at JUnit generation
+     * time to add per-`<testcase>` `<properties>` entries
+     * (`device-id`, `shard-name`, `providerKind`). Picked up via
+     * `jest-junit`'s `testCasePropertiesFile` /
+     * `testCasePropertiesDirectory` options. Filename is exposed
+     * as a constant so the consumer's `jest.config.ts` and the
+     * writer in `telemetry.ts` reference the same string.
+     */
+    JUNIT_CASE_PROPERTIES: "junit-test-case-properties.js"
+} as const;
+
+/**
+ * Optional `.passthrough()` riders on `.roku/leases/<id>.json` that this
+ * package reads. Not declared by `DeviceLeaseSchema`, so the names are the
+ * whole contract — they must match the provider that stamps them (see the
+ * "Known passthrough riders" list in
+ * `@roku-sdk/tooling/src/device-pool/schemas/lease.ts`).
+ */
+export const LEASE_FIELD = {
+    /**
+     * OS image the pool provider flashed the device with before handing out
+     * the lease. Recorded verbatim in `device-env.json` so a failed run can
+     * be traced back to an image: the ECP `firmwareVersion` is too coarse
+     * (several images report the same `ui-software` version) and the
+     * provider-side libraries (`grandcentral`, `trc-channel`) can differ
+     * between two devices that report identical firmware.
+     */
+    ROOTFS_ARTIFACTORY_PATH: "rootfsArtifactoryPath"
+} as const;
+
+// ---------------------------------------------------------------------------
+// Failure diagnostics
+// ---------------------------------------------------------------------------
+
+/** Directory (relative to `testResultsDir`) for per-failure bundles. */
+export const FAILURES_DIR = "failures";
+
+/**
+ * Filenames inside each per-failure bundle. Keep in sync with
+ * `writeFailureBundle` — CI artifact pipelines key off these names.
+ */
+export const FAILURE_ARTIFACT_FILE = {
+    SCREENSHOT: "screenshot.png",
+    DOM_TREE: "dom-tree.json",
+    RECENT_LOGS: "recent-logs.txt",
+    ERROR: "error.txt",
+    /**
+     * `LogStreamHealth` snapshot at failure time; lets a reviewer
+     * attribute a log timeout to either the device→server telnet leg
+     * or the server→client SSE leg without rerunning.
+     */
+    STREAM_HEALTH: "stream-health.json"
+} as const;
+
+/** Default tail size for `recent-logs.txt`. */
+export const FAILURE_RECENT_LOG_LINES = 100;
+
+/**
+ * Global keys shared between consumer `setup.ts` and the custom Jest
+ * test environment. Globals (not env options) because Jest constructs
+ * the environment in a different module context from `setup.ts` and
+ * globals are the only surface both sides reach.
+ */
+export const DEVICE_ENV_GLOBAL_KEY = {
+    CLIENT: "__DEVICE_CLIENT__",
+    TEST_RESULTS_DIR: "__DEVICE_TEST_RESULTS_DIR__",
+    LOG_SINK: "__DEVICE_LOG_SINK__",
+    /**
+     * Opt-out switch for the failure-bundle pipeline. Written
+     * synchronously at install time (not in `beforeAll`) so the first
+     * `test_fn_failure` event already sees the final value. Absent
+     * key + absent `TEST_RESULTS_DIR` → env stays silent (vanilla
+     * `jest-environment-node` consumers don't get unsolicited bundles).
+     */
+    CAPTURE_ENABLED: "__DEVICE_CAPTURE_ENABLED__"
+} as const;
+
+/**
+ * Per-suite cache of the IP resolved by `globalSetup`. Workers read
+ * synchronously from `createDefaultClient()` since `listMergedDevices`
+ * is async and the worker-side factory is sync.
+ */
+export const DEVICE_IP_CACHE_FILE = ".device-ip";
+
+// ---------------------------------------------------------------------------
+// Log assertions
+// ---------------------------------------------------------------------------
+
+/**
+ * Default `rk server` base URL. Canonical form includes `/api` (matches
+ * `apiEndpoint` in `.roku/rk-server.json`); bare `http://host:port` is
+ * normalized by `resolveServerUrl`.
+ */
+export const DEFAULT_RK_SERVER_URL = "http://localhost:3737/api";
+
+/** Roku device console log port. Mirror of `tooling-utils/constants.ts → ROKU_LOG_PORT`. */
+export const ROKU_LOG_PORT = 8085;
+
+/**
+ * Hard cap on retained log entries per worker. ~10k × ~200 B ≈ 2MB
+ * keeps a long-running suite within memory bounds; an earlier 200k
+ * cap drove the device-test container past its cgroup limit.
+ */
+export const LOG_BUFFER_MAX_LINES = 10_000;
+
+/**
+ * Oldest entries dropped on cap. Half-drop is amortised O(1) per
+ * append vs drop-one-per-append; the doubled retention window absorbs
+ * short `since`-pos snapshots without surprise overflows.
+ */
+export const LOG_BUFFER_DROP_HALF = 5_000;
+
+/** Default `waitForLog` timeout. */
+export const WAIT_FOR_LOG_DEFAULT_TIMEOUT_MS = 5_000;
+
+/** Upper bound on `recentLines` rendered into `WaitForLogTimeoutError`. */
+export const WAIT_FOR_LOG_RECENT_LINES_MAX = 20;
+
+/** Character cap on the recentLines preview block. */
+export const WAIT_FOR_LOG_RECENT_CHARS_MAX = 600;
+
+/**
+ * SSE parser `pending` accumulator cap. Frames are normally a few
+ * hundred bytes; a stream past 1 MiB without `\n\n` is broken or
+ * hostile — fail loud rather than leak memory.
+ */
+export const SSE_PENDING_MAX_BYTES = 1_048_576;
+
+/**
+ * Default per-call idle timeout (ms) for the `POST /api/build` SSE
+ * stream consumed by `requestServerBuild`. Sized for the worst-case
+ * cold path on constrained CI runners: first-time esbuild service
+ * spawn (~10–15s on shared CI containers) + Hermes warmup
+ * (~30–60s) + first incremental TS resolve (~30s). 90s — the prior
+ * value — could trip on cold starts and surface as the opaque
+ * `RK_SERVER_BUILD_IDLE_TIMEOUT` code, indistinguishable from a
+ * real build error. 180s comfortably covers cold-start without
+ * letting a permanent sidecar wedge eat the whole job's budget.
+ *
+ * Override per-environment via the `RK_BUILD_SSE_IDLE_TIMEOUT_MS`
+ * env var (any positive integer, in ms). Invalid values warn and
+ * fall back to this default rather than crashing the test run.
+ */
+export const BUILD_SSE_IDLE_TIMEOUT_DEFAULT_MS = 180_000;
+
+// ---------------------------------------------------------------------------
+// Screenshot assertions
+// ---------------------------------------------------------------------------
+
+/**
+ * Default convergence interval for `captureStableScreenshot`. Matches
+ * the ECP queue's `capture` gap so polling lands on the queue's cadence.
+ */
+export const SCREENSHOT_STABLE_DEFAULT_INTERVAL_MS = 500;
+
+/**
+ * Default pixel-mismatch ratio for `expectScreenshot` (1% of the
+ * unmasked canvas). Tolerates anti-aliasing drift without missing
+ * legitimate content changes.
+ */
+export const DEFAULT_SCREENSHOT_THRESHOLD = 0.01;
+
+/**
+ * Per-pixel YIQ cutoff for `pixelmatch`. Decoupled from the caller-facing
+ * threshold (which is the aggregate-ratio knob); 0.1 is pixelmatch's
+ * own library default.
+ */
+export const PIXELMATCH_COLOR_THRESHOLD = 0.1;
+
+/**
+ * Per-axis ceiling for `ScreenshotMatchOptions.alignTolerance`. The
+ * search is O((2x+1)(2y+1)) candidate offsets, so the cap bounds both
+ * the runtime and how far the comparator may slide a capture before
+ * scoring it — a wide window could "align" genuinely different content.
+ * Observed device-dependent OSD re-centering is 1-3px.
+ */
+export const ALIGN_TOLERANCE_MAX_PX = 4;
+
+/** Default diff-PNG directory; overridable via `setScreenshotDiffRoot`. */
+export const SCREENSHOT_DIFF_DIR = "test-results/diffs";

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"
+    );
+}