@putdotio/rokit 1.4.0 → 1.5.0

package/README.md

@@ -49,10 +49,12 @@ App-specific scenario scripts can also import the generic helpers:
 
 ```ts
 import {
+  assertNamedNodeState,
+  assertNamedNodeTranslation,
   assertSceneGraphNode,
   pressKey,
   querySceneGraph,
-  readNamedNodeTranslation,
+  waitForSceneGraphAssertion,
   type RokuContext,
 } from "@putdotio/rokit";
 
@@ -71,7 +73,10 @@ const context: RokuContext = {
 await pressKey(context, "Info");
 const xml = await querySceneGraph(context, { attempts: 3 });
 await assertSceneGraphNode(context, "videoPlayerScreen", { state: "visible" });
-console.log(readNamedNodeTranslation(xml, "videoPlayerScreen"));
+assertNamedNodeTranslation(xml, "videoPlayerScreen", 0, 0);
+await waitForSceneGraphAssertion(context, "expected player", (xml) => {
+  assertNamedNodeState(xml, "videoPlayerScreen", "visible");
+});
 ```
 
 ## Commands
@@ -149,6 +154,8 @@ tokens, and app-specific media identifiers do not belong in git.
 - raw ECP queries
 - SceneGraph state queries and named-node assertions
 - SceneGraph attribute, numeric geometry, bounds, and translation readers
+- SceneGraph geometry assertions, status/failure readers, and custom assertion
+  wait loops
 - screenshots
 
 App repositories should keep their own scenario commands for product behavior,

package/dist/index.d.mts

@@ -4,6 +4,10 @@ import * as rokuDeploy from "roku-deploy";
 type NodeState = "absent" | "hidden" | "visible";
 type SceneGraphBounds = readonly [x: number, y: number, width: number, height: number];
 type SceneGraphPoint = readonly [x: number, y: number];
+type SceneGraphStatus = {
+  readonly error?: string;
+  readonly status?: string;
+};
 type NodeExpectation = {
   readonly state: NodeState;
   readonly text?: string;
@@ -16,7 +20,12 @@ declare const readNamedNodeAttribute: (xml: string, nodeName: string, attributeN
 declare const readNamedNodeNumber: (xml: string, nodeName: string, attributeName: string) => number | undefined;
 declare const readNamedNodeBounds: (xml: string, nodeName: string) => SceneGraphBounds | undefined;
 declare const readNamedNodeTranslation: (xml: string, nodeName: string) => SceneGraphPoint | undefined;
+declare const readSceneGraphStatus: (xml: string) => SceneGraphStatus;
+declare const readSceneGraphFailure: (xml: string) => string | undefined;
 declare const isNamedNodeVisible: (xml: string, nodeName: 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;
 declare const assertNamedNode: (xml: string, nodeName: string, expectation: NodeExpectation) => void;
 declare const assertNamedNodeState: (xml: string, nodeName: string, state: NodeState) => void;
 declare const assertNamedNodeText: (xml: string, nodeName: string, expectedText: string) => void;
@@ -52,6 +61,11 @@ type RetryOptions = {
   readonly attempts?: number;
   readonly retryDelayMs?: number;
 };
+type SceneGraphAssertion = (xml: string) => void;
+type WaitForSceneGraphAssertionOptions = {
+  readonly pollIntervalMs?: number;
+  readonly timeoutMs?: number;
+};
 declare const checkDevice: (context: RokuContext) => Promise<DeviceSummary>;
 declare const getDeviceInfo: (context: RokuContext) => Promise<rokuDeploy.DeviceInfo>;
 declare const queryActiveApp: (context: RokuContext) => Promise<ActiveApp>;
@@ -62,6 +76,7 @@ declare const queryEcp: (context: RokuContext, path: string) => Promise<string>;
 declare const querySceneGraph: (context: RokuContext, options?: RetryOptions) => Promise<string>;
 declare const assertSceneGraphNode: (context: RokuContext, nodeName: string, expectation: NodeExpectation) => Promise<void>;
 declare const waitForSceneGraphNode: (context: RokuContext, nodeName: string, expectation: NodeExpectation, timeoutMs?: number) => Promise<void>;
+declare const waitForSceneGraphAssertion: (context: RokuContext, description: string, assertXml: SceneGraphAssertion, options?: WaitForSceneGraphAssertionOptions) => Promise<string>;
 declare const installPackage: (context: RokuContext & {
   readonly password: string;
 }, zipPath: string) => Promise<string>;
@@ -70,4 +85,4 @@ declare const takeScreenshot: (context: RokuContext & {
 }, outputPath: string) => Promise<string>;
 declare const validateRemoteKey: (key: string) => void;
 //#endregion
-export { type ActiveApp, type DeviceSummary, type NodeExpectation, type NodeState, type RemoteKey, type RetryOptions, type RokuContext, type SceneGraphBounds, type SceneGraphPoint, assertNamedNode, assertNamedNodeState, assertNamedNodeText, assertSceneGraphNode, checkDevice, getDeviceInfo, installPackage, isNamedNodeVisible, launchApp, parseSceneGraphNumberList, pressKey, queryActiveApp, queryEcp, querySceneGraph, readActiveApp, readNamedNodeAttribute, readNamedNodeAttributes, readNamedNodeBounds, readNamedNodeNumber, readNamedNodeTranslation, readXmlAttribute, readXmlTag, takeScreenshot, validateRemoteKey, waitForActiveApp, waitForSceneGraphNode };
+export { type ActiveApp, type DeviceSummary, 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, isNamedNodeVisible, launchApp, parseSceneGraphNumberList, pressKey, queryActiveApp, queryEcp, querySceneGraph, readActiveApp, readNamedNodeAttribute, readNamedNodeAttributes, readNamedNodeBounds, readNamedNodeNumber, readNamedNodeTranslation, readSceneGraphFailure, readSceneGraphStatus, readXmlAttribute, readXmlTag, takeScreenshot, validateRemoteKey, waitForActiveApp, waitForSceneGraphAssertion, waitForSceneGraphNode };

package/dist/index.mjs

@@ -1,2 +1,2 @@
-import { C as readNamedNodeTranslation, E as readXmlTag, S as readNamedNodeNumber, T as readXmlAttribute, _ as isNamedNodeVisible, a as launchApp, b as readNamedNodeAttributes, c as queryEcp, d as validateRemoteKey, f as waitForActiveApp, g as assertNamedNodeText, h as assertNamedNodeState, i as installPackage, l as querySceneGraph, m as assertNamedNode, n as checkDevice, o as pressKey, p as waitForSceneGraphNode, r as getDeviceInfo, s as queryActiveApp, t as assertSceneGraphNode, u as takeScreenshot, v as parseSceneGraphNumberList, w as readActiveApp, x as readNamedNodeBounds, y as readNamedNodeAttribute } from "./roku-7hiM97p0.mjs";
-export { assertNamedNode, assertNamedNodeState, assertNamedNodeText, assertSceneGraphNode, checkDevice, getDeviceInfo, installPackage, isNamedNodeVisible, launchApp, parseSceneGraphNumberList, pressKey, queryActiveApp, queryEcp, querySceneGraph, readActiveApp, readNamedNodeAttribute, readNamedNodeAttributes, readNamedNodeBounds, readNamedNodeNumber, readNamedNodeTranslation, readXmlAttribute, readXmlTag, takeScreenshot, validateRemoteKey, waitForActiveApp, waitForSceneGraphNode };
+import { A as readActiveApp, C as readNamedNodeAttribute, D as readNamedNodeTranslation, E as readNamedNodeNumber, M as readXmlTag, O as readSceneGraphFailure, S as parseSceneGraphNumberList, T as readNamedNodeBounds, _ as assertNamedNodeState, a as launchApp, b as assertSceneGraphNumberNear, c as queryEcp, d as validateRemoteKey, f as waitForActiveApp, g as assertNamedNodeSize, h as assertNamedNode, i as installPackage, j as readXmlAttribute, k as readSceneGraphStatus, l as querySceneGraph, m as waitForSceneGraphNode, n as checkDevice, o as pressKey, p as waitForSceneGraphAssertion, r as getDeviceInfo, s as queryActiveApp, t as assertSceneGraphNode, u as takeScreenshot, v as assertNamedNodeText, w as readNamedNodeAttributes, x as isNamedNodeVisible, y as assertNamedNodeTranslation } from "./roku-CNLr4tbj.mjs";
+export { assertNamedNode, assertNamedNodeSize, assertNamedNodeState, assertNamedNodeText, assertNamedNodeTranslation, assertSceneGraphNode, assertSceneGraphNumberNear, checkDevice, getDeviceInfo, installPackage, isNamedNodeVisible, launchApp, parseSceneGraphNumberList, pressKey, queryActiveApp, queryEcp, querySceneGraph, readActiveApp, readNamedNodeAttribute, readNamedNodeAttributes, readNamedNodeBounds, readNamedNodeNumber, readNamedNodeTranslation, readSceneGraphFailure, readSceneGraphStatus, readXmlAttribute, readXmlTag, takeScreenshot, validateRemoteKey, waitForActiveApp, waitForSceneGraphAssertion, waitForSceneGraphNode };

package/dist/rokit.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { a as launchApp, c as queryEcp, f as waitForActiveApp, i as installPackage, l as querySceneGraph, n as checkDevice, o as pressKey, p as waitForSceneGraphNode, r as getDeviceInfo, s as queryActiveApp, t as assertSceneGraphNode, u as takeScreenshot } from "./roku-7hiM97p0.mjs";
+import { a as launchApp, c as queryEcp, f as waitForActiveApp, i as installPackage, l as querySceneGraph, m as waitForSceneGraphNode, n as checkDevice, o as pressKey, r as getDeviceInfo, s as queryActiveApp, t as assertSceneGraphNode, u as takeScreenshot } from "./roku-CNLr4tbj.mjs";
 import { createRequire } from "node:module";
 import { dirname, join } from "node:path";
 import { existsSync, mkdirSync } from "node:fs";

package/dist/{roku-7hiM97p0.mjs → roku-CNLr4tbj.mjs}

@@ -58,10 +58,30 @@ const readNamedNodeTranslation = (xml, nodeName) => {
 	if (parts.length < 2) return;
 	return [parts[0], parts[1]];
 };
+const readSceneGraphStatus = (xml) => ({
+	error: readXmlTag(xml, "error"),
+	status: readXmlTag(xml, "status")
+});
+const readSceneGraphFailure = (xml) => {
+	const { error, status } = readSceneGraphStatus(xml);
+	return status === "FAILED" ? error ?? "unknown" : void 0;
+};
 const isNamedNodeVisible = (xml, nodeName) => {
 	const attributes = readNamedNodeAttributes(xml, nodeName);
 	return attributes !== void 0 && !attributes.includes("visible=\"false\"");
 };
+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"}`);
+};
+const assertNamedNodeTranslation = (xml, nodeName, expectedX, expectedY, tolerance = 1) => {
+	const translation = readNamedNodeTranslation(xml, nodeName);
+	assertSceneGraphNumberNear(translation?.[0], expectedX, `${nodeName} x`, tolerance);
+	assertSceneGraphNumberNear(translation?.[1], expectedY, `${nodeName} y`, tolerance);
+};
+const assertNamedNodeSize = (xml, nodeName, expectedWidth, expectedHeight, tolerance = 1) => {
+	assertSceneGraphNumberNear(readNamedNodeNumber(xml, nodeName, "width"), expectedWidth, `${nodeName} width`, tolerance);
+	assertSceneGraphNumberNear(readNamedNodeNumber(xml, nodeName, "height"), expectedHeight, `${nodeName} height`, tolerance);
+};
 const assertNamedNode = (xml, nodeName, expectation) => {
 	if ("attribute" in expectation) {
 		assertNamedNodeAttribute(xml, nodeName, expectation.attribute, expectation.value);
@@ -199,6 +219,24 @@ const waitForSceneGraphNode = async (context, nodeName, expectation, timeoutMs =
 	const suffix = lastError ? `; last observation: ${lastError}` : "";
 	throw new Error(`expected SceneGraph node "${nodeName}" to match condition${suffix}`);
 };
+const waitForSceneGraphAssertion = async (context, description, assertXml, options = {}) => {
+	const timeoutMs = options.timeoutMs ?? 3e4;
+	const pollIntervalMs = options.pollIntervalMs ?? 500;
+	const start = Date.now();
+	let lastError;
+	while (Date.now() - start < timeoutMs) {
+		try {
+			const xml = await querySceneGraph(context);
+			assertXml(xml);
+			return xml;
+		} catch (error) {
+			lastError = formatErrorMessage(error);
+		}
+		await sleep(pollIntervalMs);
+	}
+	const suffix = lastError ? `; last observation: ${lastError}` : "";
+	throw new Error(`${description}${suffix}`);
+};
 const installPackage = async (context, zipPath) => {
 	const resolvedZip = resolve(zipPath);
 	const extension = extname(resolvedZip);
@@ -258,4 +296,4 @@ const sleep = (ms) => new Promise((resolve) => {
 });
 const formatErrorMessage = (error) => error instanceof Error ? error.message : String(error);
 //#endregion
-export { readNamedNodeTranslation as C, readXmlTag as E, readNamedNodeNumber as S, readXmlAttribute as T, isNamedNodeVisible as _, launchApp as a, readNamedNodeAttributes as b, queryEcp as c, validateRemoteKey as d, waitForActiveApp as f, assertNamedNodeText as g, assertNamedNodeState as h, installPackage as i, querySceneGraph as l, assertNamedNode as m, checkDevice as n, pressKey as o, waitForSceneGraphNode as p, getDeviceInfo as r, queryActiveApp as s, assertSceneGraphNode as t, takeScreenshot as u, parseSceneGraphNumberList as v, readActiveApp as w, readNamedNodeBounds as x, readNamedNodeAttribute as y };
+export { readActiveApp as A, readNamedNodeAttribute as C, readNamedNodeTranslation as D, readNamedNodeNumber as E, readXmlTag as M, readSceneGraphFailure as O, parseSceneGraphNumberList as S, readNamedNodeBounds as T, assertNamedNodeState as _, launchApp as a, assertSceneGraphNumberNear as b, queryEcp as c, validateRemoteKey as d, waitForActiveApp as f, assertNamedNodeSize as g, assertNamedNode as h, installPackage as i, readXmlAttribute as j, readSceneGraphStatus as k, querySceneGraph as l, waitForSceneGraphNode as m, checkDevice as n, pressKey as o, waitForSceneGraphAssertion as p, getDeviceInfo as r, queryActiveApp as s, assertSceneGraphNode as t, takeScreenshot as u, assertNamedNodeText as v, readNamedNodeAttributes as w, isNamedNodeVisible as x, assertNamedNodeTranslation as y };

package/package.json

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