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

package/docs/rkclient.md

@@ -0,0 +1,655 @@
+# `RkClient` reference
+
+`RkClient` is the single entry point for ECP communication with a Roku
+device. It serialises every request through a queue with per-category
+minimum intervals, retries transient 5xx / timeout failures exactly
+once, and layers readiness / health / polling / log semantics on top of
+the raw ECP surface.
+
+- [Construction](#construction)
+- [ECP queries](#ecp-queries)
+- [Input](#input)
+- [Lifecycle (launch / sideload / deep-link)](#lifecycle)
+- [Readiness & health](#readiness--health)
+- [Polling helpers](#polling-helpers)
+- [Log access](#log-access)
+- [Parsers](#parsers)
+- [Rate limits & retries](#rate-limits--retries)
+- [Errors thrown](#errors-thrown)
+
+## Construction
+
+### `RkClient`
+
+```ts
+class RkClient {
+    readonly deviceIp: string;
+    readonly keyDelay: number;
+
+    constructor(opts: RkClientOptions);
+
+    getServerUrl(): string;
+}
+```
+
+```ts
+interface RkClientOptions {
+    /** IPv4 of the target device. REQUIRED for `new RkClient`. */
+    deviceIp?: string;
+    /** Inter-key delay for `keysequence` (ms). Default `100`. */
+    keyDelay?: number;
+    /** Per-request ECP timeout in ms (captures use their own longer timeout). Default `5000`. */
+    requestTimeoutMs?: number;
+    /** Override per-category minimum queue intervals (ms). For tests only. */
+    intervals?: Partial<Record<EcpCategory, number>>;
+    /** `rk server` base URL. Resolution: opts → `RK_SERVER_URL` → `.roku/rk-server.json` → `http://localhost:3737/api`. Normalized to end with `/api` (no trailing slash) regardless of source. */
+    serverUrl?: string;
+    /** Pre-built `LogSessionLike` — reserved for tests, ignored by normal callers. */
+    logSession?: LogSessionLike;
+}
+
+type EcpCategory =
+    | "query-appui"
+    | "query-device-info"
+    | "query-active-app"
+    | "keypress"
+    | "launch"
+    | "capture";
+```
+
+**Example — direct construction.**
+
+```ts
+import { RkClient } from "@roku-sdk/device-test-client";
+
+const client = new RkClient({
+    deviceIp: "192.168.1.42",
+    keyDelay: 150
+});
+```
+
+Call `new RkClient({})` without `deviceIp` to see `RkClientError(RK_DEVICE_IP_UNRESOLVED)`
+— the error message tells you to use `createDefaultClient()` instead.
+
+### `createDefaultClient`
+
+```ts
+function createDefaultClient(opts?: RkClientOptions): RkClient;
+```
+
+Single source of truth for env-driven construction. Resolves `deviceIp`
+from `opts.deviceIp` → `RK_DEVICE_IP` → `test-results/.device-ip`
+(written by `globalSetup`). If `test-results/device-env.json` already
+exists, the cache is seeded so `client.cachedDeviceInfo()` returns
+immediately.
+
+**Example — worker-side wiring.**
+
+```ts
+import { createDefaultClient } from "@roku-sdk/device-test-client";
+
+const client = createDefaultClient();       // Uses globalSetup-resolved IP.
+const client2 = createDefaultClient({ keyDelay: 200 });
+```
+
+**Common pitfall.** `createDefaultClient` is synchronous. If you construct
+it from a host-side script that has not yet run `globalSetup` and has no
+`RK_DEVICE_IP`, the call throws. In `globalSetup` itself, pass
+`deviceIp` explicitly (see `createGlobalSetup` in
+`[jest-integration.md](jest-integration.md)`).
+
+---
+
+## ECP queries
+
+### `queryAppUi`
+
+```ts
+queryAppUi(): Promise<AppUiNode>;
+```
+
+```ts
+interface AppUiNode {
+    tag: string;
+    attrs: Record<string, string>;
+    bounds: { x: number; y: number; width: number; height: number };
+    focused: boolean;
+    children: AppUiNode[];
+}
+```
+
+Fetches the full SceneGraph tree via `/query/app-ui`. Rate-limited at
+200 ms between successful calls. The ECP `name=` attribute is mirrored
+into `attrs.id` at parse time so predicates can use the canonical `id`
+selector (see [DOM assertions](dom-assertions.md#id--name-alias)).
+
+**Example.**
+
+```ts
+const tree = await client.queryAppUi();
+console.log(tree.tag);              // typically "app-ui"
+console.log(tree.children.length);
+```
+
+### `queryDeviceInfo` / `cachedDeviceInfo` / `seedDeviceInfo`
+
+```ts
+queryDeviceInfo(): Promise<DeviceInfo>;
+cachedDeviceInfo(): DeviceInfo | null;
+seedDeviceInfo(info: DeviceInfo): void;
+resetCache(): void;
+```
+
+```ts
+interface DeviceInfo {
+    modelName: string;
+    modelNumber: string;
+    modelFamily: string;
+    deviceClass: string;          // form-factor: "tv" | "stick" | "player"
+    firmwareVersion: string;
+    videoMode: string;            // e.g. "1080p60"
+    locale: string;
+    country: string;
+    libraries: Record<string, string>;
+}
+```
+
+`queryDeviceInfo` always hits the wire (ECP `/query/device-info`) and
+caches the result. `cachedDeviceInfo` is free and returns `null` before
+the first query. `seedDeviceInfo` primes the cache from an external
+source (what `createDefaultClient` does with `device-env.json`).
+
+**Example — cache-aware read.**
+
+```ts
+const info = client.cachedDeviceInfo() ?? (await client.queryDeviceInfo());
+if (info.videoMode.startsWith("1080p")) {
+    // use full-HD baselines
+}
+```
+
+### `queryActiveApp`
+
+```ts
+queryActiveApp(): Promise<ActiveAppInfo>;
+
+interface ActiveAppInfo {
+    id: string;      // "dev" for sideloaded, channel id for published, "" on home
+    title: string;   // "Roku" on home
+    type: string;    // e.g. "appl"
+}
+```
+
+**Example.**
+
+```ts
+const active = await client.queryActiveApp();
+expect(active.id).toBe("dev");
+```
+
+### `captureScreenshot`
+
+```ts
+captureScreenshot(): Promise<Buffer>;
+```
+
+Raw PNG bytes from `/capture-screen/png`. Rate-limited at 500 ms between
+captures. For meaningful pixel comparisons, use
+`[captureStableScreenshot](#capturestablescreenshot)` which polls until
+two successive frames are identical.
+
+**Example.**
+
+```ts
+import { writeFileSync } from "node:fs";
+writeFileSync("debug.png", await client.captureScreenshot());
+```
+
+---
+
+## Input
+
+### `keypress`
+
+```ts
+keypress(key: string): Promise<void>;
+```
+
+Sends exactly one ECP keypress. The key name is validated before the
+queue is entered — typos throw `RkClientError(ECP_INVALID_KEY)`
+immediately. Accepts any Roku key (`"Up"`, `"Down"`, `"Select"`,
+`"Home"`, `"Back"`, etc.).
+
+**Example.**
+
+```ts
+await client.keypress("Select");
+```
+
+### `keysequence`
+
+```ts
+keysequence(keys: string[], opts?: KeySequenceOptions): Promise<void>;
+
+interface KeySequenceOptions {
+    /** Inter-key delay (ms) between the end of one keypress and the start of the next. Defaults to `client.keyDelay`. */
+    keyDelay?: number;
+}
+```
+
+Validates every key up-front so a typo at index 7 fails before index 0
+goes out. The delay is applied between keys — not before the first or
+after the last.
+
+**Example.**
+
+```ts
+await client.keysequence(["Down", "Down", "Right", "Select"]);
+await client.keysequence(["Up", "Up"], { keyDelay: 250 });
+```
+
+---
+
+## Lifecycle
+
+### `launch`
+
+```ts
+launch(opts?: LaunchOptions): Promise<void>;
+
+interface LaunchOptions {
+    /** ECP channel id. Defaults to `"dev"`. */
+    channelId?: string;
+    /** Deep-link params for an **already-running** channel (reliable path). */
+    deepLink?: Record<string, string>;
+    /** Readiness gate timeout (ms). Defaults to 10_000. */
+    readinessTimeout?: number;
+    /** Semantic readiness predicate (see `BuildAndDeployOptions.readyNode`). */
+    readyNode?: NodePredicate;
+}
+```
+
+Launches a channel via `/launch/{channelId}`, then blocks on the shared
+readiness + dialog gate. `launch` is the **reliable** path for
+deep-link delivery when the channel is already installed — use it from
+`beforeEach` to return the app to a known state between tests. For
+cold sideloads that must land deep-linked, use
+`[buildAndLaunchWithParams](#buildandlaunchwithparams)`.
+
+**Example — re-open to a specific state.**
+
+```ts
+beforeEach(async () => {
+    await client.launch({
+        deepLink: { contentId: "home" },
+        readyNode: { attr: { id: "home-root" } }
+    });
+});
+```
+
+**Auto-launch tolerance.** For a plain `dev` launch (no `deepLink`) the
+POST races the launch the firmware already started for the sideloaded
+build, so its verdict is not authoritative: a timeout, a `fetch failed`
+blip, a 5xx from the busy launcher (`503 Service Unavailable` on
+virtualized hosts), or a 404 from firmware that does not serve `/launch/dev` at all
+are all tolerated, and the readiness gate decides. Any other `launch`
+call — a named `channelId`, or one carrying `deepLink` params — treats
+the POST status as final, because nothing else can prove those params
+were delivered. `[buildAndLaunchWithParams](#buildandlaunchwithparams)`
+is the one exception: its params POST tolerates the same race errors
+(not a 404) because its mandatory params-ack log proves delivery.
+
+### `buildAndDeploy`
+
+```ts
+buildAndDeploy(appPath: string, opts?: BuildAndDeployOptions): Promise<void>;
+
+interface BuildAndDeployOptions {
+    deepLink?: Record<string, string>;        // see "Common pitfall" below
+    readinessTimeout?: number;                 // ms, default 10_000
+    channelId?: string;                         // default "dev"
+    deviceSelector?: string;                    // override .roku/ active device
+    readyNode?: NodePredicate;                  // semantic readiness gate
+}
+```
+
+Builds the app at `appPath` (expects a `roku-config.ts` next to it),
+sideloads the pkg-dir, launches, and blocks until the app is
+interactive. Host-side build failures throw `BuildFailedError` (the
+device is not marked unhealthy — the next test may succeed after a
+code fix). Device-side failures throw `DeployFailedError` and flip the
+health flag so `beforeEach` in the next test aborts fast.
+
+**Minimal example.**
+
+```ts
+await client.buildAndDeploy("apps/smoke");
+```
+
+**Realistic example.**
+
+```ts
+await client.buildAndDeploy("apps/grid", {
+    readyNode: { attr: { id: "grid-title", text: "Featured" } },
+    readinessTimeout: 20_000
+});
+```
+
+**Common pitfall — cold-sideload deep-link race.** `buildAndDeploy`'s
+`deepLink` option is best-effort: on a fresh sideload the Install ECP
+endpoint auto-launches without params, and the follow-up launch-with-
+params POST frequently arrives before the app's
+`setLaunchParamsUpdateHandler` has registered. Firmware drops it
+silently. Use `buildAndLaunchWithParams` below when correctness
+depends on a specific deep-linked landing state.
+
+### `buildAndLaunchWithParams`
+
+```ts
+buildAndLaunchWithParams(
+    appPath: string,
+    deepLink: Record<string, string>,
+    opts: BuildAndLaunchWithParamsOptions
+): Promise<void>;
+
+interface BuildAndLaunchWithParamsOptions {
+    deviceSelector?: string;
+    channelId?: string;
+    readinessTimeout?: number;
+    readyNode?: NodePredicate;
+    /** Required. Regex the app emits once its launch-params handler is live. */
+    runtimeReadyLogPattern: RegExp;
+    runtimeReadyTimeout?: number;       // ms, default 5_000
+    /** Required. Regex the app emits once params propagate through the reactive graph. */
+    paramsAckLogPattern: RegExp;
+    paramsAckTimeout?: number;          // ms, default 5_000
+}
+```
+
+Implements the three-step dance the cold-sideload race requires:
+
+1. sideload + auto-launch without params,
+2. `waitForLog(runtimeReadyLogPattern)` — proves the handler is live,
+3. `/launch/{channelId}?…` with params + `waitForLog(paramsAckLogPattern)` —
+  proves the reactive graph observed them.
+
+Both log patterns are **required** — type-system enforcement that the
+caller thought about observability.
+
+**Example.**
+
+```ts
+await client.buildAndLaunchWithParams(
+    "apps/player",
+    { contentId: "abc-123", startPos: "45" },
+    {
+        readyNode: { attr: { id: "player-ready" } },
+        runtimeReadyLogPattern: /launch-params-handler: ready/,
+        paramsAckLogPattern: /launch-params: contentId=abc-123/
+    }
+);
+```
+
+---
+
+## Readiness & health
+
+### `assertAppAlive`
+
+```ts
+assertAppAlive(context?: unknown): Promise<void>;
+```
+
+Single-shot "is the app still on screen?" probe. Throws
+`AppCrashedError` if `/query/active-app` reports the home screen. Every
+polling helper in the SDK (`waitForNode`, `waitForLog`,
+`captureStableScreenshot`) invokes this between iterations so crashes
+surface immediately instead of consuming the full timeout.
+
+**Example.**
+
+```ts
+await client.buildAndDeploy("apps/flaky");
+// ... do some user interactions ...
+await client.assertAppAlive();  // fail fast if the app crashed
+```
+
+### `detectSystemDialog`
+
+```ts
+static detectSystemDialog(tree: AppUiNode): SystemDialogNode | null;
+detectSystemDialog(tree: AppUiNode): SystemDialogNode | null;
+
+interface SystemDialogNode {
+    tag: string;                // e.g. "StandardMessageDialog"
+    title: string;              // attrs.title if present
+    node: AppUiNode;
+}
+```
+
+Static and instance form of the same predicate — scans root-level
+children for one of the known obstructing dialog tags (`Dialog`,
+`StandardMessageDialog`, `StandardDialog`, `ProblemDialog`,
+`KeyboardDialog`, `PinEntryDialog`). Returns the first match or `null`.
+
+`buildAndDeploy` and `launch` call this automatically after readiness
+and fail the deploy with `DeployFailedError` when a dialog is present.
+Direct callers typically only need it for bespoke recovery flows.
+
+**Example.**
+
+```ts
+const tree = await client.queryAppUi();
+const dialog = RkClient.detectSystemDialog(tree);
+if (dialog) {
+    console.warn(`Obstructing dialog: ${dialog.tag} ("${dialog.title}")`);
+}
+```
+
+---
+
+## Polling helpers
+
+### `waitForNode`
+
+```ts
+waitForNode(predicate: NodePredicate, opts: WaitOptions): Promise<AppUiNode>;
+
+interface NodePredicate {
+    tag?: string;
+    attr?: Record<string, string>;
+    focused?: boolean;
+}
+
+interface WaitOptions {
+    timeout: number;        // ms, required
+    interval?: number;      // ms between iteration starts, default 200
+}
+```
+
+Polls `queryAppUi()` until `predicate` matches. Each iteration calls
+`assertAppAlive` first, then fetches a fresh tree, then attempts the
+match. `interval` is a **minimum** gap between iteration starts —
+iterations that already took ≥ `interval` loop without extra sleep.
+
+Throws `WaitForNodeTimeoutError` (with `context.lastTree` for
+diagnostics) on timeout, or `AppCrashedError` if the app crashed
+mid-wait.
+
+**Example — first-render wait.**
+
+```ts
+await client.waitForNode(
+    { attr: { id: "grid-item", text: "The Office" } },
+    { timeout: 10_000 }
+);
+```
+
+**Example — focus wait with custom interval.**
+
+```ts
+await client.waitForNode(
+    { focused: true, attr: { id: "play-button" } },
+    { timeout: 3_000, interval: 100 }
+);
+```
+
+### `captureStableScreenshot`
+
+```ts
+captureStableScreenshot(opts: CaptureStableOptions): Promise<Buffer>;
+
+interface CaptureStableOptions {
+    timeout: number;
+    interval?: number;          // default 500 (matches the ECP queue gap)
+    mask?: MaskRegion[];
+}
+
+interface MaskRegion {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+```
+
+Polls until two successive captures are pixel-identical outside any
+`mask` regions, then returns the **newer** PNG. Calls `assertAppAlive`
+before each capture. On timeout throws `ScreenshotNotStableError` with
+`iterations`, `lastDiffCount`, `firstDiffPoint`, `maskedRegions`, and
+`lastPng`.
+
+**Example.**
+
+```ts
+const png = await client.captureStableScreenshot({
+    timeout: 5_000,
+    mask: [{ x: 0, y: 0, width: 1920, height: 80 }]   // blank the top bar
+});
+```
+
+See [Screenshot assertions](screenshot-assertions.md) for the
+`expectScreenshot` counterpart.
+
+---
+
+## Log access
+
+The log-assertion API is fully documented in
+[log-assertions.md](log-assertions.md). The method set exposed
+directly on `RkClient`:
+
+```ts
+ensureLogSession(): Promise<void>;
+disposeLogSession(): void;
+logBuffer(): LogBufferLike;
+recentLogLines(n?: number): Array<{ seq: number; line: LogLine }>;
+
+logPosition(): LogPosition;
+logs(opts: { since: LogPosition }): Promise<LogLine[]>;
+waitForLog(pattern: RegExp, opts: LogQueryOptions): Promise<LogLine>;
+expectNoLog(pattern: RegExp, opts: LogQueryOptions): Promise<void>;
+
+interface LogQueryOptions {
+    since: LogPosition;
+    timeout?: number;       // for waitForLog
+    window?: number;        // for expectNoLog (alias: timeout)
+}
+
+type LogPosition = string;   // opaque decimal seq
+type LogLine = string;
+```
+
+**Causality example** — the canonical pattern for proving a keypress
+caused a log line to appear:
+
+```ts
+const pos = client.logPosition();                           // SYNC — take baseline
+await client.keypress("Select");
+const line = await client.waitForLog(/select-pressed/, {
+    since: pos,
+    timeout: 2_000
+});
+```
+
+**Common pitfall — `logPosition` must come before the causing action.**
+Grabbing it after `keypress` means a fast-emitting log line can land
+while `await keypress` is still in flight, making the `since` baseline
+skip past it. The method is synchronous precisely so you can capture
+it without a microtask boundary.
+
+---
+
+## Parsers (internal / deep-import only)
+
+`parseBounds(raw)` and `parseDeviceInfo(raw)` are used internally by
+`RkClient.queryAppUi` and `RkClient.queryDeviceInfo` to turn Roku's
+wire format into the typed shapes this page documents. They were
+exported from the package root in v1.x but were **removed from the
+barrel** in v2.0.0 — normal consumers get the parsed values directly
+from the client methods (`(await client.queryAppUi()).bounds`,
+`await client.queryDeviceInfo()`), which is what the tests in this
+repository already do.
+
+Reporters that post-process raw `/query/device-info` XML without
+going through an `RkClient` instance can still reach them as
+deep imports:
+
+```ts
+// DEEP IMPORT — not covered by SemVer.
+import { parseBounds, parseDeviceInfo } from "@roku-sdk/device-test-client/src/client/parsers";
+```
+
+If your consumer needs either on a stable public path, open an issue
+so we can promote a dedicated export.
+
+---
+
+## Rate limits & retries
+
+
+| Category            | Interval (ms) | Notes                                                    |
+| ------------------- | ------------- | -------------------------------------------------------- |
+| `query-appui`       | 200           | Matches the `waitForNode` polling cadence.               |
+| `query-device-info` | 0             | Cached after first fetch.                                |
+| `query-active-app`  | 0             | Crash probes fire on every polling tick.                 |
+| `keypress`          | 0             | Serialised via the queue; `keysequence` adds `keyDelay`. |
+| `launch`            | 0             | One-shot per test; pacing irrelevant.                    |
+| `capture`           | 500           | Expensive to render + encode server-side.                |
+
+
+All intervals are **gap-based** — measured between the *end* of one
+call and the *start* of the next. Overridable for tests via
+`RkClientOptions.intervals`.
+
+**Retries.** Transient ECP failures (HTTP 5xx, network timeout, generic
+`fetch failed`) are retried exactly once after a 500 ms backoff inside
+the same queue slot. The second failure propagates verbatim as a
+`ToolingError` (from `@roku-sdk/tooling`) so its `code` field stays
+queryable — the SDK does not silently wrap it into an `RkClientError`.
+
+---
+
+## Errors thrown
+
+Symbols below are the **class names**; full definitions and recovery
+advice live in `[errors.md](errors.md)`.
+
+- Construction — `RkClientError(RK_DEVICE_IP_UNRESOLVED)`
+- Query parsing — `RkClientError(ECP_APPUI_PARSE_FAILED)`,
+`RkClientError(ECP_ACTIVEAPP_PARSE_FAILED)`
+- Invalid key — `RkClientError(ECP_INVALID_KEY)`
+- Build / deploy / launch — `BuildFailedError`, `DeployFailedError`,
+`DeviceUnhealthyError` (cascade guard)
+- Readiness / health — `AppCrashedError`,
+`DeployFailedError({ reason: "readiness-timeout" | "never-left-home" | "crashed-after-ready" | "system-dialog" })`.
+The `never-left-home` reason latches the device **fatal**
+(`markDeviceFatal` / `isDeviceFatal` / `getFatalReason`) — an
+unrecoverable-on-this-VM wedge that disables recovery and fast-skips
+downstream deploys; see [errors.md](errors.md#fatal-device-wedge)
+- Polling — `WaitForNodeTimeoutError`, `AppCrashedError`,
+`ScreenshotNotStableError`
+- Logs (see [log-assertions.md](log-assertions.md)) —
+`WaitForLogTimeoutError`, `UnexpectedLogError`, `LogStreamGapError`,
+`LogBufferOverflowError`, `LogSessionStartError`
+