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

package/src/types.ts

@@ -0,0 +1,472 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+import type { DeviceTarget } from "@roku-sdk/tooling/src/tooling-utils/device-target";
+
+export interface DeviceInfo {
+    modelName: string;
+    modelNumber: string;
+    modelFamily: string;
+    deviceClass: string;
+    firmwareVersion: string;
+    videoMode: string;
+    locale: string;
+    country: string;
+    libraries: Record<string, string>;
+}
+
+export interface AppUiNode {
+    /** XML tag name (e.g. `"Label"`, `"RowList"`). */
+    tag: string;
+    /**
+     * Raw ECP attributes verbatim (all values are strings; numeric
+     * comparisons require parsing). `bounds`/`focused` are also kept
+     * here as strings so attribute iteration is exhaustive.
+     */
+    attrs: Record<string, string>;
+    bounds: { x: number; y: number; width: number; height: number };
+    focused: boolean;
+    children: AppUiNode[];
+}
+
+export interface NodePredicate {
+    tag?: string;
+    attr?: Record<string, string>;
+    focused?: boolean;
+}
+
+export interface LibraryRequirement {
+    /** Library identifier as reported by Roku ECP (`rida`, etc.). */
+    name: string;
+    /** Semver range (e.g. `">=2.0"`) — matched against the library's reported version. */
+    version: string;
+}
+
+/**
+ * Test-declared requirements for `requirePrecondition` / `itOnDevice` /
+ * `describeOnDevice`.
+ *
+ * Match strategy: `firmwareVersion` semver range (4-part Roku versions
+ * coerced to MAJOR.MINOR.PATCH); `modelFamily` exact;
+ * `deviceClass` exact against a derived perf tier (NOT `DeviceInfo.deviceClass`,
+ * which is form-factor); `videoMode` prefix; `locale`/`country` exact.
+ * `library` throws `PreconditionNotImplementedError` (no ECP query path).
+ *
+ * Evaluation is in key-insertion order, so the caller controls which
+ * field produces the error when multiple mismatch.
+ */
+export interface Precondition {
+    firmwareVersion?: string;
+    modelFamily?: string;
+    deviceClass?: string;
+    videoMode?: string;
+    locale?: string;
+    country?: string;
+    library?: LibraryRequirement;
+}
+
+export interface MaskRegion {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+
+export interface WaitOptions {
+    timeout: number;
+    interval?: number;
+}
+
+export interface CaptureStableOptions {
+    timeout: number;
+    interval?: number;
+    mask?: MaskRegion[];
+    /**
+     * Maximum number of differing pixels (outside `mask`) between two
+     * consecutive captures that still counts as "stable". Defaults to
+     * `0` — strict pixel equality, the historical contract.
+     *
+     * Use a small positive value when the firmware's anti-aliasing
+     * pipeline emits sub-pixel jitter on static text (~50–500 pixels
+     * per frame on FHD) even after the user-visible content has
+     * settled. Pair with `expectScreenshot(...).toMatchBaseline(..., {
+     * threshold })` whose `threshold` covers the same tolerance — the
+     * stability gate must not be stricter than the assertion gate,
+     * otherwise `captureStableScreenshot` can time out on a screen
+     * the baseline would have accepted.
+     */
+    tolerance?: number;
+}
+
+export interface KeySequenceOptions {
+    keyDelay?: number;
+}
+
+export interface WaitForDeviceOnlineOptions {
+    /** Total wait budget; defaults to `DEVICE_ONLINE_DEFAULT_TIMEOUT_MS` (180s). */
+    timeoutMs?: number;
+    /** Probe interval; defaults to `DEVICE_ONLINE_POLL_INTERVAL_MS` (2s). */
+    intervalMs?: number;
+}
+
+/**
+ * Options for `RkClient.waitForDeviceFullyReady`. The method gates on
+ * BOTH the ECP responder (port 8060, via `/query/device-info`) AND the
+ * sideload installer (port 80, via TCP connect). Each phase has an
+ * independent budget so a slow installer cannot starve the ECP probe
+ * (and vice versa); the overall wall time is bounded by their sum.
+ *
+ * Why two phases: the original `waitForDeviceOnline` only proves the
+ * device is responding on ECP. After a crash/reboot the installer (the
+ * port `rk` POSTs the sideload package to) lags ECP recovery by several
+ * seconds; retrying a deploy in that window surfaces the misleading
+ * "Device is not reachable on the network" diagnostic from
+ * `sideload-diagnostics`. Probing both before the next deploy attempt
+ * eliminates that whole failure class — see `installDeployGuard`.
+ */
+export interface WaitForDeviceFullyReadyOptions {
+    /**
+     * Budget for the ECP `/query/device-info` arm. Defaults to
+     * `DEVICE_ONLINE_DEFAULT_TIMEOUT_MS` (180s). Forwarded verbatim to
+     * the underlying `waitForDeviceOnline` call.
+     */
+    ecpTimeoutMs?: number;
+    /**
+     * Probe interval for the ECP arm. Defaults to
+     * `DEVICE_ONLINE_POLL_INTERVAL_MS` (2s).
+     */
+    ecpIntervalMs?: number;
+    /**
+     * Budget for the installer-port (TCP/80) arm, applied AFTER the ECP
+     * arm resolves. Defaults to `INSTALLER_PORT_PROBE_DEFAULT_TIMEOUT_MS`
+     * (60s).
+     */
+    installerTimeoutMs?: number;
+    /**
+     * Probe interval for the installer-port arm. Defaults to
+     * `INSTALLER_PORT_PROBE_INTERVAL_MS` (1s).
+     */
+    installerIntervalMs?: number;
+}
+
+export type LogPosition = string;
+
+export type LogLine = string;
+
+export interface LogQueryOptions {
+    since: LogPosition;
+    timeout?: number;
+    window?: number;
+}
+
+export interface LaunchOptions {
+    /**
+     * ECP channel id to launch. Defaults to `"dev"` (the currently
+     * sideloaded development channel). Published channels use their
+     * numeric id (e.g. `"12345"`).
+     */
+    channelId?: string;
+    /**
+     * Deep-link params serialized into the launch URL. Reliable on
+     * `launch()` (the runtime is already subscribed); cold sideloads
+     * must use `buildAndLaunchWithParams` instead.
+     */
+    deepLink?: Record<string, string>;
+    /**
+     * Post-launch readiness budget; defaults to `READINESS_TIMEOUT_MS`.
+     * On timeout: `DeployFailedError`, device flagged unhealthy.
+     */
+    readinessTimeout?: number;
+    /**
+     * Semantic readiness gate. See `BuildAndDeployOptions.readyNode`
+     * for picking-the-predicate guidance.
+     */
+    readyNode?: NodePredicate;
+}
+
+export interface BuildAndDeployOptions {
+    /**
+     * Deep-link params for the post-sideload `/launch/dev?…` POST.
+     *
+     * Cold-mount race: the POST frequently lands before the runtime
+     * subscribes to `setLaunchParamsUpdateHandler`, and firmware
+     * silently drops it. Readiness passing is NOT evidence the params
+     * arrived. Use this only for apps that ignore params, read them
+     * synchronously on mount, or gate on a fixture-emitted log line.
+     * For cold sideloads that must land in a deep-linked state, use
+     * `buildAndLaunchWithParams` instead.
+     */
+    deepLink?: Record<string, string>;
+    /** Readiness budget; defaults to `READINESS_TIMEOUT_MS` (10s). */
+    readinessTimeout?: number;
+    /** ECP channel id to launch after sideload; defaults to `"dev"`. */
+    channelId?: string;
+    /** Override device selector; defaults to active `.roku/` device. */
+    deviceSelector?: string;
+    /**
+     * Semantic readiness gate: a predicate matching a user-rendered
+     * element. Without it, readiness fires on the SceneGraph skeleton
+     * (mounted before user code), so `buildAndDeploy` can return
+     * "success" while `main()` is still compiling or crashing during
+     * mount (`EXIT_APP_ERROR` 0.3–1.0s after splash). Pick a stable
+     * Label with a known id+text; avoid wrapper tags like `Group`.
+     *
+     * Once matched, readiness still requires two consecutive passing
+     * polls — catches "mounted then immediately crashed" as
+     * `DeployFailedError({ reason: "crashed-after-ready" })`.
+     * Omitting falls back to `tree.children.length > 0`.
+     */
+    readyNode?: NodePredicate;
+    /**
+     * Override esbuild's `drop: ["console", "debugger"]` pass:
+     * `true` always drops (perf profiling), `false` never drops (for
+     * fixtures that exercise console behaviour, e.g. polyfill
+     * verifiers), `undefined` falls back to the historical default
+     * (drop on `rk build`, keep on `rk dev`).
+     */
+    dropConsole?: boolean;
+    /**
+     * Build with development artifacts — no minification, readable identifiers,
+     * source maps. Equivalent to `rk build --debug`. Useful for profiling sessions
+     * where signal/effect names and stack frames remain human-readable.
+     */
+    dev?: boolean;
+    /**
+     * Enable SolidJS dev mode — imports the `solid-js/dev` build so signal
+     * and effect names remain readable in Perfetto tracepoints. Equivalent to
+     * `rk build --solid-dev-mode` or `buildVariables: { __SIGNAL__: true }` in
+     * `roku-config.ts`.
+     */
+    solidDevMode?: boolean;
+    /**
+     * Build-time variable overrides merged on top of the app's `roku-config.ts`
+     * `buildVariables`. Pass `{ __SIGNAL__: true }` to enable SolidJS dev mode
+     * (readable signal/effect names in Perfetto tracepoints).
+     */
+    buildVariables?: Record<string, boolean | string | number>;
+}
+
+/**
+ * Options for `buildAndLaunchWithParams`. Both log regexes are
+ * required: omitting either re-introduces the cold-mount race the
+ * primitive exists to avoid.
+ */
+export interface BuildAndLaunchWithParamsOptions {
+    /** Device selector for phase-1 `buildAndDeploy`. */
+    deviceSelector?: string;
+    /** ECP channel id for both phases; defaults to `"dev"`. */
+    channelId?: string;
+    /** Readiness timeout forwarded to BOTH phases. */
+    readinessTimeout?: number;
+    /** Phase-1 semantic readiness gate; see `BuildAndDeployOptions.readyNode`. */
+    readyNode?: NodePredicate;
+    /**
+     * Required. Log regex emitted once the runtime's launch-params
+     * subscription is registered (e.g. an effect reading
+     * `useLaunchConfig()` for the first time). Gating phase 2 on this
+     * prevents the params POST from racing handler registration.
+     */
+    runtimeReadyLogPattern: RegExp;
+    /** "Runtime ready" gate timeout; defaults to 5s. */
+    runtimeReadyTimeout?: number;
+    /**
+     * Required. Log regex emitted when phase-2 params are observed by
+     * the reactive graph. Gating on this separates signal-delivery
+     * failures from renderer regressions in subsequent DOM timeouts.
+     */
+    paramsAckLogPattern: RegExp;
+    /** "Params ack" gate timeout; defaults to 5s. */
+    paramsAckTimeout?: number;
+    /** Forwarded to phase-1; see `BuildAndDeployOptions.dropConsole`. */
+    dropConsole?: boolean;
+}
+
+/**
+ * Narrow projection of `AppUiNode` for system-dialog surfacing.
+ * `tag`/`title` are top-level for reporter convenience; `node` keeps
+ * the full underlying tree for deeper inspection.
+ */
+export interface SystemDialogNode {
+    /** XML tag that matched the `SYSTEM_DIALOG_TAGS` heuristic. */
+    tag: string;
+    /** `attrs.title` on the node, if present (common on StandardMessageDialog). */
+    title: string;
+    /** Full underlying AppUiNode, for reporters that want context. */
+    node: AppUiNode;
+}
+
+/**
+ * Max whole-pixel translation the comparator may apply to the capture
+ * before scoring it against the baseline. Both axes default to 0
+ * (exact positional match) and are capped at
+ * `ALIGN_TOLERANCE_MAX_PX` — needing more than a few pixels means the
+ * baseline content is genuinely different, not merely offset.
+ *
+ * Intended for firmware-drawn surfaces (system OSD dialogs) whose
+ * internal row heights round differently per device, re-centering the
+ * whole surface by 1-3px. App-rendered content is positionally
+ * deterministic and must not use this.
+ */
+export interface AlignTolerance {
+    x?: number;
+    y?: number;
+}
+
+export interface ScreenshotMatchOptions {
+    /**
+     * Max fraction of unmasked pixels that may differ; defaults to
+     * 0.01 (1%). Per-pixel color sensitivity (YIQ 0.1) is internal
+     * and decoupled — widening this does not loosen per-pixel matching.
+     */
+    threshold?: number;
+    mask?: MaskRegion[];
+    /**
+     * Allow the capture to be translated by up to this many pixels on
+     * each axis to absorb device-dependent re-centering. Only consulted
+     * after an untranslated comparison has already failed, so it can
+     * rescue a failing assertion but never relax a passing one.
+     */
+    alignTolerance?: AlignTolerance;
+}
+
+export interface TreeMatchOptions {
+    /** Attribute keys stripped recursively before serialization. */
+    exclude?: readonly string[];
+    /**
+     * Node tags serialized as leaves: the node itself is asserted, its
+     * children are not. Use for native nodes whose internal chrome the
+     * app does not own and firmware restructures between builds.
+     */
+    excludeChildrenOf?: readonly string[];
+}
+
+/**
+ * `/query/active-app` result. Every field stays faithful to the XML, so
+ * decide "is this the home screen?" with `isHomeScreenActiveApp` rather
+ * than comparing fields directly — firmware ships several distinct home
+ * surfaces and no single field identifies all of them.
+ */
+export interface ActiveAppInfo {
+    /**
+     * `"dev"` for sideloaded, channel id for published. Empty on the
+     * classic home screen, but newer firmware reports a real id for its
+     * home surfaces (`"562859"` for Roku Dynamic Menu).
+     */
+    id: string;
+    /**
+     * User-facing title (text node of `<app>`). `"Roku"` on the classic
+     * home screen; other home surfaces use their own name, e.g.
+     * `"Roku Dynamic Menu"`.
+     */
+    title: string;
+    /** ECP `type` attribute (`"appl"`, `"home"`, `"tvin"`, …); `""` when absent. */
+    type: string;
+    /**
+     * ECP `ui-location` attribute: `"home"` for the home experience, and
+     * the channel's own id while that channel is foregrounded. `""` when
+     * absent, as on firmware that predates the attribute.
+     */
+    uiLocation: string;
+}
+
+/** ECP request categories. Keys in `ECP_INTERVAL_MS` must match. */
+export type EcpCategory = "query-appui" | "query-device-info" | "query-active-app" | "keypress" | "launch" | "capture";
+
+/**
+ * A host that runs fixture apps in place of a physical device. The client
+ * deploys through it (instead of the rk server build + installer sideload)
+ * and then speaks ECP to the transport it returns. Lets a suite run against
+ * any host that answers ECP, without the specs knowing.
+ */
+export interface DeploymentDriver {
+    /** Short name used where a device IP would appear (artifact names, messages). */
+    readonly label: string;
+    /** Answers ECP before the first deploy (e.g. `/query/device-info`). */
+    readonly initialTarget: DeviceTarget;
+    /** Subscribe to the console lines of whichever app is running; returns the unsubscribe. */
+    onLog(listener: (line: string) => void): () => void;
+    /** Build and start the app at `absPath`; resolves with the transport to use for it. */
+    deploy(request: { absPath: string; launchParams?: Record<string, string> }): Promise<DeviceTarget>;
+    /** Stop whatever the driver started. Idempotent. */
+    release?(): Promise<void>;
+}
+
+export interface RkClientOptions {
+    /** Run apps through this driver instead of a device at `deviceIp`. */
+    driver?: DeploymentDriver;
+    /** Device IPv4. Required directly; `createDefaultClient()` resolves from env/`.roku/`. */
+    deviceIp?: string;
+    /** Default inter-key delay for `keysequence` (ms). */
+    keyDelay?: number;
+    /** Per-request ECP timeout (ms); capture uses its own hard-coded longer timeout. */
+    requestTimeoutMs?: number;
+    /** Override per-category minimum intervals (ms). For tests only. */
+    intervals?: Partial<Record<EcpCategory, number>>;
+    /**
+     * Override `rk server` base URL. Precedence:
+     * `opts.serverUrl` → `RK_SERVER_URL` → `DEFAULT_RK_SERVER_URL`.
+     */
+    serverUrl?: string;
+    /** Test-only: inject a fake log session. Ignored by normal callers. */
+    logSession?: LogSessionLike;
+}
+
+/** Structural type for `LogSession`; kept here to avoid a types→class cycle. */
+export interface LogSessionLike {
+    ensureStarted(): Promise<void>;
+    dispose(): void;
+    /**
+     * Re-attach the subscription, recovering lines the current one
+     * stopped delivering. Optional so an injected fake stays valid
+     * without it; callers feature-detect and skip the recovery.
+     */
+    resync?(): Promise<void>;
+    readonly buffer: LogBufferLike;
+}
+
+/** Structural type for `LogBuffer`'s public surface. */
+export interface LogBufferLike {
+    append(line: LogLine): { seq: number; line: LogLine; ts: number };
+    currentPosition(): LogPosition;
+    linesSince(pos: LogPosition): LogLine[];
+    entriesSince(pos: LogPosition): Array<{ seq: number; line: LogLine; ts: number }>;
+    hasGapWithin(from: LogPosition, to?: LogPosition): { start: number; end: number } | null;
+    /**
+     * Return the tracked gap that contains `seq`, or `null`. Used by
+     * the per-match line-integrity check in `waitForLog`.
+     */
+    findGapContaining(seq: number): { start: number; end: number } | null;
+    subscribe(cb: (e: { seq: number; line: LogLine; ts: number }) => void): () => void;
+    markGapStart(): void;
+    markGapEnd(): void;
+    /** Lifetime stream-health stats. */
+    getStats(): {
+        gapCount: number;
+        totalGapSeqSpan: number;
+        lastGapAt: number | null;
+        openGap: boolean;
+    };
+}
+
+/**
+ * Stream-health snapshot from `getLogStreamHealth()`. `serverMetrics`
+ * is `null` on server fetch failure, `undefined` when the server has
+ * no matching session, otherwise the matched session metrics.
+ */
+export interface LogStreamHealth {
+    /** Closed gaps recorded on the client buffer since construction. */
+    gapCount: number;
+    /** Sum of `(end - start)` across closed client-side gaps (seq units). */
+    totalGapSeqSpan: number;
+    /** `Date.now()` of the most recent gap close, or `null` if none. */
+    lastGapAt: number | null;
+    /** Whether the client thinks a gap is currently open (reconnecting). */
+    openGap: boolean;
+    /** Server-side metrics; see class docstring for tri-state semantics. */
+    serverMetrics?: {
+        reconnectCount: number;
+        totalDowntime: number;
+        uptime: number;
+        connectedAt: string | null;
+        lastActivity: string | null;
+    } | null;
+}

package/support/constants.ts

@@ -0,0 +1,17 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+/**
+ * `@roku-sdk/device-test-client/support/constants`: constants a Jest config can load at parse time.
+ *
+ * The package root re-exports `RkClient`, which loads `@roku-sdk/tooling`. That package is ESM
+ * and uses `import.meta.url`, so a CommonJS-mode loader parsing `jest.config.ts` (ts-node, or the
+ * loader Jest uses) fails with `ERR_REQUIRE_ESM` before any test runs. This entry point loads only
+ * `src/constants.ts`, whose imports are type-only, so a config file can import from it safely.
+ * The same values are also exported from the package root.
+ *
+ * Only add constants a config loader needs at parse time. The file sits at this physical path so
+ * it also resolves under `moduleResolution: "Node"`, which ignores the `exports` map.
+ */
+
+export { ARTIFACT_FILE, INTEGRATION_BUILD_OUT_DIR } from "../src/constants";

package/support/deploy.ts

@@ -0,0 +1,27 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+/**
+ * `@roku-sdk/device-test-client/support/deploy`: deploy-guard helpers for test harnesses.
+ *
+ * These are for harness code that recovers from a bad deploy, not for test bodies. A harness
+ * that wipes an app's integration build output between deploy retries calls
+ * `invalidateBuildCacheForApp` with the same root, so the next `RkClient.buildAndDeploy` rebuilds
+ * instead of reusing a memoised result. Call the two together: wiping without invalidating
+ * sideloads an empty package, and invalidating without wiping rebuilds for nothing.
+ *
+ * A harness whose deployment driver sideloads through its own transport (rather than
+ * `RkClient.buildAndDeploy`) can reuse the build and manifest steps through `requestServerBuild`,
+ * `readAppTypeFromManifest` and `resolveServerUrl`.
+ *
+ * Importing this entry point loads `@roku-sdk/tooling`, which is ESM, so a CommonJS-mode config
+ * loader (ts-node parsing `jest.config.ts`) cannot load it. Config files should use
+ * `./support/constants` or `./support/paths`, which are safe to load at parse time.
+ *
+ * The file sits at this physical path, not just in the `exports` map, so it also resolves under
+ * `moduleResolution: "Node"`, which ignores `exports`.
+ */
+
+export { readAppTypeFromManifest, requestServerBuild, resolveAppPath } from "../src/client/deploy";
+export { resolveServerUrl } from "../src/client/server-url";
+export { invalidateBuildCacheForApp } from "../src/client/build-cache";

package/support/paths.ts

@@ -0,0 +1,13 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+/**
+ * `@roku-sdk/device-test-client/support/paths`: where a test run writes its artifacts.
+ *
+ * Multi-device runners and Jest global setup use these to agree on the `test-results/`
+ * directory. Like `./support/constants`, this entry point imports only Node built-ins, so a
+ * CommonJS-mode config loader can import it at parse time. It must stay free of `RkClient` and
+ * `@roku-sdk/tooling`.
+ */
+
+export { TEST_RESULTS_DIR_ENV_VAR, TEST_RESULTS_DIR_NAME, defaultTestResultsDir } from "../src/paths";