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

package/src/client/server-url.ts

@@ -0,0 +1,137 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+/**
+ * `resolveServerUrl` — single source of truth for where the
+ * `rk server` daemon lives, shared between `RkClient` construction
+ * and `globalSetup`/`globalTeardown`.
+ *
+ * Why a dedicated module instead of an inline helper? Jest's
+ * `globalTeardown` runs in a separate module graph from the worker
+ * processes that construct `RkClient`, so we need a tree-shake-safe
+ * import path that does not pull in the full `client.ts` surface
+ * (with its `pngjs`, `@roku-sdk/tooling/*` deps) into the teardown
+ * lifecycle. Isolating this helper keeps teardown lean and makes the
+ * resolution order easy to audit in one place.
+ *
+ * Resolution order (first non-empty wins):
+ *   1. `opts.serverUrl` — explicit override.
+ *   2. `process.env[RK_SERVER_URL]` — per-process env var.
+ *   3. `.roku/rk-server.json#apiEndpoint` — discovery file the
+ *      `rk server` CLI writes on startup. The port is derived from a
+ *      sha256 of the workspace path (see
+ *      `@roku-sdk/tooling` `server/port-derivation.ts`), so the
+ *      default `:3737` is almost never the right answer for a real
+ *      developer box. Reading this file lets the fixture's log pillar
+ *      "just work" after the user starts `rk server` — no manual
+ *      `RK_SERVER_URL=…` export required.
+ *   4. `DEFAULT_RK_SERVER_URL` — compiled-in fallback.
+ *
+ * Discovery is intentionally best-effort: a torn read during a
+ * server restart, a missing file, or a malformed JSON payload all
+ * fall through silently to the next resolution tier.
+ *
+ * Output normalization. Whatever tier wins, the returned URL is
+ * normalized to end with `/api` (no trailing slash). All consumers
+ * (`LogSession.postStart`, `LogStreamClient`, `globalSetup`'s
+ * `resetAndStartLogSession`, `RkClient.getLogStreamHealth`) build
+ * request URLs by appending `/logs/...` to this base, and every
+ * route on the server is mounted under `/api/...`
+ * (`tooling/src/server/index.ts:387: app.use("/api/logs", logRoutes)`).
+ * The discovery file already emits the canonical `http://host:port/api`
+ * shape (`coordination.ts::createPortFileData`); the env var path
+ * historically allowed a bare `http://host:port` and silently 404'd.
+ * Normalizing here makes both tiers indistinguishable to consumers
+ * and means a developer can set `RK_SERVER_URL` without remembering
+ * the `/api` suffix.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { join, resolve as resolvePath } from "node:path";
+
+import { DEFAULT_RK_SERVER_URL, ENV_VAR } from "../constants";
+
+export interface ResolveServerUrlOptions {
+    /** Explicit override (e.g. from `RkClientOptions.serverUrl`). */
+    serverUrl?: string;
+    /**
+     * Directory to start the `.roku/rk-server.json` walk from. Defaults
+     * to `process.cwd()`; tests inject a synthetic start dir so they
+     * don't depend on the actual filesystem layout.
+     */
+    startDir?: string;
+}
+
+export function resolveServerUrl(opts: ResolveServerUrlOptions = {}): string {
+    return normalizeServerUrl(resolveRawServerUrl(opts));
+}
+
+function resolveRawServerUrl(opts: ResolveServerUrlOptions): string {
+    if (opts.serverUrl) return opts.serverUrl;
+    const envUrl = process.env[ENV_VAR.RK_SERVER_URL];
+    if (envUrl) return envUrl;
+    const discovered = readRkServerDiscovery(opts.startDir ?? process.cwd());
+    if (discovered) return discovered;
+    return DEFAULT_RK_SERVER_URL;
+}
+
+/**
+ * Coerce any of the historical accepted shapes —
+ * `http://host:port`, `http://host:port/`, `http://host:port/api`,
+ * `http://host:port/api/` — into the canonical
+ * `http://host:port/api` (no trailing slash). Idempotent. Exported
+ * for unit tests; production callers should always go through
+ * `resolveServerUrl`.
+ */
+export function normalizeServerUrl(url: string): string {
+    const trimmed = url.endsWith("/") ? url.slice(0, -1) : url;
+    return trimmed.endsWith("/api") ? trimmed : `${trimmed}/api`;
+}
+
+/**
+ * Best-effort read of `.roku/rk-server.json#apiEndpoint` by walking
+ * up from `startDir` and looking for the file directly. Returns
+ * `null` on any failure.
+ *
+ * We look for the FILE (`.roku/rk-server.json`) rather than its
+ * containing directory (`.roku/`) because per-suite scaffolding
+ * often creates a local placeholder `.roku/` (e.g. `device-tests/
+ * .roku/` is a gitkept empty dir). Anchoring on the file — which is
+ * only written by `rk server` — sidesteps those false positives.
+ *
+ * Exported for unit tests — production code should go through
+ * `resolveServerUrl`.
+ */
+export function readRkServerDiscovery(startDir: string): string | null {
+    const file = findRkServerConfigFile(startDir);
+    if (!file) return null;
+    try {
+        const raw = readFileSync(file, "utf8");
+        const parsed = JSON.parse(raw) as { apiEndpoint?: unknown };
+        if (typeof parsed.apiEndpoint === "string" && parsed.apiEndpoint) {
+            return parsed.apiEndpoint;
+        }
+        return null;
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * Walk up from `startDir` looking for a `.roku/rk-server.json` file.
+ * Returns the absolute path to the first match, or `null` if we
+ * reach `/` first without finding one. The walk stops only at the
+ * filesystem root — we do NOT treat `.git` / `pnpm-workspace.yaml`
+ * as fences, because `rk server` typically runs at the outermost
+ * monorepo root while tests run from a package-level cwd several
+ * levels below, and we want them to find the outer config.
+ */
+function findRkServerConfigFile(startDir: string): string | null {
+    let dir = resolvePath(startDir);
+    for (;;) {
+        const candidate = join(dir, ".roku", "rk-server.json");
+        if (existsSync(candidate)) return candidate;
+        const parent = resolvePath(dir, "..");
+        if (parent === dir) return null;
+        dir = parent;
+    }
+}

package/src/constants.ts

@@ -0,0 +1,520 @@
+// 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",
+    /**
+     * Path to a module that default-exports (or exports `createDeploymentDriver`)
+     * a factory returning a `DeploymentDriver`. When set, `createDefaultClient`
+     * runs apps through the driver instead of a device and needs no device IP.
+     */
+    RK_DEVICE_DRIVER_MODULE: "RK_DEVICE_DRIVER_MODULE",
+    /**
+     * 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;
+
+/**
+ * Consecutive deploys that may fail to foreground the channel on a VM
+ * known to have foregrounded one earlier before the wedge is treated as
+ * fatal rather than as a bad launch.
+ *
+ * One file's full deploy-retry budget is allowed to fail softly, so a
+ * genuinely transient stall still resolves the way it always has; the
+ * next failure after that is a second file reaching the same verdict,
+ * which no amount of further retrying has ever cured. Derived from the
+ * retry budget so the two cannot drift apart.
+ */
+export const FOREGROUND_FAILURE_STREAK_FATAL = DEVICE_RECOVERY_DEFAULT_RETRIES + 1;
+
+/**
+ * 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;
+
+/**
+ * Launch requests the readiness gate re-sends, per deploy, when the
+ * device log shows the channel entering and then exiting with
+ * `EXIT_APP_ERROR`. Firmware 15.3.4 on virtualized hosts ends some
+ * launches that way right after a sideload, its TypeScript process still
+ * compiling the build `replace()` removed, and a launch of the same build
+ * a few seconds later succeeds. A build that crashes during mount exits
+ * the same way and pays at most this many extra launches per deploy.
+ */
+export const LAUNCH_CRASH_RELAUNCH_MAX = 2;
+
+/**
+ * Minimum spacing between two launch requests from the readiness gate.
+ * A relaunch also waits out the home-screen grace window, so InstantOn's
+ * own exit-and-relaunch is not raced.
+ */
+export const LAUNCH_CRASH_RELAUNCH_GAP_MS = 2_000;
+
+/**
+ * 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;
+
+/** Build output directory the client uses for fixture apps, relative to the app root. */
+export const INTEGRATION_BUILD_OUT_DIR = "dist-integration-test";
+
+/** 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;
+
+/**
+ * Grace window granted to a log assertion whose wait window stayed
+ * empty, measured from the re-attach it triggers. `/logs/tail`
+ * resolves readiness on its first status frame and emits the
+ * replayed buffer immediately after, so the lines land a round trip
+ * — not a device operation — later.
+ */
+export const LOG_STREAM_RESYNC_GRACE_MS = 1_000;
+
+/**
+ * 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";