@putdotio/rokit 1.6.0 → 1.7.0

package/README.md

@@ -47,9 +47,11 @@ App-specific scenario scripts can also import the generic helpers:
 import {
   assertNamedNodeState,
   assertNamedNodeTranslation,
+  assertMediaPlayerContainer,
   assertSceneGraphNode,
   pressKey,
   querySceneGraph,
+  sceneGraphContainsText,
   waitForSceneGraphAssertion,
   type RokuContext,
 } from "@putdotio/rokit";
@@ -67,11 +69,15 @@ const context: RokuContext = {
 };
 
 await pressKey(context, "Info");
-const xml = await querySceneGraph(context, { attempts: 3 });
+const xml = await querySceneGraph(context, { attempts: 3, requireComplete: true });
 await assertSceneGraphNode(context, "videoPlayerScreen", { state: "visible" });
 assertNamedNodeTranslation(xml, "videoPlayerScreen", 0, 0);
+await assertMediaPlayerContainer(context, "mp4");
 await waitForSceneGraphAssertion(context, "expected player", (xml) => {
   assertNamedNodeState(xml, "videoPlayerScreen", "visible");
+  if (!sceneGraphContainsText(xml, "Ready")) {
+    throw new Error("expected ready text");
+  }
 });
 ```
 
@@ -123,7 +129,9 @@ and reports failures as `{ "status": "failed", "error": { "message": "..." } }`.
   sequences that need a stable gap between keys.
 - `query` prints a raw ECP response such as `/query/sgnodes/all`.
 - `sgnodes` prints the raw SceneGraph tree from `/query/sgnodes/all`. Library
-  callers can pass retry options to `querySceneGraph`.
+  callers can pass retry options to `querySceneGraph`; use
+  `requireComplete: true` when a scenario needs to reject partial SceneGraph
+  dumps that include `<All_Nodes>` but no root `<App>` node yet.
 - `assert-node` checks a named SceneGraph node once.
 - `wait-node` polls SceneGraph until a named node condition matches.
 - `screenshot` saves a developer screenshot. It requires `ROKIT_PASSWORD`.
@@ -155,8 +163,10 @@ tokens, and app-specific media identifiers do not belong in git.
 - remote keypresses
 - raw ECP queries
 - parsed media-player state from `/query/media-player`
+- media-player active-state and container assertions
 - SceneGraph state queries and named-node assertions
 - SceneGraph attribute, numeric geometry, bounds, and translation readers
+- SceneGraph completeness and escaped-text helpers
 - SceneGraph geometry assertions, status/failure readers, and custom assertion
   wait loops
 - screenshots

package/dist/index.d.mts

@@ -23,6 +23,9 @@ declare const readNamedNodeTranslation: (xml: string, nodeName: string) => Scene
 declare const readSceneGraphStatus: (xml: string) => SceneGraphStatus;
 declare const readSceneGraphFailure: (xml: string) => string | undefined;
 declare const isNamedNodeVisible: (xml: string, nodeName: string) => boolean;
+declare const isCompleteSceneGraph: (xml: string) => boolean;
+declare const escapeXmlAttribute: (value: string) => string;
+declare const sceneGraphContainsText: (xml: string, text: string) => boolean;
 declare const assertSceneGraphNumberNear: (actual: number | undefined, expected: number, label: string, tolerance?: number) => void;
 declare const assertNamedNodeTranslation: (xml: string, nodeName: string, expectedX: number, expectedY: number, tolerance?: number) => void;
 declare const assertNamedNodeSize: (xml: string, nodeName: string, expectedWidth: number, expectedHeight: number, tolerance?: number) => void;
@@ -77,6 +80,7 @@ type MediaPlayerInfo = {
 };
 type RetryOptions = {
   readonly attempts?: number;
+  readonly requireComplete?: boolean;
   readonly retryDelayMs?: number;
 };
 type SceneGraphAssertion = (xml: string) => void;
@@ -93,11 +97,14 @@ declare const pressKey: (context: RokuContext, key: string) => Promise<void>;
 declare const queryEcp: (context: RokuContext, path: string) => Promise<string>;
 declare const queryMediaPlayerXml: (context: RokuContext) => Promise<string>;
 declare const queryMediaPlayer: (context: RokuContext) => Promise<MediaPlayerInfo>;
+declare const queryMediaPlayerXmlSafe: (context: RokuContext) => Promise<string | undefined>;
+declare const queryMediaPlayerSafe: (context: RokuContext) => Promise<MediaPlayerInfo | undefined>;
 declare const readMediaPlayerInfo: (xml: string) => MediaPlayerInfo;
 declare const readMediaPlayerState: (xml: string) => MediaPlayerState | undefined;
 declare const readMediaPlayerPositionMs: (xml: string) => number | undefined;
 declare const readMediaPlayerContainer: (xml: string) => string | undefined;
 declare const isActiveMediaPlayerState: (state: string | undefined) => boolean;
+declare const assertMediaPlayerContainer: (context: RokuContext, expectedContainer: string) => Promise<MediaPlayerInfo>;
 declare const waitForMediaPlayerState: (context: RokuContext, expectedState: MediaPlayerState, timeoutMs?: number) => Promise<MediaPlayerInfo>;
 declare const querySceneGraph: (context: RokuContext, options?: RetryOptions) => Promise<string>;
 declare const assertSceneGraphNode: (context: RokuContext, nodeName: string, expectation: NodeExpectation) => Promise<void>;
@@ -111,4 +118,4 @@ declare const takeScreenshot: (context: RokuContext & {
 }, outputPath: string) => Promise<string>;
 declare const validateRemoteKey: (key: string) => void;
 //#endregion
-export { type ActiveApp, type DeviceSummary, type MediaPlayerInfo, type MediaPlayerState, type NodeExpectation, type NodeState, type RemoteKey, type RetryOptions, type RokuContext, type SceneGraphAssertion, type SceneGraphBounds, type SceneGraphPoint, type SceneGraphStatus, type WaitForSceneGraphAssertionOptions, assertNamedNode, assertNamedNodeSize, assertNamedNodeState, assertNamedNodeText, assertNamedNodeTranslation, assertSceneGraphNode, assertSceneGraphNumberNear, checkDevice, getDeviceInfo, installPackage, isActiveMediaPlayerState, isNamedNodeVisible, launchApp, parseSceneGraphNumberList, pressKey, queryActiveApp, queryEcp, queryMediaPlayer, queryMediaPlayerXml, querySceneGraph, readActiveApp, readMediaPlayerContainer, readMediaPlayerInfo, readMediaPlayerPositionMs, readMediaPlayerState, readNamedNodeAttribute, readNamedNodeAttributes, readNamedNodeBounds, readNamedNodeNumber, readNamedNodeTranslation, readSceneGraphFailure, readSceneGraphStatus, readXmlAttribute, readXmlTag, takeScreenshot, validateRemoteKey, waitForActiveApp, waitForMediaPlayerState, waitForSceneGraphAssertion, waitForSceneGraphNode };
+export { type ActiveApp, type DeviceSummary, type MediaPlayerInfo, type MediaPlayerState, type NodeExpectation, type NodeState, type RemoteKey, type RetryOptions, type RokuContext, type SceneGraphAssertion, type SceneGraphBounds, type SceneGraphPoint, type SceneGraphStatus, type WaitForSceneGraphAssertionOptions, assertMediaPlayerContainer, assertNamedNode, assertNamedNodeSize, assertNamedNodeState, assertNamedNodeText, assertNamedNodeTranslation, assertSceneGraphNode, assertSceneGraphNumberNear, checkDevice, escapeXmlAttribute, getDeviceInfo, installPackage, isActiveMediaPlayerState, isCompleteSceneGraph, isNamedNodeVisible, launchApp, parseSceneGraphNumberList, pressKey, queryActiveApp, queryEcp, queryMediaPlayer, queryMediaPlayerSafe, queryMediaPlayerXml, queryMediaPlayerXmlSafe, querySceneGraph, readActiveApp, readMediaPlayerContainer, readMediaPlayerInfo, readMediaPlayerPositionMs, readMediaPlayerState, readNamedNodeAttribute, readNamedNodeAttributes, readNamedNodeBounds, readNamedNodeNumber, readNamedNodeTranslation, readSceneGraphFailure, readSceneGraphStatus, readXmlAttribute, readXmlTag, sceneGraphContainsText, takeScreenshot, validateRemoteKey, waitForActiveApp, waitForMediaPlayerState, waitForSceneGraphAssertion, waitForSceneGraphNode };

package/dist/index.mjs

@@ -1,2 +1,2 @@
-import { A as parseSceneGraphNumberList, B as readXmlTag, C as assertNamedNode, D as assertNamedNodeTranslation, E as assertNamedNodeText, F as readNamedNodeTranslation, I as readSceneGraphFailure, L as readSceneGraphStatus, M as readNamedNodeAttributes, N as readNamedNodeBounds, O as assertSceneGraphNumberNear, P as readNamedNodeNumber, R as readActiveApp, S as waitForSceneGraphNode, T as assertNamedNodeState, _ as takeScreenshot, a as isActiveMediaPlayerState, b as waitForMediaPlayerState, c as queryActiveApp, d as queryMediaPlayerXml, f as querySceneGraph, g as readMediaPlayerState, h as readMediaPlayerPositionMs, i as installPackage, j as readNamedNodeAttribute, k as isNamedNodeVisible, l as queryEcp, m as readMediaPlayerInfo, n as checkDevice, o as launchApp, p as readMediaPlayerContainer, r as getDeviceInfo, s as pressKey, t as assertSceneGraphNode, u as queryMediaPlayer, v as validateRemoteKey, w as assertNamedNodeSize, x as waitForSceneGraphAssertion, y as waitForActiveApp, z as readXmlAttribute } from "./roku-CXHAzYR-.mjs";
-export { assertNamedNode, assertNamedNodeSize, assertNamedNodeState, assertNamedNodeText, assertNamedNodeTranslation, assertSceneGraphNode, assertSceneGraphNumberNear, checkDevice, getDeviceInfo, installPackage, isActiveMediaPlayerState, isNamedNodeVisible, launchApp, parseSceneGraphNumberList, pressKey, queryActiveApp, queryEcp, queryMediaPlayer, queryMediaPlayerXml, querySceneGraph, readActiveApp, readMediaPlayerContainer, readMediaPlayerInfo, readMediaPlayerPositionMs, readMediaPlayerState, readNamedNodeAttribute, readNamedNodeAttributes, readNamedNodeBounds, readNamedNodeNumber, readNamedNodeTranslation, readSceneGraphFailure, readSceneGraphStatus, readXmlAttribute, readXmlTag, takeScreenshot, validateRemoteKey, waitForActiveApp, waitForMediaPlayerState, waitForSceneGraphAssertion, waitForSceneGraphNode };
+import { A as assertNamedNodeTranslation, B as readNamedNodeTranslation, C as waitForMediaPlayerState, D as assertNamedNodeSize, E as assertNamedNode, F as parseSceneGraphNumberList, G as readXmlAttribute, H as readSceneGraphStatus, I as readNamedNodeAttribute, K as readXmlTag, L as readNamedNodeAttributes, M as escapeXmlAttribute, N as isCompleteSceneGraph, O as assertNamedNodeState, P as isNamedNodeVisible, R as readNamedNodeBounds, S as waitForActiveApp, T as waitForSceneGraphNode, U as sceneGraphContainsText, V as readSceneGraphFailure, W as readActiveApp, _ as readMediaPlayerInfo, a as installPackage, b as takeScreenshot, c as pressKey, d as queryMediaPlayer, f as queryMediaPlayerSafe, g as readMediaPlayerContainer, h as querySceneGraph, i as getDeviceInfo, j as assertSceneGraphNumberNear, k as assertNamedNodeText, l as queryActiveApp, m as queryMediaPlayerXmlSafe, n as assertSceneGraphNode, o as isActiveMediaPlayerState, p as queryMediaPlayerXml, r as checkDevice, s as launchApp, t as assertMediaPlayerContainer, u as queryEcp, v as readMediaPlayerPositionMs, w as waitForSceneGraphAssertion, x as validateRemoteKey, y as readMediaPlayerState, z as readNamedNodeNumber } from "./roku-B61mpmWt.mjs";
+export { assertMediaPlayerContainer, assertNamedNode, assertNamedNodeSize, assertNamedNodeState, assertNamedNodeText, assertNamedNodeTranslation, assertSceneGraphNode, assertSceneGraphNumberNear, checkDevice, escapeXmlAttribute, getDeviceInfo, installPackage, isActiveMediaPlayerState, isCompleteSceneGraph, isNamedNodeVisible, launchApp, parseSceneGraphNumberList, pressKey, queryActiveApp, queryEcp, queryMediaPlayer, queryMediaPlayerSafe, queryMediaPlayerXml, queryMediaPlayerXmlSafe, querySceneGraph, readActiveApp, readMediaPlayerContainer, readMediaPlayerInfo, readMediaPlayerPositionMs, readMediaPlayerState, readNamedNodeAttribute, readNamedNodeAttributes, readNamedNodeBounds, readNamedNodeNumber, readNamedNodeTranslation, readSceneGraphFailure, readSceneGraphStatus, readXmlAttribute, readXmlTag, sceneGraphContainsText, takeScreenshot, validateRemoteKey, waitForActiveApp, waitForMediaPlayerState, waitForSceneGraphAssertion, waitForSceneGraphNode };

package/dist/rokit.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { S as waitForSceneGraphNode, _ as takeScreenshot, b as waitForMediaPlayerState, c as queryActiveApp, f as querySceneGraph, i as installPackage, l as queryEcp, n as checkDevice, o as launchApp, r as getDeviceInfo, s as pressKey, t as assertSceneGraphNode, u as queryMediaPlayer, y as waitForActiveApp } from "./roku-CXHAzYR-.mjs";
+import { C as waitForMediaPlayerState, S as waitForActiveApp, T as waitForSceneGraphNode, a as installPackage, b as takeScreenshot, c as pressKey, d as queryMediaPlayer, h as querySceneGraph, i as getDeviceInfo, l as queryActiveApp, n as assertSceneGraphNode, r as checkDevice, s as launchApp, u as queryEcp } from "./roku-B61mpmWt.mjs";
 import { createRequire } from "node:module";
 import { dirname, join } from "node:path";
 import { existsSync, mkdirSync } from "node:fs";

package/dist/{roku-CXHAzYR-.mjs → roku-B61mpmWt.mjs}

@@ -70,6 +70,9 @@ const isNamedNodeVisible = (xml, nodeName) => {
 	const attributes = readNamedNodeAttributes(xml, nodeName);
 	return attributes !== void 0 && !attributes.includes("visible=\"false\"");
 };
+const isCompleteSceneGraph = (xml) => !xml.includes("<All_Nodes>") || xml.includes("<App ");
+const escapeXmlAttribute = (value) => value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll("\"", "&quot;");
+const sceneGraphContainsText = (xml, text) => xml.includes(escapeXmlAttribute(text));
 const assertSceneGraphNumberNear = (actual, expected, label, tolerance = 1) => {
 	if (actual === void 0 || Math.abs(actual - expected) > tolerance) throw new Error(`expected ${label} ${expected}, got ${actual ?? "missing"}`);
 };
@@ -191,6 +194,17 @@ const pressKey = async (context, key) => {
 const queryEcp = async (context, path) => await fetchText(context, path.startsWith("/") ? path : `/${path}`);
 const queryMediaPlayerXml = async (context) => await queryEcp(context, "/query/media-player");
 const queryMediaPlayer = async (context) => readMediaPlayerInfo(await queryMediaPlayerXml(context));
+const queryMediaPlayerXmlSafe = async (context) => {
+	try {
+		return await queryMediaPlayerXml(context);
+	} catch {
+		return;
+	}
+};
+const queryMediaPlayerSafe = async (context) => {
+	const xml = await queryMediaPlayerXmlSafe(context);
+	return xml === void 0 ? void 0 : readMediaPlayerInfo(xml);
+};
 const readMediaPlayerInfo = (xml) => {
 	const playerAttributes = /<player(?:\s+([^>]*))?>/.exec(xml)?.[1] ?? "";
 	const formatAttributes = /<format(?:\s+([^>]*))?\/>/.exec(xml)?.[1] ?? "";
@@ -216,7 +230,12 @@ const readMediaPlayerInfo = (xml) => {
 const readMediaPlayerState = (xml) => readMediaPlayerInfo(xml).state;
 const readMediaPlayerPositionMs = (xml) => readMediaPlayerInfo(xml).positionMs;
 const readMediaPlayerContainer = (xml) => readMediaPlayerInfo(xml).container;
-const isActiveMediaPlayerState = (state) => state === "buffer" || state === "pause" || state === "play";
+const isActiveMediaPlayerState = (state) => state === "buffer" || state === "buffering" || state === "pause" || state === "play";
+const assertMediaPlayerContainer = async (context, expectedContainer) => {
+	const mediaPlayer = await queryMediaPlayer(context);
+	if (mediaPlayer.container !== expectedContainer) throw new Error(`expected media-player container ${expectedContainer}, got ${mediaPlayer.container ?? "unknown"}`);
+	return mediaPlayer;
+};
 const waitForMediaPlayerState = async (context, expectedState, timeoutMs = 1e4) => {
 	const start = Date.now();
 	let lastState;
@@ -237,14 +256,22 @@ const waitForMediaPlayerState = async (context, expectedState, timeoutMs = 1e4)
 };
 const querySceneGraph = async (context, options = {}) => {
 	const attempts = options.attempts ?? 1;
+	const requireComplete = options.requireComplete ?? false;
 	const retryDelayMs = options.retryDelayMs ?? 500;
+	let lastXml = "";
 	let lastError;
-	for (let attempt = 0; attempt < attempts; attempt += 1) try {
-		return await queryEcp(context, "/query/sgnodes/all");
-	} catch (error) {
-		lastError = error;
+	for (let attempt = 0; attempt < attempts; attempt += 1) {
+		try {
+			const xml = await queryEcp(context, "/query/sgnodes/all");
+			if (!requireComplete || isCompleteSceneGraph(xml)) return xml;
+			lastXml = xml;
+		} catch (error) {
+			lastError = error;
+			lastXml = "";
+		}
 		if (attempt < attempts - 1) await sleep(retryDelayMs);
 	}
+	if (lastXml !== "") return lastXml;
 	throw new Error(`SceneGraph query failed: ${formatErrorMessage(lastError)}`);
 };
 const assertSceneGraphNode = async (context, nodeName, expectation) => {
@@ -360,4 +387,4 @@ const sleep = (ms) => new Promise((resolve) => {
 });
 const formatErrorMessage = (error) => error instanceof Error ? error.message : String(error);
 //#endregion
-export { parseSceneGraphNumberList as A, readXmlTag as B, assertNamedNode as C, assertNamedNodeTranslation as D, assertNamedNodeText as E, readNamedNodeTranslation as F, readSceneGraphFailure as I, readSceneGraphStatus as L, readNamedNodeAttributes as M, readNamedNodeBounds as N, assertSceneGraphNumberNear as O, readNamedNodeNumber as P, readActiveApp as R, waitForSceneGraphNode as S, assertNamedNodeState as T, takeScreenshot as _, isActiveMediaPlayerState as a, waitForMediaPlayerState as b, queryActiveApp as c, queryMediaPlayerXml as d, querySceneGraph as f, readMediaPlayerState as g, readMediaPlayerPositionMs as h, installPackage as i, readNamedNodeAttribute as j, isNamedNodeVisible as k, queryEcp as l, readMediaPlayerInfo as m, checkDevice as n, launchApp as o, readMediaPlayerContainer as p, getDeviceInfo as r, pressKey as s, assertSceneGraphNode as t, queryMediaPlayer as u, validateRemoteKey as v, assertNamedNodeSize as w, waitForSceneGraphAssertion as x, waitForActiveApp as y, readXmlAttribute as z };
+export { assertNamedNodeTranslation as A, readNamedNodeTranslation as B, waitForMediaPlayerState as C, assertNamedNodeSize as D, assertNamedNode as E, parseSceneGraphNumberList as F, readXmlAttribute as G, readSceneGraphStatus as H, readNamedNodeAttribute as I, readXmlTag as K, readNamedNodeAttributes as L, escapeXmlAttribute as M, isCompleteSceneGraph as N, assertNamedNodeState as O, isNamedNodeVisible as P, readNamedNodeBounds as R, waitForActiveApp as S, waitForSceneGraphNode as T, sceneGraphContainsText as U, readSceneGraphFailure as V, readActiveApp as W, readMediaPlayerInfo as _, installPackage as a, takeScreenshot as b, pressKey as c, queryMediaPlayer as d, queryMediaPlayerSafe as f, readMediaPlayerContainer as g, querySceneGraph as h, getDeviceInfo as i, assertSceneGraphNumberNear as j, assertNamedNodeText as k, queryActiveApp as l, queryMediaPlayerXmlSafe as m, assertSceneGraphNode as n, isActiveMediaPlayerState as o, queryMediaPlayerXml as p, checkDevice as r, launchApp as s, assertMediaPlayerContainer as t, queryEcp as u, readMediaPlayerPositionMs as v, waitForSceneGraphAssertion as w, validateRemoteKey as x, readMediaPlayerState as y, readNamedNodeNumber as z };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@putdotio/rokit",
-  "version": "1.6.0",
+  "version": "1.7.0",
   "description": "A tiny CLI companion for Roku device harness work.",
   "keywords": [
     "cli",