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

package/docs/dom-assertions.md

@@ -0,0 +1,264 @@
+# DOM assertions
+
+DOM assertions operate on the `AppUiNode` tree returned by
+`client.queryAppUi()`. They come in two flavours: **pure tree helpers**
+(`findNode`, `findAllNodes`, `findFocusedNode`, `expectFocused`,
+`matchesPredicate`) that inspect a tree you already have, and
+**baseline comparison** (`expectTree(...).toMatchBaseline(...)`) that
+commits a canonical snapshot to disk.
+
+- [Core types](#core-types)
+- [Predicates](#predicates)
+- `[findNode](#findnode)`
+- `[findAllNodes](#findallnodes)`
+- `[findFocusedNode](#findfocusednode)`
+- `[expectFocused](#expectfocused)`
+- `[matchesPredicate](#matchespredicate)`
+- `[expectTree().toMatchBaseline(...)](#expecttreetomatchbaseline)`
+- [id / name alias](#id--name-alias)
+- [Errors thrown](#errors-thrown)
+
+## Core types
+
+```ts
+interface AppUiNode {
+    tag: string;                                            // e.g. "Label", "Group"
+    attrs: Record<string, string>;                          // every XML attribute, stringly-typed
+    bounds: { x: number; y: number; width: number; height: number };
+    focused: boolean;                                       // true if this node or a descendant has focus
+    children: AppUiNode[];                                  // document order
+}
+
+interface NodePredicate {
+    /** Exact tag match. */
+    tag?: string;
+    /** Partial attribute match — every listed key must `===` match. */
+    attr?: Record<string, string>;
+    /** Exact focus match. */
+    focused?: boolean;
+}
+```
+
+An empty predicate (`{}`) matches every node — this is documented
+behaviour, occasionally useful for "give me the first child of
+anything".
+
+## Predicates
+
+- `tag` — exact match against `node.tag`.
+- `attr` — each listed key/value is compared with `===`. Keys not in
+the predicate are ignored, so `{ attr: { id: "home" } }` matches
+regardless of any other attributes.
+- `focused` — matches whether the node (or an ancestor) is focused.
+- **Predicates are cumulative.** Listing `tag`, `attr`, and `focused`
+together ANDs them together.
+
+## `findNode`
+
+```ts
+function findNode(tree: AppUiNode, predicate: NodePredicate): AppUiNode;
+```
+
+Depth-first search returning the first match in document order. Throws
+`NodeNotFoundError` (with the predicate and a truncated tree summary)
+when nothing matches.
+
+**Example.**
+
+```ts
+import { findNode } from "@roku-sdk/device-test-client";
+
+const tree = await client.queryAppUi();
+const playButton = findNode(tree, { tag: "Button", attr: { id: "play" } });
+expect(playButton.attrs.text).toBe("Play");
+```
+
+## `findAllNodes`
+
+```ts
+function findAllNodes(tree: AppUiNode, predicate: NodePredicate): AppUiNode[];
+```
+
+Same traversal as `findNode`, but returns every match in document
+order. Zero matches is **not** an error — you get `[]`.
+
+**Example.**
+
+```ts
+import { findAllNodes } from "@roku-sdk/device-test-client";
+
+const rows = findAllNodes(tree, { tag: "RowListItem" });
+expect(rows).toHaveLength(10);
+expect(rows[0]!.attrs.title).toBe("Featured");
+```
+
+## `findFocusedNode`
+
+```ts
+function findFocusedNode(tree: AppUiNode): AppUiNode;
+```
+
+Returns the **leaf** focused node (SceneGraph propagates
+`focused="true"` up the ancestor chain — a naive DFS would hit the
+root `<screen>` instead of the actual input target). Throws
+`NodeNotFoundError("No focused node in tree")` if nothing is focused,
+which is a legitimate transient state during transitions.
+
+**Example.**
+
+```ts
+import { findFocusedNode } from "@roku-sdk/device-test-client";
+
+const focused = findFocusedNode(tree);
+console.log(focused.tag, focused.attrs.id);
+```
+
+## `expectFocused`
+
+```ts
+function expectFocused(tree: AppUiNode, predicate: NodePredicate): void;
+```
+
+Shorthand for "I don't care where in the tree it is, just assert the
+focused leaf matches this predicate". Throws `NodeNotFoundError`
+(nothing focused) or `FocusedNodeMismatchError` (focused node does not
+match).
+
+**Example.**
+
+```ts
+import { expectFocused } from "@roku-sdk/device-test-client";
+
+await client.keypress("Down");
+const tree = await client.queryAppUi();
+expectFocused(tree, { tag: "Button", attr: { id: "settings" } });
+```
+
+## `matchesPredicate`
+
+```ts
+function matchesPredicate(node: AppUiNode, predicate: NodePredicate): boolean;
+```
+
+Pure boolean — useful when you already have the node (e.g. from
+`waitForNode`) and want to re-assert against a different predicate
+without re-traversing.
+
+**Example.**
+
+```ts
+import { matchesPredicate } from "@roku-sdk/device-test-client";
+
+const node = await client.waitForNode({ attr: { id: "tile" } }, { timeout: 3_000 });
+if (matchesPredicate(node, { focused: true })) {
+    await client.keypress("Select");
+}
+```
+
+## `expectTree().toMatchBaseline()`
+
+```ts
+function expectTree(node: AppUiNode): TreeAssertion;
+
+interface TreeAssertion {
+    toMatchBaseline(baselinePath: string, opts?: TreeMatchOptions): Promise<void>;
+}
+
+interface TreeMatchOptions {
+    /** Attribute keys stripped recursively before serialization.
+     *  Useful for transient values (timestamps, uuids) that would otherwise churn the baseline. */
+    exclude?: readonly string[];
+    /** Node tags serialized as leaves — the node is asserted, its children are not. */
+    excludeChildrenOf?: readonly string[];
+}
+```
+
+Serializes the subtree to canonical JSON (attrs sorted, `bounds` and
+`focused` dropped as derived, children in DOM order), resolves
+`<baselineRoot>/<hd|fhd>/<baselinePath>`, and either:
+
+- **first run** (`UPDATE_BASELINES=1`) — creates the baseline
+atomically, after the CI guard passes (see
+`[baselines.md](baselines.md)`);
+- **normal run** — compares against the stored baseline and throws
+`TreeMismatchError` with `firstDiff` pointing at the first JSONPath-
+ish location where the trees diverge;
+- **baseline missing + no update flag** — throws
+`BaselineMissingError` with instructions to re-run with
+`UPDATE_BASELINES=1`.
+
+**Example — minimal.**
+
+```ts
+import { expectTree } from "@roku-sdk/device-test-client";
+
+const tree = await client.queryAppUi();
+await expectTree(tree).toMatchBaseline("home/initial.json");
+```
+
+**Example — with exclusions.**
+
+```ts
+await expectTree(tree).toMatchBaseline("player/playing.json", {
+    exclude: ["renderTracking", "lastRenderTimestamp"]
+});
+```
+
+**Example — native node with firmware-owned internals.** `Video`
+renders a whole subtree of native chrome (caption label, trick-play
+bar, spinner) that the app neither declares nor controls, and whose
+shape differs between OS builds — Roku OS 16 inserts a `WeelandChild`
+node that 15.3 does not have. Assert that the node is mounted without
+pinning its internals:
+
+```ts
+await expectTree(tree).toMatchBaseline("player/playing.json", {
+    excludeChildrenOf: ["Video"]
+});
+```
+
+**Example — subtree assertion.**
+
+```ts
+import { findNode, expectTree } from "@roku-sdk/device-test-client";
+
+const grid = findNode(tree, { attr: { id: "grid" } });
+await expectTree(grid).toMatchBaseline("grid/10-items.json");
+```
+
+**Common pitfall — running `UPDATE_BASELINES=1` in CI.** The CI guard
+(`assertBaselineUpdatesAllowed`) throws as soon as a baseline write
+would happen while `CI=true`. See
+`[baselines.md#ci-guard](baselines.md#ci-guard)`.
+
+## id / name alias
+
+Roku's `/query/app-ui` XML serialises the SceneGraph `id` field as a
+`name="..."` attribute. Every predicate that reads `attr.id` falls
+back to `attr.name` transparently, so you can continue to use the `id`
+selector that appears in your JSX / XML source without writing
+`name=` in tests:
+
+```ts
+findNode(tree, { attr: { id: "play" } });   // matches <button name="play" />
+findNode(tree, { attr: { name: "play" } }); // also matches — raw attribute still works
+```
+
+The alias is strictly additive — matching on `name` directly continues
+to work.
+
+## Errors thrown
+
+- `NodeNotFoundError` — `findNode` / `findFocusedNode` / `expectFocused`
+when no node matches. Fields: `predicate`, `treeSummary`.
+- `FocusedNodeMismatchError` — `expectFocused` when a node IS focused
+but doesn't match. Fields: `predicate`, `focusedSummary`.
+- `WaitForNodeTimeoutError` — `client.waitForNode` on timeout. Fields:
+`predicate`, `timeout`, `context.lastTree`.
+- `BaselineMissingError` — `expectTree` against a baseline that
+doesn't exist. Fields: `baselinePath`, `resolution`, `videoMode`.
+- `TreeMismatchError` — `expectTree` with a diff. Fields:
+`baselinePath`, `firstDiff`, `expectedSnippet`, `actualSnippet`.
+
+Full field lists and recovery advice in
+`[errors.md](errors.md)`.