@putdotio/rokit 2.1.0 → 2.2.0

package/README.md

@@ -106,6 +106,7 @@ App-specific scenario scripts can import the generic helpers:
 import {
   assertMediaPlayerContainer,
   assertSceneGraphNode,
+  captureScreenshot,
   pressKey,
   querySceneGraph,
   waitForSceneGraphAssertion,
@@ -124,9 +125,14 @@ const context: RokuContext = {
 };
 
 await pressKey(context, "Info");
-await querySceneGraph(context, { attempts: 3, requireComplete: true });
+await querySceneGraph(context, { attempts: 3, requireAppNode: true, requireComplete: true });
 await assertSceneGraphNode(context, "videoPlayerScreen", { state: "visible" });
 await assertMediaPlayerContainer(context, "mp4");
+await captureScreenshot(
+  { ...context, password: process.env.ROKIT_PASSWORD ?? "" },
+  "artifacts/player.jpg",
+  { attempts: 3 },
+);
 await waitForSceneGraphAssertion(context, "player ready", (xml) => {
   if (!xml.includes("videoPlayerScreen")) {
     throw new Error("expected player screen");

package/dist/{debug-af6vvS9T.mjs → debug-BbJdwNkW.mjs}

@@ -4,6 +4,8 @@ import { existsSync } from "node:fs";
 import { basename, dirname, extname, isAbsolute, join, relative, resolve } from "node:path";
 import * as rokuDeploy from "roku-deploy";
 import { createSocket } from "node:dgram";
+import { access, copyFile, mkdir, mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
 //#region src/errors.ts
 var InvalidInput = class extends Schema.TaggedErrorClass()("InvalidInput", { message: Schema.String }) {};
 var MissingTarget = class extends Schema.TaggedErrorClass()("MissingTarget", {}) {
@@ -335,22 +337,31 @@ const waitForMediaPlayerState = async (context, expectedState, timeoutMs = 1e4)
 };
 const querySceneGraph = async (context, options = {}) => {
 	const attempts = options.attempts ?? 1;
+	const requireAppNode = options.requireAppNode ?? false;
 	const requireComplete = options.requireComplete ?? false;
 	const retryDelayMs = options.retryDelayMs ?? 500;
 	let lastXml = "";
 	let lastError;
+	let lastMissingAppNode = false;
 	for (let attempt = 0; attempt < attempts; attempt += 1) {
 		try {
 			const xml = await queryEcp(context, "/query/sgnodes/all");
-			if (!requireComplete || isCompleteSceneGraph(xml)) return xml;
+			const complete = !requireComplete || isCompleteSceneGraph(xml);
+			const hasAppNode = !requireAppNode || !xml.includes("<All_Nodes>") || xml.includes("<App ");
+			if (complete && hasAppNode) return xml;
 			lastXml = xml;
+			lastMissingAppNode = complete && !hasAppNode;
 		} catch (error) {
 			lastError = error;
 			lastXml = "";
+			lastMissingAppNode = false;
 		}
 		if (attempt < attempts - 1) await sleep(retryDelayMs);
 	}
-	if (lastXml !== "") throw new Error("SceneGraph query returned incomplete XML");
+	if (lastXml !== "") {
+		if (lastMissingAppNode) throw new Error("SceneGraph query returned complete XML without an App node");
+		throw new Error("SceneGraph query returned incomplete XML");
+	}
 	throw new Error(`SceneGraph query failed: ${formatErrorMessage$1(lastError)}`);
 };
 const assertSceneGraphNode = async (context, nodeName, expectation) => {
@@ -411,6 +422,41 @@ const takeScreenshot = async (context, outputPath) => {
 		password: context.password
 	});
 };
+const captureScreenshot = async (context, outputPath, options = {}) => {
+	const attempts = options.attempts ?? 3;
+	const retryDelayMs = options.retryDelayMs ?? 1500;
+	const resolvedOutput = resolve(outputPath);
+	await mkdir(dirname(resolvedOutput), { recursive: true });
+	let lastError = "unknown";
+	for (let attempt = 1; attempt <= attempts; attempt += 1) {
+		const captureDir = await mkdtemp(join(tmpdir(), `${safeTempPrefix(options.tempDirPrefix ?? "rokit-screenshot")}-`));
+		const capturePath = join(captureDir, basename(resolvedOutput));
+		try {
+			const tempResult = await firstExistingPath([await takeScreenshot(context, capturePath), capturePath]);
+			if (tempResult !== void 0) {
+				await copyFile(tempResult, resolvedOutput);
+				return resolvedOutput;
+			}
+			const directResult = await firstExistingPath([resolvedOutput, await takeScreenshot(context, resolvedOutput)]);
+			if (directResult === resolvedOutput) return resolvedOutput;
+			if (directResult !== void 0) {
+				await copyFile(directResult, resolvedOutput);
+				return resolvedOutput;
+			}
+			throw new Error("screenshot capture succeeded without writing an image file");
+		} catch (error) {
+			lastError = formatErrorMessage$1(error);
+			if (attempt === attempts) break;
+			await sleep(retryDelayMs);
+		} finally {
+			await rm(captureDir, {
+				force: true,
+				recursive: true
+			});
+		}
+	}
+	throw new Error(`failed to capture ${basename(resolvedOutput)}: ${lastError}`);
+};
 const packageChannel = async (outputPath, rootDir = process.cwd()) => {
 	const options = packageOptions(outputPath, rootDir);
 	await rokuDeploy.createPackage(options);
@@ -444,6 +490,18 @@ const rejectUnsafeInput$1 = (value, label) => {
 		return code < 32 || code === 127;
 	})) throw new Error(`${label} contains control characters`);
 };
+const safeTempPrefix = (value) => value.replace(/[^a-zA-Z0-9_-]/g, "-");
+const firstExistingPath = async (paths) => {
+	for (const path of paths) if (await fileExists(path)) return path;
+};
+const fileExists = async (path) => {
+	try {
+		await access(path);
+		return true;
+	} catch {
+		return false;
+	}
+};
 const validateRemoteKey = (key) => {
 	if (key.startsWith("Lit_")) return;
 	if (!remoteKeySet.has(key)) throw new Error(`unsupported remote key: ${key}`);
@@ -747,4 +805,4 @@ const validateNonNegativeInteger = (value, label) => {
 	if (!Number.isInteger(parsed) || parsed < 0) fail(`Invalid ${label}: ${value}`);
 };
 //#endregion
-export { readNamedNodeBounds as $, readMediaPlayerInfo as A, waitForSceneGraphNode as B, queryEcp as C, queryMediaPlayerXmlSafe as D, queryMediaPlayerXml as E, validateEcpPath as F, assertNamedNodeTranslation as G, assertNamedNodeSize as H, validateRemoteKey as I, isCompleteSceneGraph as J, assertSceneGraphNumberNear as K, waitForActiveApp as L, readMediaPlayerState as M, resolvePackageOutputPath as N, querySceneGraph as O, takeScreenshot as P, readNamedNodeAttributes as Q, waitForMediaPlayerState as R, queryActiveApp as S, queryMediaPlayerSafe as T, assertNamedNodeState as U, assertNamedNode as V, assertNamedNodeText as W, parseSceneGraphNumberList as X, isNamedNodeVisible as Y, readNamedNodeAttribute as Z, installPackage as _, loadEnv as a, readActiveApp as at, packageChannel as b, requirePassword as c, normalizeError as ct, resolveOutputPath as d, readNamedNodeNumber as et, assertMediaPlayerContainer as f, getDeviceInfo as g, discoverRokuDevices as h, fail as i, sceneGraphContainsText as it, readMediaPlayerPositionMs as j, readMediaPlayerContainer as k, requireTarget as l, renderError as lt, checkDevice as m, captureDebugConsole as n, readSceneGraphFailure as nt, loadLocalEnv as o, readXmlAttribute as ot, assertSceneGraphNode as p, escapeXmlAttribute as q, runDebugCommand as r, readSceneGraphStatus as rt, rejectUnsafeEcpPath as s, readXmlTag as st, buildDebugCommand as t, readNamedNodeTranslation as tt, resolveFileOutputPath as u, isActiveMediaPlayerState as v, queryMediaPlayer as w, pressKey as x, launchApp as y, waitForSceneGraphAssertion as z };
+export { readNamedNodeAttributes as $, readMediaPlayerContainer as A, waitForSceneGraphAssertion as B, queryActiveApp as C, queryMediaPlayerXml as D, queryMediaPlayerSafe as E, takeScreenshot as F, assertNamedNodeText as G, assertNamedNode as H, validateEcpPath as I, escapeXmlAttribute as J, assertNamedNodeTranslation as K, validateRemoteKey as L, readMediaPlayerPositionMs as M, readMediaPlayerState as N, queryMediaPlayerXmlSafe as O, resolvePackageOutputPath as P, readNamedNodeAttribute as Q, waitForActiveApp as R, pressKey as S, queryMediaPlayer as T, assertNamedNodeSize as U, waitForSceneGraphNode as V, assertNamedNodeState as W, isNamedNodeVisible as X, isCompleteSceneGraph as Y, parseSceneGraphNumberList as Z, getDeviceInfo as _, loadEnv as a, sceneGraphContainsText as at, launchApp as b, requirePassword as c, readXmlTag as ct, resolveOutputPath as d, readNamedNodeBounds as et, assertMediaPlayerContainer as f, discoverRokuDevices as g, checkDevice as h, fail as i, readSceneGraphStatus as it, readMediaPlayerInfo as j, querySceneGraph as k, requireTarget as l, normalizeError as lt, captureScreenshot as m, captureDebugConsole as n, readNamedNodeTranslation as nt, loadLocalEnv as o, readActiveApp as ot, assertSceneGraphNode as p, assertSceneGraphNumberNear as q, runDebugCommand as r, readSceneGraphFailure as rt, rejectUnsafeEcpPath as s, readXmlAttribute as st, buildDebugCommand as t, readNamedNodeNumber as tt, resolveFileOutputPath as u, renderError as ut, installPackage as v, queryEcp as w, packageChannel as x, isActiveMediaPlayerState as y, waitForMediaPlayerState as z };

package/dist/index.d.mts

@@ -88,6 +88,7 @@ type MediaPlayerInfo = {
 };
 type RetryOptions = {
   readonly attempts?: number;
+  readonly requireAppNode?: boolean;
   readonly requireComplete?: boolean;
   readonly retryDelayMs?: number;
 };
@@ -99,6 +100,11 @@ type WaitForSceneGraphAssertionOptions = {
 type PackageResult = {
   readonly path: string;
 };
+type ScreenshotCaptureOptions = {
+  readonly attempts?: number;
+  readonly retryDelayMs?: number;
+  readonly tempDirPrefix?: string;
+};
 declare const checkDevice: (context: RokuContext) => Promise<DeviceSummary>;
 declare const getDeviceInfo: (context: RokuContext) => Promise<rokuDeploy.DeviceInfo>;
 declare const queryActiveApp: (context: RokuContext) => Promise<ActiveApp>;
@@ -128,6 +134,9 @@ declare const installPackage: (context: RokuContext & {
 declare const takeScreenshot: (context: RokuContext & {
   readonly password: string;
 }, outputPath: string) => Promise<string>;
+declare const captureScreenshot: (context: RokuContext & {
+  readonly password: string;
+}, outputPath: string, options?: ScreenshotCaptureOptions) => Promise<string>;
 declare const packageChannel: (outputPath: string, rootDir?: string) => Promise<PackageResult>;
 declare const validateEcpPath: (path: string) => string;
 declare const validateRemoteKey: (key: string) => void;
@@ -159,4 +168,4 @@ declare const buildDebugCommand: (command: string, args: readonly string[]) => R
 declare const runDebugCommand: (context: RokuContext, command: RokuDebugCommand, durationMs: number, idleTimeoutMs: number) => Promise<DebugCommandResult>;
 declare const captureDebugConsole: (context: RokuContext, durationMs: number) => Promise<DebugConsoleCapture>;
 //#endregion
-export { type ActiveApp, type DebugCommandResult, type DebugConsoleCapture, type DeviceSummary, type DiscoveredRokuDevice, type MediaPlayerInfo, type MediaPlayerState, type NodeExpectation, type NodeState, type PackageResult, type RemoteKey, type RetryOptions, type RokuContext, type RokuDebugCommand, type RokuDebugPort, type SceneGraphAssertion, type SceneGraphBounds, type SceneGraphPoint, type SceneGraphStatus, type WaitForSceneGraphAssertionOptions, assertMediaPlayerContainer, assertNamedNode, assertNamedNodeSize, assertNamedNodeState, assertNamedNodeText, assertNamedNodeTranslation, assertSceneGraphNode, assertSceneGraphNumberNear, buildDebugCommand, captureDebugConsole, checkDevice, discoverRokuDevices, escapeXmlAttribute, getDeviceInfo, installPackage, isActiveMediaPlayerState, isCompleteSceneGraph, isNamedNodeVisible, launchApp, packageChannel, parseSceneGraphNumberList, pressKey, queryActiveApp, queryEcp, queryMediaPlayer, queryMediaPlayerSafe, queryMediaPlayerXml, queryMediaPlayerXmlSafe, querySceneGraph, readActiveApp, readMediaPlayerContainer, readMediaPlayerInfo, readMediaPlayerPositionMs, readMediaPlayerState, readNamedNodeAttribute, readNamedNodeAttributes, readNamedNodeBounds, readNamedNodeNumber, readNamedNodeTranslation, readSceneGraphFailure, readSceneGraphStatus, readXmlAttribute, readXmlTag, runDebugCommand, sceneGraphContainsText, takeScreenshot, validateEcpPath, validateRemoteKey, waitForActiveApp, waitForMediaPlayerState, waitForSceneGraphAssertion, waitForSceneGraphNode };
+export { type ActiveApp, type DebugCommandResult, type DebugConsoleCapture, type DeviceSummary, type DiscoveredRokuDevice, type MediaPlayerInfo, type MediaPlayerState, type NodeExpectation, type NodeState, type PackageResult, type RemoteKey, type RetryOptions, type RokuContext, type RokuDebugCommand, type RokuDebugPort, type SceneGraphAssertion, type SceneGraphBounds, type SceneGraphPoint, type SceneGraphStatus, type ScreenshotCaptureOptions, type WaitForSceneGraphAssertionOptions, assertMediaPlayerContainer, assertNamedNode, assertNamedNodeSize, assertNamedNodeState, assertNamedNodeText, assertNamedNodeTranslation, assertSceneGraphNode, assertSceneGraphNumberNear, buildDebugCommand, captureDebugConsole, captureScreenshot, checkDevice, discoverRokuDevices, escapeXmlAttribute, getDeviceInfo, installPackage, isActiveMediaPlayerState, isCompleteSceneGraph, isNamedNodeVisible, launchApp, packageChannel, parseSceneGraphNumberList, pressKey, queryActiveApp, queryEcp, queryMediaPlayer, queryMediaPlayerSafe, queryMediaPlayerXml, queryMediaPlayerXmlSafe, querySceneGraph, readActiveApp, readMediaPlayerContainer, readMediaPlayerInfo, readMediaPlayerPositionMs, readMediaPlayerState, readNamedNodeAttribute, readNamedNodeAttributes, readNamedNodeBounds, readNamedNodeNumber, readNamedNodeTranslation, readSceneGraphFailure, readSceneGraphStatus, readXmlAttribute, readXmlTag, runDebugCommand, sceneGraphContainsText, takeScreenshot, validateEcpPath, validateRemoteKey, waitForActiveApp, waitForMediaPlayerState, waitForSceneGraphAssertion, waitForSceneGraphNode };

package/dist/index.mjs

@@ -1,2 +1,2 @@
-import { $ as readNamedNodeBounds, A as readMediaPlayerInfo, B as waitForSceneGraphNode, C as queryEcp, D as queryMediaPlayerXmlSafe, E as queryMediaPlayerXml, F as validateEcpPath, G as assertNamedNodeTranslation, H as assertNamedNodeSize, I as validateRemoteKey, J as isCompleteSceneGraph, K as assertSceneGraphNumberNear, L as waitForActiveApp, M as readMediaPlayerState, O as querySceneGraph, P as takeScreenshot, Q as readNamedNodeAttributes, R as waitForMediaPlayerState, S as queryActiveApp, T as queryMediaPlayerSafe, U as assertNamedNodeState, V as assertNamedNode, W as assertNamedNodeText, X as parseSceneGraphNumberList, Y as isNamedNodeVisible, Z as readNamedNodeAttribute, _ as installPackage, at as readActiveApp, b as packageChannel, et as readNamedNodeNumber, f as assertMediaPlayerContainer, g as getDeviceInfo, h as discoverRokuDevices, it as sceneGraphContainsText, j as readMediaPlayerPositionMs, k as readMediaPlayerContainer, m as checkDevice, n as captureDebugConsole, nt as readSceneGraphFailure, ot as readXmlAttribute, p as assertSceneGraphNode, q as escapeXmlAttribute, r as runDebugCommand, rt as readSceneGraphStatus, st as readXmlTag, t as buildDebugCommand, tt as readNamedNodeTranslation, v as isActiveMediaPlayerState, w as queryMediaPlayer, x as pressKey, y as launchApp, z as waitForSceneGraphAssertion } from "./debug-af6vvS9T.mjs";
-export { assertMediaPlayerContainer, assertNamedNode, assertNamedNodeSize, assertNamedNodeState, assertNamedNodeText, assertNamedNodeTranslation, assertSceneGraphNode, assertSceneGraphNumberNear, buildDebugCommand, captureDebugConsole, checkDevice, discoverRokuDevices, escapeXmlAttribute, getDeviceInfo, installPackage, isActiveMediaPlayerState, isCompleteSceneGraph, isNamedNodeVisible, launchApp, packageChannel, parseSceneGraphNumberList, pressKey, queryActiveApp, queryEcp, queryMediaPlayer, queryMediaPlayerSafe, queryMediaPlayerXml, queryMediaPlayerXmlSafe, querySceneGraph, readActiveApp, readMediaPlayerContainer, readMediaPlayerInfo, readMediaPlayerPositionMs, readMediaPlayerState, readNamedNodeAttribute, readNamedNodeAttributes, readNamedNodeBounds, readNamedNodeNumber, readNamedNodeTranslation, readSceneGraphFailure, readSceneGraphStatus, readXmlAttribute, readXmlTag, runDebugCommand, sceneGraphContainsText, takeScreenshot, validateEcpPath, validateRemoteKey, waitForActiveApp, waitForMediaPlayerState, waitForSceneGraphAssertion, waitForSceneGraphNode };
+import { $ as readNamedNodeAttributes, A as readMediaPlayerContainer, B as waitForSceneGraphAssertion, C as queryActiveApp, D as queryMediaPlayerXml, E as queryMediaPlayerSafe, F as takeScreenshot, G as assertNamedNodeText, H as assertNamedNode, I as validateEcpPath, J as escapeXmlAttribute, K as assertNamedNodeTranslation, L as validateRemoteKey, M as readMediaPlayerPositionMs, N as readMediaPlayerState, O as queryMediaPlayerXmlSafe, Q as readNamedNodeAttribute, R as waitForActiveApp, S as pressKey, T as queryMediaPlayer, U as assertNamedNodeSize, V as waitForSceneGraphNode, W as assertNamedNodeState, X as isNamedNodeVisible, Y as isCompleteSceneGraph, Z as parseSceneGraphNumberList, _ as getDeviceInfo, at as sceneGraphContainsText, b as launchApp, ct as readXmlTag, et as readNamedNodeBounds, f as assertMediaPlayerContainer, g as discoverRokuDevices, h as checkDevice, it as readSceneGraphStatus, j as readMediaPlayerInfo, k as querySceneGraph, m as captureScreenshot, n as captureDebugConsole, nt as readNamedNodeTranslation, ot as readActiveApp, p as assertSceneGraphNode, q as assertSceneGraphNumberNear, r as runDebugCommand, rt as readSceneGraphFailure, st as readXmlAttribute, t as buildDebugCommand, tt as readNamedNodeNumber, v as installPackage, w as queryEcp, x as packageChannel, y as isActiveMediaPlayerState, z as waitForMediaPlayerState } from "./debug-BbJdwNkW.mjs";
+export { assertMediaPlayerContainer, assertNamedNode, assertNamedNodeSize, assertNamedNodeState, assertNamedNodeText, assertNamedNodeTranslation, assertSceneGraphNode, assertSceneGraphNumberNear, buildDebugCommand, captureDebugConsole, captureScreenshot, checkDevice, discoverRokuDevices, escapeXmlAttribute, getDeviceInfo, installPackage, isActiveMediaPlayerState, isCompleteSceneGraph, isNamedNodeVisible, launchApp, packageChannel, parseSceneGraphNumberList, pressKey, queryActiveApp, queryEcp, queryMediaPlayer, queryMediaPlayerSafe, queryMediaPlayerXml, queryMediaPlayerXmlSafe, querySceneGraph, readActiveApp, readMediaPlayerContainer, readMediaPlayerInfo, readMediaPlayerPositionMs, readMediaPlayerState, readNamedNodeAttribute, readNamedNodeAttributes, readNamedNodeBounds, readNamedNodeNumber, readNamedNodeTranslation, readSceneGraphFailure, readSceneGraphStatus, readXmlAttribute, readXmlTag, runDebugCommand, sceneGraphContainsText, takeScreenshot, validateEcpPath, validateRemoteKey, waitForActiveApp, waitForMediaPlayerState, waitForSceneGraphAssertion, waitForSceneGraphNode };

package/dist/rokit.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { B as waitForSceneGraphNode, C as queryEcp, I as validateRemoteKey, L as waitForActiveApp, N as resolvePackageOutputPath, O as querySceneGraph, P as takeScreenshot, R as waitForMediaPlayerState, S as queryActiveApp, _ as installPackage, a as loadEnv, b as packageChannel, c as requirePassword, ct as normalizeError, d as resolveOutputPath, g as getDeviceInfo, h as discoverRokuDevices, i as fail, l as requireTarget, lt as renderError, m as checkDevice, n as captureDebugConsole, nt as readSceneGraphFailure, o as loadLocalEnv, p as assertSceneGraphNode, r as runDebugCommand, rt as readSceneGraphStatus, s as rejectUnsafeEcpPath, t as buildDebugCommand, u as resolveFileOutputPath, w as queryMediaPlayer, x as pressKey, y as launchApp } from "./debug-af6vvS9T.mjs";
+import { C as queryActiveApp, L as validateRemoteKey, P as resolvePackageOutputPath, R as waitForActiveApp, S as pressKey, T as queryMediaPlayer, V as waitForSceneGraphNode, _ as getDeviceInfo, a as loadEnv, b as launchApp, c as requirePassword, d as resolveOutputPath, g as discoverRokuDevices, h as checkDevice, i as fail, it as readSceneGraphStatus, k as querySceneGraph, l as requireTarget, lt as normalizeError, m as captureScreenshot, n as captureDebugConsole, o as loadLocalEnv, p as assertSceneGraphNode, r as runDebugCommand, rt as readSceneGraphFailure, s as rejectUnsafeEcpPath, t as buildDebugCommand, u as resolveFileOutputPath, ut as renderError, v as installPackage, w as queryEcp, x as packageChannel, z as waitForMediaPlayerState } from "./debug-BbJdwNkW.mjs";
 import { createRequire } from "node:module";
 import { Effect } from "effect";
 import { mkdirSync, writeFileSync } from "node:fs";
@@ -255,8 +255,7 @@ const runCommand = async (context, command, dryRun) => {
 		const path = timestampOutputPath(resolveFileOutputPath(command.outputPath, "screenshot output path"));
 		if (dryRun) return dryRunResult(command.name, { path });
 		const password = requirePassword(deviceContext);
-		mkdirSync(dirname(path), { recursive: true });
-		const screenshotPath = await takeScreenshot({
+		const screenshotPath = await captureScreenshot({
 			...deviceContext,
 			password
 		}, path);
@@ -405,7 +404,7 @@ const writeProof = async (context, outputDir, includeScreenshot) => {
 	writeJson("media-player", await observe(async () => await queryMediaPlayer(context)));
 	if (includeScreenshot) {
 		const password = requirePassword(context);
-		const path = await takeScreenshot({
+		const path = await captureScreenshot({
 			...context,
 			password
 		}, timestampOutputPath(`${outputDir}/screenshot.png`));

package/package.json

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