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

package/docs/errors.md

@@ -0,0 +1,544 @@
+# Error reference
+
+Every error class exported from `@roku-sdk/device-test-client` is
+listed below with its declaration, context fields, typical causes,
+and an `instanceof`-based narrowing example.
+
+All errors extend `Error`, set a unique `.name` literal, and attach
+structured context fields so CI reporters can render "id / title /
+reason" columns without parsing the message string.
+
+- [How to narrow errors](#how-to-narrow-errors)
+- [RkClient / construction](#rkclient--construction)
+- [Build / deploy](#build--deploy)
+- [Lifecycle health](#lifecycle-health)
+- [DOM assertions](#dom-assertions)
+- [Screenshot assertions](#screenshot-assertions)
+- [Log assertions](#log-assertions)
+- [Preconditions](#preconditions)
+
+## How to narrow errors
+
+Use `instanceof` — every error class is exported from the package
+root:
+
+```ts
+import {
+    WaitForNodeTimeoutError,
+    AppCrashedError
+} from "@roku-sdk/device-test-client";
+
+try {
+    await client.waitForNode({ attr: { id: "tile" } }, { timeout: 3_000 });
+} catch (err) {
+    if (err instanceof AppCrashedError) {
+        console.log(`App crashed; active app: ${err.activeApp.title}`);
+        throw err;
+    }
+    if (err instanceof WaitForNodeTimeoutError) {
+        console.log(`Last tree had ${err.context.lastTree?.children.length} children`);
+        throw err;
+    }
+    throw err;
+}
+```
+
+---
+
+## RkClient / construction
+
+### `RkClientError`
+
+```ts
+class RkClientError extends Error {
+    readonly name: "RkClientError";
+    readonly code?: string;
+}
+```
+
+Thrown for framework-internal failures that are **not** wire /
+transport errors. Known codes:
+
+
+| code                                | Thrown by                                              | Typical fix                                             |
+| ----------------------------------- | ------------------------------------------------------ | ------------------------------------------------------- |
+| `RK_DEVICE_IP_UNRESOLVED`           | `new RkClient({})` with no IP; `resolveActiveDeviceIp` | Set `RK_DEVICE_IP` or `rk device add <ip>`              |
+| `ECP_INVALID_KEY`                   | `keypress`, `keysequence`                              | Use a valid Roku key name                               |
+| `ECP_APPUI_PARSE_FAILED`            | `queryAppUi`                                           | Firmware bug / malformed XML; check `rk device ping`    |
+| `ECP_ACTIVEAPP_PARSE_FAILED`        | `queryActiveApp`                                       | Firmware bug / malformed XML                            |
+| `PRECONDITION_NO_DEVICE_INFO`       | `requirePrecondition` before cache populated           | Call `installDeviceTestHooks` / `queryDeviceInfo` first |
+| `PRECONDITION_INVALID_SEMVER_RANGE` | `requirePrecondition` / `itOnDevice` with bad range    | Fix the semver range syntax                             |
+
+
+Wire errors propagate as `ToolingError` from `@roku-sdk/tooling`
+without wrapping — their `code` field stays queryable downstream.
+
+---
+
+## Build / deploy
+
+### `BuildFailedError`
+
+```ts
+class BuildFailedError extends Error {
+    readonly name: "BuildFailedError";
+    readonly appPath: string;
+    readonly cause?: unknown;
+}
+```
+
+Thrown by `buildAndDeploy` when the host-side build (TypeScript
+compile, manifest parse, bundler) fails. **Does NOT mark the device
+unhealthy** — the next test can succeed after a code fix without
+device intervention.
+
+```ts
+try {
+    await client.buildAndDeploy("apps/broken");
+} catch (err) {
+    if (err instanceof BuildFailedError) {
+        console.error(`Build failed for ${err.appPath}:`, err.cause);
+    }
+}
+```
+
+### `DeployFailedError`
+
+```ts
+class DeployFailedError extends Error {
+    readonly name: "DeployFailedError";
+    readonly context: {
+        appPath?: string;
+        deviceIp?: string;
+        diagnostics?: string;
+        lastTree?: AppUiNode;
+        lastActiveApp?: ActiveAppInfo;
+        dialog?: SystemDialogNode;
+        phase?: "launch" | "readiness" | "sideload" | "config";
+        expectedChannelId?: string;
+        reason?: string;
+        cause?: unknown;
+    };
+}
+```
+
+Thrown by `buildAndDeploy` / `launch` / `buildAndLaunchWithParams`
+when the device-side step fails. Every instance is paired with
+`markDeviceUnhealthy` so the cascade guard aborts subsequent tests.
+
+Known `context.reason` values: `"readiness-timeout"`,
+`"never-left-home"`, `"crashed-after-ready"`, `"system-dialog"`,
+`"sideload-rejected"`.
+
+`"never-left-home"` is special. It means the device answered ECP for
+the entire readiness budget but never foregrounded the sideloaded
+channel. On a device that has not been seen foregrounding a channel
+at all, that is an **unrecoverable-on-this-VM** condition (a wedged
+device host): it latches the device **fatal** (`markDeviceFatal`),
+not merely unhealthy, so downstream deploys fast-skip and the
+recovery `beforeEach` refuses to revive it. See
+[Fatal device wedge](#fatal-device-wedge) below.
+
+Once any deploy has put a channel on screen, the same observation
+carries the softer meaning — a launch slower than the budget looks
+identical from inside one deploy — so it only flips soft health and
+the deploy-guard retries that deploy. The `reason` tag reports what
+was observed either way; only the verdict differs.
+
+---
+
+## Lifecycle health
+
+### `AppCrashedError`
+
+```ts
+class AppCrashedError extends Error {
+    readonly name: "AppCrashedError";
+    readonly activeApp: ActiveAppInfo;
+    readonly context?: unknown;
+}
+```
+
+Thrown by `assertAppAlive` (and every polling helper that calls it)
+when `/query/active-app` reports the home screen. `activeApp.title`
+is `"Roku"` on the home screen.
+
+```ts
+try {
+    await client.waitForNode(…);
+} catch (err) {
+    if (err instanceof AppCrashedError) {
+        console.error("app crashed:", err.activeApp);
+    }
+}
+```
+
+### `DeviceUnhealthyError`
+
+```ts
+class DeviceUnhealthyError extends Error {
+    readonly name: "DeviceUnhealthyError";
+    readonly reason: string;
+}
+```
+
+Thrown by `installDeviceTestHooks`'s `beforeEach` when a previous
+test flipped the health flag. Aborts the remaining tests in the
+worker fast so reviewers aren't wading through 50 cascade failures.
+
+### Fatal device wedge
+
+There are two device-health states, exposed as separate helper sets:
+
+| Concept | Set | Reset by | Models |
+|---------|-----|----------|--------|
+| Soft health | `markDeviceUnhealthy` / `isDeviceHealthy` / `getUnhealthyReason` | `resetDeviceHealth()` | **Recoverable** fault (crash/reboot the device returns from). |
+| Fatal latch | `markDeviceFatal` / `isDeviceFatal` / `getFatalReason` | *(process-lifetime; not cleared by `resetDeviceHealth`)* | **Unrecoverable-on-this-VM** fault — device answers ECP/installer but won't foreground a sideloaded channel. |
+
+`markDeviceFatal` also flips the soft flag, so the existing cascade
+keeps firing and you never need to call both. Currently only
+`DeployFailedError({ reason: "never-left-home" })` latches fatal, and
+only on a device with no record of foregrounding a channel. A deploy
+that put one on screen calls `markChannelForegrounded`, which keeps
+later stalled launches on that VM soft — the latch costs the whole
+shard plus a lease recycle, so it is reserved for the case the
+device's own history does not contradict.
+
+Consequences once fatal is latched (single `--runInBand` process):
+
+- The recovery `beforeEach` in `installDeviceTestHooks` does **not**
+  attempt `waitForDeviceOnline` — a wedged VM still answers it, which
+  would falsely "recover" and re-run the test. It throws
+  `DeviceUnhealthyError` immediately with a "recycle the instance"
+  message.
+- `installDeployGuard` (in `device-tests/`) short-circuits: remaining
+  suites skip their deploy entirely instead of burning the full
+  retry × backoff budget on a dead instance. The device host
+  must be recycled at the lease/runner layer.
+
+---
+
+## DOM assertions
+
+### `NodeNotFoundError`
+
+```ts
+class NodeNotFoundError extends Error {
+    readonly name: "NodeNotFoundError";
+    readonly predicate: NodePredicate;
+    readonly treeSummary: string;   // truncated pseudo-XML listing
+}
+```
+
+Thrown by `findNode` / `findFocusedNode` / `expectFocused`. The tree
+summary is truncated to the first 3 levels / 2 000 chars so the
+reporter stays scannable.
+
+### `FocusedNodeMismatchError`
+
+```ts
+class FocusedNodeMismatchError extends Error {
+    readonly name: "FocusedNodeMismatchError";
+    readonly expectedPredicate: NodePredicate;
+    readonly actualFocusedNode: string;   // one-line summary of the focused node
+}
+```
+
+Thrown by `expectFocused` when a node IS focused but doesn't match
+the predicate.
+
+### `WaitForNodeTimeoutError`
+
+```ts
+class WaitForNodeTimeoutError extends Error {
+    readonly name: "WaitForNodeTimeoutError";
+    readonly context: {
+        predicate: NodePredicate;
+        timeoutMs: number;
+        lastTree: AppUiNode | null;
+    };
+}
+```
+
+Thrown by `client.waitForNode` on timeout. `context.lastTree` is the
+final snapshot the polling loop observed.
+
+### `BaselineMissingError`
+
+```ts
+class BaselineMissingError extends Error {
+    readonly name: "BaselineMissingError";
+    readonly path: string;               // absolute baseline path
+    readonly resolution: string;         // "hd" | "fhd"
+    readonly videoMode: string | undefined;
+}
+```
+
+Thrown by `expectTree(…).toMatchBaseline(path)` when the file does
+not exist and `UPDATE_BASELINES=1` was not set.
+
+### `BaselineResolutionError`
+
+```ts
+class BaselineResolutionError extends Error {
+    readonly name: "BaselineResolutionError";
+    readonly context: {
+        videoMode?: string;
+        reason: "unsupported-videoMode" | "no-active-client-and-no-env" | "invalid-env-value";
+    };
+}
+```
+
+Thrown when `hd` / `fhd` subdirectory cannot be determined. See
+[baselines.md](baselines.md#resolution-routing) for the precedence
+table.
+
+### `TreeMismatchError`
+
+```ts
+class TreeMismatchError extends Error {
+    readonly name: "TreeMismatchError";
+    readonly context: {
+        baselinePath: string;
+        firstDiff: string;               // JSONPath (e.g. "$.children[0].attrs.opacity")
+        expectedSnippet: string;         // truncated baseline snippet
+        actualSnippet: string;           // truncated actual snippet
+    };
+}
+```
+
+Thrown by `expectTree(…).toMatchBaseline(…)` when the tree diverges
+from the baseline.
+
+---
+
+## Screenshot assertions
+
+### `ScreenshotNotStableError`
+
+```ts
+class ScreenshotNotStableError extends Error {
+    readonly name: "ScreenshotNotStableError";
+    readonly timeoutMs: number;
+    readonly iterations: number;
+    readonly lastDiffCount: number;
+    readonly maskedRegions: MaskRegion[];
+    readonly firstDiffPoint?: { x: number; y: number };
+    readonly lastPng?: Buffer;
+
+    toJSON(): Record<string, unknown>;   // omits lastPng
+}
+```
+
+Thrown by `captureStableScreenshot` on timeout. `lastPng` is the most
+recent capture; `toJSON` explicitly omits it so
+`JSON.stringify(err)` doesn't balloon the CI log.
+
+### `ScreenshotBaselineMissingError`
+
+```ts
+class ScreenshotBaselineMissingError extends Error {
+    readonly name: "ScreenshotBaselineMissingError";
+    readonly baselinePath: string;
+    readonly resolution: "hd" | "fhd";
+}
+```
+
+Thrown by `expectScreenshot(…).toMatchBaseline(…)` when the baseline
+PNG does not exist and `UPDATE_BASELINES=1` was not set.
+
+### `ScreenshotDimensionsMismatchError`
+
+```ts
+class ScreenshotDimensionsMismatchError extends Error {
+    readonly name: "ScreenshotDimensionsMismatchError";
+    readonly context: {
+        baselinePath: string;
+        resolution: "hd" | "fhd";
+        baseline: { w: number; h: number };
+        actual:   { w: number; h: number };
+    };
+}
+```
+
+Thrown when baseline and actual PNGs have different sizes. No diff
+PNG is written in this path.
+
+### `ScreenshotMismatchError`
+
+```ts
+class ScreenshotMismatchError extends Error {
+    readonly name: "ScreenshotMismatchError";
+    readonly context: {
+        baselinePath: string;
+        resolution: "hd" | "fhd";
+        actual: { w: number; h: number };
+        mismatchedPixels: number;
+        totalPixels: number;
+        ratio: number;
+        threshold: number;
+        diffPath: string;
+        alignment?: { dx: number; dy: number };
+    };
+}
+```
+
+Thrown when the pixel-mismatch ratio exceeds the threshold. The diff
+PNG is **always** written to `diffPath` before the error is thrown
+— reporters that swallow the error can still attach it.
+
+`alignment` appears only when an `alignTolerance` search found a
+translation that scored better than the untranslated comparison, and
+names the offset the reported `ratio` was measured at. A non-zero
+`alignment` on a failure means the surface both moved and changed.
+
+### `ScreenshotMaskError`
+
+```ts
+class ScreenshotMaskError extends Error {
+    readonly name: "ScreenshotMaskError";
+    readonly context: {
+        region: MaskRegion;
+        canvas: { w: number; h: number };
+        reason: "out-of-bounds" | "zero-area";
+    };
+}
+```
+
+Thrown for malformed `MaskRegion` values. Partial overlap is NOT an
+error — those regions are clamped silently.
+
+### `ScreenshotAlignToleranceError`
+
+```ts
+class ScreenshotAlignToleranceError extends Error {
+    readonly name: "ScreenshotAlignToleranceError";
+    readonly context: {
+        axis: "x" | "y";
+        value: number;
+        max: number;
+        reason: "not-an-integer" | "negative" | "over-cap";
+    };
+}
+```
+
+Thrown for a malformed `alignTolerance` axis. Unlike masks, nothing is
+clamped — a bad value is a caller bug, and it is validated before the
+comparison so it surfaces on passing runs too.
+
+---
+
+## Log assertions
+
+### `WaitForLogTimeoutError`
+
+```ts
+class WaitForLogTimeoutError extends Error {
+    readonly name: "WaitForLogTimeoutError";
+    readonly pattern: string;
+    readonly since: LogPosition;
+    readonly timeoutMs: number;
+    readonly linesChecked: number;
+    readonly recentLines: LogLine[];   // last 20 entries, capped
+}
+```
+
+Thrown by `waitForLog` on timeout. `linesChecked === 0` means no
+output at all reached the window, re-attach included. That narrows the
+cause but does not settle it: an app with nothing to log in those few
+seconds and a stream stalled at its far end look the same from here,
+and a short window around a quiet moment is the ordinary case. What it
+does rule out is a line lost between the server and this process,
+which the re-attach would have replayed. The message names both
+readings.
+
+### `UnexpectedLogError`
+
+```ts
+class UnexpectedLogError extends Error {
+    readonly name: "UnexpectedLogError";
+    readonly pattern: string;
+    readonly matchedLine: LogLine;
+    readonly since: LogPosition;
+}
+```
+
+Thrown by `expectNoLog` when the forbidden pattern matched a line in
+the window.
+
+### `LogStreamGapError`
+
+```ts
+class LogStreamGapError extends Error {
+    readonly name: "LogStreamGapError";
+    readonly gapStart: LogPosition;
+    readonly gapEnd: LogPosition;
+}
+```
+
+Thrown by `waitForLog` / `expectNoLog` / `logs` when an SSE
+reconnect gap overlaps the query range — the missing lines *might*
+have matched, so we fail rather than silently pass.
+
+### `LogBufferOverflowError`
+
+```ts
+class LogBufferOverflowError extends Error {
+    readonly name: "LogBufferOverflowError";
+    readonly requested: LogPosition;
+    readonly minAvailable: LogPosition;
+}
+```
+
+Thrown when a `since` position references lines the buffer has
+already evicted. Fix: raise `LogBuffer` cap, take fresh
+`logPosition()` more often, or shorten assertion windows.
+
+### `LogSessionStartError`
+
+```ts
+class LogSessionStartError extends Error {
+    readonly name: "LogSessionStartError";
+    readonly serverUrl: string;
+    readonly statusCode?: number;
+    readonly detail?: string;
+}
+```
+
+Thrown when `POST /logs/start` fails with an unrecoverable HTTP error
+or SSE attach fails before ready. A 400 "already active" response is
+NOT a failure — the session attaches to the existing server-side
+session.
+
+---
+
+## Preconditions
+
+### `PreconditionNotMetError`
+
+```ts
+class PreconditionNotMetError extends Error {
+    readonly name: "PreconditionNotMetError";
+    readonly field: string;
+    readonly expected: string;
+    readonly actual: string;
+    readonly reason: "mismatch" | "missing-device-info" | "not-implemented";
+}
+```
+
+Thrown by `requirePrecondition`. Registration-time wrappers
+(`itOnDevice` / `describeOnDevice`) catch this class and convert it
+to `it.skip()` / `describe.skip()`.
+
+### `PreconditionNotImplementedError`
+
+```ts
+class PreconditionNotImplementedError extends PreconditionNotMetError {
+    readonly name: "PreconditionNotImplementedError";
+    readonly feature: string;   // e.g. "library-version"
+}
+```
+
+Extends `PreconditionNotMetError` so the skip-converter handles it
+identically. Thrown when the caller asks for a field the SDK cannot
+query (today: `library`).

package/docs/examples/deep-link-cold-start.md

@@ -0,0 +1,85 @@
+# Example: deep-link cold start
+
+`buildAndLaunchWithParams` deploys an app and immediately launches it
+with ECP `contentId` / `mediaType` query parameters. The footgun: on a
+cold sideload the launch parameters race with the channel's own
+cold-start code path, so this example gates readiness on both a DOM
+node AND a log pattern.
+
+## Prerequisites
+
+- An app that logs a deterministic line once it has parsed the
+launch params (e.g. `deep-link:parsed contentId=<id>`).
+- A DOM node that appears only on the deep-linked screen
+(e.g. `id="detail-screen"`).
+
+## Test file
+
+```ts
+// tests/deep-link.test.ts
+import {
+    installDeviceTestHooks,
+    findNode
+} from "@roku-sdk/device-test-client";
+
+const ctx = installDeviceTestHooks();
+
+describe("deep link cold start", () => {
+    test("opens detail screen for the deep-linked content id", async () => {
+        const client = ctx.getClient();
+        const contentId = "movie-42";
+
+        const pos = client.logPosition();
+
+        await client.buildAndLaunchWithParams("apps/video", {
+            contentId,
+            mediaType: "movie",
+            readyNode: { attr: { id: "detail-screen" } },
+            readinessTimeout: 15_000
+        });
+
+        await client.waitForLog(
+            new RegExp(`deep-link:parsed contentId=${contentId}`),
+            { since: pos, timeout: 10_000 }
+        );
+
+        const tree = await client.queryAppUi();
+        const title = findNode(tree, {
+            tag: "Label",
+            attr: { id: "content-title" }
+        });
+        expect(title.attrs.text).toBeTruthy();
+    });
+});
+```
+
+## Walkthrough
+
+1. **Snapshot the log position first.** `logPosition()` is O(1) and
+  cheap. We capture it *before* starting the deploy so the log
+   window covers the entire launch sequence. If we snapshotted after
+   `buildAndLaunchWithParams`, the parse line would likely be older
+   than `since`, and `waitForLog` would timeout even though the app
+   did the right thing.
+2. **Deploy + launch with readiness.** `readyNode` polls
+  `queryAppUi` until the detail screen renders. `readinessTimeout`
+   is bumped to 15 s for cold-start scenarios where bundle hydration
+   dominates.
+3. **Await the app-level ack.** Readiness says the node appeared;
+  the log gate says the app actually parsed and respected the
+   contentId. Both together rule out the "generic home screen with a
+   label that happens to match" failure mode.
+4. **Verify content.** Trivial DOM assertion once the gates pass.
+
+## Common pitfalls
+
+- **Don't skip the `logPosition()` snapshot.** Every `waitForLog`
+without `since` scans from the buffer's minimum retained line,
+which on long-lived workers can be minutes old.
+- **Use readiness that is exclusive to the deep link.** A generic
+`id="main"` node is often present on the home screen too — the
+test will go green before the app actually navigated.
+- **If the app's log line is non-deterministic,** gate on DOM only
+and add a second `waitForNode` for a deep-link-only sub-element
+(e.g. a back button that only exists on detail screens).
+

package/docs/examples/focus-navigation.md

@@ -0,0 +1,81 @@
+# Example: focus navigation
+
+End-to-end test that drives a grid with directional keys and asserts
+the focused node after each step. Demonstrates the
+`keysequence` + `waitForNode({ focused: true })` idiom.
+
+## Prerequisites
+
+- An app with a navigable tile grid where each tile has a stable
+`id` attribute (e.g. `tile-0`, `tile-1`, `tile-2`).
+
+## Test file
+
+```ts
+// tests/focus-nav.test.ts
+import {
+    installDeviceTestHooks,
+    expectFocused,
+    findFocusedNode
+} from "@roku-sdk/device-test-client";
+
+const ctx = installDeviceTestHooks();
+
+describe("grid focus navigation", () => {
+    test("Right, Right, Down lands on tile-5", async () => {
+        const client = ctx.getClient();
+
+        await client.buildAndDeploy("apps/grid", {
+            readyNode: { attr: { id: "grid" } }
+        });
+
+        const initial = await client.queryAppUi();
+        expectFocused(initial, { attr: { id: "tile-0" } });
+
+        await client.keysequence(["Right", "Right"], { keyDelay: 200 });
+        const row1 = await client.waitForNode(
+            { focused: true, attr: { id: "tile-2" } },
+            { timeout: 2_000 }
+        );
+        expect(row1.attrs.id).toBe("tile-2");
+
+        await client.keypress("Down");
+        const focused = findFocusedNode(
+            await client.queryAppUi()
+        );
+        expect(focused?.attrs.id).toBe("tile-5");
+    });
+});
+```
+
+## Walkthrough
+
+1. `expectFocused(tree, predicate)` is synchronous — it asserts on
+  an already-captured tree. Use it when the previous action
+   guaranteed the device is steady (e.g. just after
+   `buildAndDeploy` readiness).
+2. `keysequence(["Right", "Right"], { keyDelay: 200 })` sends two
+  keys with a 200 ms pause between them. Override the default
+   100 ms (`DEFAULT_KEY_DELAY`) when your app's focus-change
+   animations are slow.
+3. `waitForNode({ focused: true, attr: { id: "tile-2" } })` polls
+  `queryAppUi` until BOTH the `focused: true` bit and the id
+   predicate match on the same node. This is more robust than
+   asserting each dimension separately because it tolerates the
+   frame where focus has moved off tile-0 but not yet landed on
+   tile-2.
+4. `findFocusedNode` returns `null` if nothing is focused — prefer
+  `expectFocused` when you want a thrown
+   `NodeNotFoundError` / `FocusedNodeMismatchError` instead.
+
+## Common pitfalls
+
+- **Don't sleep between keypresses.** Use `keyDelay` or
+`waitForNode({ focused: true, … })` rather than arbitrary
+`setTimeout` — it's slower on fast devices and flaky on slow ones.
+- **Assert node identity, not just "focused: true".** A test that
+only checks `{ focused: true }` passes as long as *some* node has
+focus, even if it's the wrong one.
+- **Beware RTL apps.** `Right` / `Left` key semantics flip; prefer
+`FocusChange` log lines when targeting locales with RTL layout.
+