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

package/src/index.ts

@@ -0,0 +1,186 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+/**
+ * `@roku-sdk/device-test-client` — public surface.
+ *
+ * SemVer major 2.0.0 trimmed the barrel to the symbols real
+ * consumers actually import. Log primitives, failure-bundle writers,
+ * XML parsers, low-level baseline/screenshot-artifact setters, async
+ * device resolvers, and sync device-env helpers are no longer part
+ * of the documented API.
+ *
+ * **Internal symbols (not on the public surface):**
+ * the `package.json` `exports` map no longer carries a `./src/*`
+ * wildcard. Symbols deliberately kept off this barrel are reachable
+ * ONLY via the dedicated, documented internal subpaths:
+ *
+ *   - `@roku-sdk/device-test-client/internal/deploy` — `resolveAppPath`
+ *     for the integration-test deploy guard's directory-wipe path.
+ *   - `@roku-sdk/device-test-client/internal/constants` — the small
+ *     subset of `src/constants.ts` symbols (currently `ARTIFACT_FILE`)
+ *     that `*.config.ts` files load at parse time. The public barrel
+ *     is unreachable from CommonJS-mode config loaders because it
+ *     transitively pulls in `@roku-sdk/tooling` ESM (`import.meta.url`);
+ *     this subpath bypasses the offending chain.
+ *   - `@roku-sdk/device-test-client/internal/paths` — load-safe
+ *     `test-results/` path helpers used by multi-device test setup.
+ *
+ * If a future internal symbol needs the same escape hatch, prefer
+ * extending one of the existing `internal/<name>` subpaths (grouped
+ * by concern: deploy-side helpers under `deploy`, config-load
+ * constants under `constants`) rather than reintroducing the
+ * wildcard or minting a parallel subpath. The wildcard was tech
+ * debt that compounded — every `./src/<x>` deep import bound the
+ * (already-internal) module topology into the published API surface
+ * for consumers using `moduleResolution: "Node16"` or `"Bundler"`.
+ * Named subpaths are grep-able, audit-able, and break loudly at
+ * install time when a partner reaches for a symbol that has moved.
+ *
+ * Constants surface (M14): `index.ts` no longer re-exports every
+ * value in `constants.ts`. The curated set below covers the env
+ * vars, file/global keys, default budgets, and bundle-layout
+ * names that consumers legitimately read; pure-implementation
+ * magic numbers (ECP queue gaps, log-buffer caps, pixelmatch YIQ
+ * cutoff, error-formatter character caps, readiness-gate poll
+ * mechanics, SSE accumulator limits) are intentionally NOT
+ * re-exported.
+ *
+ * Errors and types (`errors.ts`, `types.ts`) re-export wholesale —
+ * the entire error catalogue must stay reachable for `instanceof`
+ * checks, and the type surface is read-only at runtime.
+ *
+ * The trimmed surface is snapshot-guarded by
+ * `__tests__/public-api-surface.test.ts`; any add/remove/typeof flip
+ * requires an explicit snapshot update + reviewer sign-off.
+ *
+ * See `README.md` (Versioning) for the public API contract and
+ * `docs/getting-started.md` for setup migration guidance.
+ */
+
+export * from "./types";
+export * from "./errors";
+
+// Curated public constants. KEEP in this list any constant a real
+// consumer needs to align to (env-var names, file/global keys,
+// default budgets that overlap with public option types, server
+// URL / port, bundle layout names CI pipelines parse). DO NOT add
+// pure-implementation magic numbers (queue mechanics, formatter
+// caps, parser limits) — those stay file-internal. If a partner
+// truly needs one, promote it through this barrel via a snapshot
+// update (the `./src/*` deep-import escape hatch was removed in
+// to keep the published exports map auditable).
+export {
+    // Env vars + file/global keys.
+    ARTIFACT_FILE,
+    DEVICE_ENV_GLOBAL_KEY,
+    ENV_VAR,
+    // Server URL / port.
+    DEFAULT_RK_SERVER_URL,
+    ROKU_LOG_PORT,
+    // Default budgets (overlap with `RkClientOptions` / `WaitOptions`
+    // / `BuildAndDeployOptions` / `CaptureStableOptions`).
+    BUILD_SSE_IDLE_TIMEOUT_DEFAULT_MS,
+    DEFAULT_KEY_DELAY,
+    DEFAULT_REQUEST_TIMEOUT_MS,
+    DEVICE_ONLINE_DEFAULT_TIMEOUT_MS,
+    DEVICE_ONLINE_POLL_INTERVAL_MS,
+    DEVICE_RECOVERY_DEFAULT_RETRIES,
+    INSTALLER_PORT_PROBE_DEFAULT_TIMEOUT_MS,
+    INSTALLER_PORT_PROBE_INTERVAL_MS,
+    READINESS_TIMEOUT_MS,
+    SCREENSHOT_STABLE_DEFAULT_INTERVAL_MS,
+    WAIT_FOR_LOG_DEFAULT_TIMEOUT_MS,
+    WAIT_FOR_NODE_DEFAULT_INTERVAL_MS,
+    // Public threshold + alignment cap (overlap with `expectScreenshot` opts).
+    ALIGN_TOLERANCE_MAX_PX,
+    DEFAULT_SCREENSHOT_THRESHOLD,
+    // Validation sets consumers can read.
+    SUPPORTED_VIDEO_MODES,
+    SYSTEM_DIALOG_TAGS,
+    // Bundle / artifact layout — CI pipelines key off these names.
+    BASELINE_RESOLUTION_DIR,
+    FAILURE_ARTIFACT_FILE,
+    FAILURE_RECENT_LOG_LINES,
+    FAILURES_DIR,
+    SCREENSHOT_DIFF_DIR
+} from "./constants";
+
+export { RkClient } from "./client/client";
+export { createDefaultClient } from "./client/factory";
+// Exported so tests asserting the home-vs-channel contract check it the
+// same way crash-detection does, instead of pinning field values that
+// differ per firmware.
+export { isHomeScreenActiveApp } from "./client/parsers";
+export {
+    getFatalReason,
+    getUnhealthyReason,
+    isDeviceFatal,
+    isDeviceHealthy,
+    markDeviceFatal,
+    markDeviceUnhealthy,
+    resetDeviceHealth
+} from "./client/health";
+export { createGlobalSetup } from "./jest/global-setup";
+export type { GlobalSetupOptions } from "./jest/global-setup";
+export { createGlobalTeardown } from "./jest/global-teardown";
+export type { CreateGlobalTeardownOptions } from "./jest/global-teardown";
+export { installDeviceTestHooks } from "./jest/install-hooks";
+export type { DeviceRecoveryOptions, InstallDeviceTestHooksOptions } from "./jest/install-hooks";
+export { describeOnDevice, itOnDevice, requirePrecondition } from "./jest/preconditions";
+export type { OnDeviceDescribeOptions, OnDeviceTestOptions } from "./jest/preconditions";
+// Device-lease telemetry helpers for the parallel-device rollout.
+// Curated for partners writing their own `globalSetup` /
+// `globalTeardown`. Each export earns its keep:
+//
+//   - `resolveTelemetry`: bootstrap entry point — turns a
+//     known device id + env into the fully-resolved triple.
+//   - `emitDeviceLeaseLog`: the side-effecting "emit to stdout"
+//     that the dashboard log-aggregator consumes.
+//   - `writeJUnitTelemetryPropertiesFile`: the side-effecting
+//     "write the CJS file `jest-junit` requires".
+//   - `formatDeviceLeaseLog`: pure formatter, exposed so partners
+//     piping through structured loggers (e.g. pino) can re-emit
+//     the canonical line without duplicating the wire contract.
+//   - `buildAcquireEvent` / `buildReleaseEvent` /
+//     `buildJUnitTelemetryProperties`: pure builders so partners
+//     can construct events without memorising the field shape.
+//   - `DEVICE_LEASE_LOG_PREFIX`: surfaced for log-parser code.
+//   - `DEFAULT_PROVIDER_KIND` / `DEFAULT_SHARD_NAME`: the
+//     documented fallback values when env vars are unset; surfaced
+//     so partner tests can assert against them by name.
+//
+// Anything NOT in this list (e.g. internal type guards) is file-
+// internal. The `./src/*` deep-import escape hatch was removed in
+// promote the symbol through this barrel (with a
+// public-API snapshot update) if a partner needs it.
+export {
+    buildAcquireEvent,
+    buildJUnitTelemetryProperties,
+    buildReleaseEvent,
+    DEFAULT_PROVIDER_KIND,
+    DEFAULT_SHARD_NAME,
+    DEVICE_LEASE_LOG_PREFIX,
+    emitDeviceLeaseLog,
+    formatDeviceLeaseLog,
+    resolveTelemetry,
+    writeJUnitTelemetryPropertiesFile
+} from "./jest/telemetry";
+export type {
+    DeviceLeaseAcquireEvent,
+    DeviceLeaseEvent,
+    DeviceLeaseReleaseEvent,
+    DeviceLeaseTelemetry,
+    JUnitTelemetryProperties
+} from "./jest/telemetry";
+export { getDeviceClass } from "./device/device-class";
+export type { DeviceClass } from "./device/device-class";
+export {
+    expectFocused,
+    expectScreenshot,
+    expectTree,
+    findAllNodes,
+    findFocusedNode,
+    findNode,
+    matchesPredicate
+} from "./assertions/assertions";
+export type { ScreenshotAssertion, TreeAssertion } from "./assertions/assertions";

package/src/internal/constants.ts

@@ -0,0 +1,3 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+export * from "../constants";

package/src/jest/artifacts.ts

@@ -0,0 +1,87 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+/**
+ * Artifact helpers shared between `globalSetup` and install hooks.
+ * Extracted so orchestration files focus on lifecycle wiring;
+ * `jest-setup.ts` re-exports every symbol for API compatibility.
+ */
+
+import { mkdirSync, readdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { ARTIFACT_FILE, SUPPORTED_VIDEO_MODES } from "../constants";
+import type { LeaseProvisioning } from "../device/lease-provisioning";
+import type { DeviceInfo } from "../types";
+
+/**
+ * Removes everything inside `testResultsDir` except a `.gitkeep` marker, then
+ * ensures the directory itself exists. Safe to call when the directory is
+ * missing.
+ */
+export function cleanArtifacts(testResultsDir: string): void {
+    mkdirSync(testResultsDir, { recursive: true });
+    for (const entry of readdirSync(testResultsDir, { withFileTypes: true })) {
+        if (entry.name === ".gitkeep") continue;
+        rmSync(join(testResultsDir, entry.name), { recursive: true, force: true });
+    }
+}
+
+export function assertSupportedVideoMode(videoMode: string): void {
+    if (!SUPPORTED_VIDEO_MODES.has(videoMode)) {
+        throw new Error(
+            `Unrecognized device videoMode "${videoMode}". ` + `Supported: ${[...SUPPORTED_VIDEO_MODES].join(", ")}.`
+        );
+    }
+}
+
+/**
+ * On-disk shape of `device-env.json`: the ECP `DeviceInfo` plus whatever
+ * provisioning provenance the lease carried.
+ *
+ * A superset rather than extra `DeviceInfo` fields, because `DeviceInfo` is
+ * the return type of `queryDeviceInfo()` and must keep meaning "what ECP
+ * reported". Readers of the artifact stay valid either way: the snapshot
+ * validator in `client/factory.ts` checks required fields only, and
+ * `readCachedDeviceInfoSync` passes extras through untouched.
+ */
+export type DeviceEnvSnapshot = DeviceInfo & LeaseProvisioning;
+
+/**
+ * Atomic write of `device-env.json` (write-temp + rename) so
+ * concurrent readers never see a torn JSON payload.
+ *
+ * `provisioning` keys with an `undefined` value are dropped by
+ * `JSON.stringify`, so an unknown field is absent from the artifact rather
+ * than present-and-null — see `lease-provisioning.ts` for why absence is
+ * the correct encoding of "unknown".
+ */
+export function writeDeviceEnvSnapshot(
+    testResultsDir: string,
+    info: DeviceInfo,
+    provisioning: LeaseProvisioning = {}
+): void {
+    const file = join(testResultsDir, ARTIFACT_FILE.DEVICE_ENV);
+    const snapshot: DeviceEnvSnapshot = { ...info, ...provisioning };
+    // Per-pid+timestamp tmp name so concurrent globalSetups don't
+    // clobber each other's in-flight tmp files.
+    const tmp = `${file}.${process.pid}.${Date.now()}.tmp`;
+    writeFileSync(tmp, `${JSON.stringify(snapshot, null, 2)}\n`, "utf8");
+    renameSync(tmp, file);
+}
+
+export function logDeviceDiagnostic(info: DeviceInfo, provisioning: LeaseProvisioning = {}): void {
+    // The rootfs is appended to the SAME line rather than logged separately
+    // so a `grep "\[device-test-client\] device:"` over a CI log still yields
+    // one self-contained record per job.
+    const rootfs = provisioning.rootfsArtifactoryPath;
+    const rootfsSuffix = rootfs === undefined ? "" : `, rootfs ${rootfs}`;
+    console.log(
+        `[device-test-client] device: ${info.modelName} (${info.modelNumber}), ` +
+            `firmware ${info.firmwareVersion}, videoMode ${info.videoMode}, locale ${info.locale}${rootfsSuffix}`
+    );
+}
+
+/** Trim a single trailing `/` — shared helper for `rk server` URL composition. */
+export function trimTrailingSlash(s: string): string {
+    return s.endsWith("/") ? s.slice(0, -1) : s;
+}