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

package/src/index.ts

@@ -0,0 +1,181 @@
+// 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.
+ *
+ * **Harness support entry points.** The `package.json` `exports` map
+ * has no `./src/*` wildcard. Symbols kept off this barrel for harness
+ * code are on documented `./support/<name>` entry points:
+ *
+ *   - `@roku-sdk/device-test-client/support/deploy` — `resolveAppPath`
+ *     and `invalidateBuildCacheForApp` for a deploy guard that wipes
+ *     and rebuilds an app between retries.
+ *   - `@roku-sdk/device-test-client/support/constants` — the subset of
+ *     `src/constants.ts` (currently `ARTIFACT_FILE`) that `*.config.ts`
+ *     files load at parse time. This barrel is unreachable from
+ *     CommonJS-mode config loaders because it transitively pulls in
+ *     `@roku-sdk/tooling` ESM (`import.meta.url`); this entry point
+ *     bypasses that chain.
+ *   - `@roku-sdk/device-test-client/support/paths` — load-safe
+ *     `test-results/` path helpers used by multi-device test setup.
+ *
+ * The former `./internal/<name>` subpaths were removed (BREAKING_CHANGES.md).
+ * Prefer extending an existing `support/<name>` entry point over
+ * minting a parallel one, and never reintroduce the wildcard: every
+ * `./src/<x>` deep import bound the module topology into the
+ * published API surface.
+ *
+ * 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;
+}

package/src/jest/device-test-environment.ts

@@ -0,0 +1,420 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+/**
+ * Custom Jest environment that hooks `handleTestEvent` to capture
+ * device-side artifacts on failure and writes them to
+ * `<testResultsDir>/failures/<sanitized>/`. Used over `afterEach`
+ * because circus emits structured `test_fn_failure`/`hook_failure`
+ * events with the actual error.
+ *
+ * Capture runs EAGERLY on each failure event (not at teardown) so
+ * screenshots/DOM/logs reflect the device state at the moment of
+ * failure rather than after the next test's `beforeAll` deploys
+ * over it. Disk writes are still deferred to `teardown` (off the
+ * hot path).
+ *
+ * Globals set by the consumer's `setup.ts`:
+ *   - `DEVICE_ENV_GLOBAL_KEY.CLIENT` — RkClient
+ *   - `DEVICE_ENV_GLOBAL_KEY.TEST_RESULTS_DIR` — abs path
+ *   - `DEVICE_ENV_GLOBAL_KEY.CAPTURE_ENABLED` — opt-out flag
+ *
+ * All optional. Capture short-circuits when `CAPTURE_ENABLED ===
+ * false`, or when both `CAPTURE_ENABLED` and `TEST_RESULTS_DIR`
+ * are undefined (vanilla consumer that picked this env via
+ * misconfigured preset).
+ */
+
+import { join } from "node:path";
+
+import { DEVICE_ENV_GLOBAL_KEY, FAILURE_RECENT_LOG_LINES } from "../constants";
+import { TEST_RESULTS_DIR_NAME } from "../paths";
+import type { LogLine } from "../types";
+import { ensureFailuresDir, sanitizeTestPath, writeFailureBundle } from "./failure-artifacts";
+
+// Runtime `require()` of `jest-environment-node` keeps the
+// dependency out of our TS type graph and picks whichever Jest
+// version is hosting the worker (29 or 30).
+
+interface NodeEnvironmentConstructor {
+    new (config: unknown, context?: unknown): NodeEnvironmentLike;
+}
+
+/** Base class shape; `any` to avoid coupling to Jest 29 vs 30. */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type NodeEnvironmentLike = any;
+
+/* eslint-disable @typescript-eslint/no-require-imports */
+const NodeEnvModule = require("jest-environment-node");
+/* eslint-enable @typescript-eslint/no-require-imports */
+
+// Both Jest 29 and 30 export the class as `TestEnvironment`.
+const NodeEnvironment: NodeEnvironmentConstructor = NodeEnvModule.TestEnvironment;
+
+// Local circus-event shapes (stable across Jest 29/30) so we don't
+// need `@jest/types` as a dep.
+
+interface CircusNamedBlock {
+    name: string;
+    parent?: CircusNamedBlock;
+}
+
+interface CircusTestEntry extends CircusNamedBlock {
+    errors?: unknown[];
+}
+
+interface CircusHook extends CircusNamedBlock {
+    type: string;
+}
+
+interface TestFnFailureEvent {
+    name: "test_fn_failure";
+    test: CircusTestEntry;
+    error?: unknown;
+}
+
+interface HookFailureEvent {
+    name: "hook_failure";
+    hook: CircusHook;
+    test?: CircusTestEntry;
+    error?: unknown;
+}
+
+interface TeardownEvent {
+    name: "teardown";
+}
+
+type KnownEvent = TestFnFailureEvent | HookFailureEvent | TeardownEvent;
+
+// Structural client shape — keeps the environment decoupled from
+// the full client module graph so unit tests can inject fakes.
+export interface FailureCaptureClient {
+    captureScreenshot(): Promise<Buffer>;
+    queryAppUi(): Promise<unknown>;
+    recentLogLines(n: number): ReadonlyArray<{ seq: number; line: LogLine }>;
+    /** Optional; older clients/fakes may omit. Probed before calling. */
+    getLogStreamHealth?(): Promise<Record<string, unknown>>;
+}
+
+interface PendingFailure {
+    /** describe ancestors + it name (root excluded). */
+    testPath: string[];
+    error: unknown;
+    /** Device-side artifacts captured at failure event time (best-effort). */
+    screenshot: Buffer | null;
+    domTree: unknown;
+    recentLogs: ReadonlyArray<{ seq: number; line: LogLine }> | null;
+    streamHealth: Record<string, unknown> | null;
+    /** Capture-time warnings; merged with write-time on flush. */
+    captureWarnings: Array<{ artifact: string; cause: Error }>;
+}
+
+/**
+ * Subclass of `jest-environment-node`'s `TestEnvironment`. Implements
+ * `handleTestEvent` to buffer failures and flush them on `teardown`.
+ */
+export default class DeviceTestEnvironment extends NodeEnvironment {
+    /** Failure buffer — flushed once on the single `teardown` event. */
+    private pendingFailures: PendingFailure[] = [];
+
+    async handleTestEvent(event: unknown, _state: unknown): Promise<void> {
+        const typed = event as KnownEvent;
+        if (typed.name === "test_fn_failure") {
+            if (!this.shouldCapture()) return;
+            await this.recordFailure(buildTestPath(typed.test), pickError(typed.test.errors, typed.error));
+            return;
+        }
+        if (typed.name === "hook_failure") {
+            if (!this.shouldCapture()) return;
+            const testPath = typed.test ? buildTestPath(typed.test) : buildHookPath(typed.hook);
+            await this.recordFailure(testPath, typed.error ?? new Error(`${typed.hook.type} failed`));
+            return;
+        }
+        if (typed.name === "teardown") {
+            await this.flushPendingFailures();
+        }
+    }
+
+    /**
+     * Capture gate. `CAPTURE_ENABLED === false` → off; both
+     * `CAPTURE_ENABLED` and `TEST_RESULTS_DIR` undefined → off
+     * (vanilla consumer didn't opt in). Defensive overlap with the
+     * flush guard in case globals mutate between events.
+     */
+    private shouldCapture(): boolean {
+        const envGlobal = this.global as Record<string, unknown>;
+        const captureEnabled = envGlobal[DEVICE_ENV_GLOBAL_KEY.CAPTURE_ENABLED];
+        if (captureEnabled === false) return false;
+        if (captureEnabled === undefined && envGlobal[DEVICE_ENV_GLOBAL_KEY.TEST_RESULTS_DIR] === undefined) {
+            return false;
+        }
+        return true;
+    }
+
+    /**
+     * Capture device-side artifacts NOW (eager). Runs inside Jest's
+     * awaited `handleTestEvent`, blocking the next `beforeEach` until
+     * the snapshot is in hand. Each call wrapped in `captureArtifact`
+     * so one throw doesn't abort the others.
+     */
+    private async recordFailure(testPath: string[], error: unknown): Promise<void> {
+        const envGlobal = this.global as Record<string, unknown>;
+        const client = envGlobal[DEVICE_ENV_GLOBAL_KEY.CLIENT] as FailureCaptureClient | undefined;
+
+        const captureWarnings: Array<{ artifact: string; cause: Error }> = [];
+        let screenshot: Buffer | null = null;
+        let domTree: unknown = null;
+        let recentLogs: ReadonlyArray<{ seq: number; line: LogLine }> | null = null;
+        let streamHealth: Record<string, unknown> | null = null;
+
+        if (client) {
+            screenshot = await captureArtifact("screenshot", () => client.captureScreenshot(), captureWarnings);
+            domTree = await captureArtifact("dom-tree", () => client.queryAppUi(), captureWarnings);
+            recentLogs =
+                (await captureArtifact(
+                    "recent-logs",
+                    async () => client.recentLogLines(FAILURE_RECENT_LOG_LINES),
+                    captureWarnings
+                )) ?? [];
+            if (typeof client.getLogStreamHealth === "function") {
+                streamHealth = await captureArtifact(
+                    "stream-health",
+                    async () => {
+                        // Re-narrow locally; the closure doesn't see
+                        // the typeof guard above.
+                        const fn = client.getLogStreamHealth!;
+                        return await fn.call(client);
+                    },
+                    captureWarnings
+                );
+            }
+        }
+
+        // Surface the one-line stream-health summary so CI stdout
+        // shows gap context inline with the failure without
+        // requiring the reviewer to fetch the on-disk bundle.
+        // Routed through `console.warn` (not error.message/.stack
+        // mutation) because (a) Jest's reporter pipes our console
+        // calls right next to the failure, so visibility is
+        // preserved, and (b) mutating foreign Error objects
+        // throws on frozen errors and breaks custom matchers that
+        // pin on `expect(err.message).toMatch(...)`. The bundle
+        // already persists `streamHealth` separately for offline
+        // analysis, so this is purely an inline-visibility hook.
+        emitStreamHealthSummary(testPath, streamHealth);
+
+        this.pendingFailures.push({
+            testPath,
+            error,
+            screenshot,
+            domTree,
+            recentLogs,
+            streamHealth,
+            captureWarnings
+        });
+    }
+
+    /**
+     * Drain `pendingFailures` and write one bundle per failure. All
+     * work is best-effort and must not propagate out of `teardown`.
+     * Emits at most ONE warning per bundle covering every capture +
+     * write failure for that bundle.
+     */
+    private async flushPendingFailures(): Promise<void> {
+        if (this.pendingFailures.length === 0) return;
+        const envGlobal = this.global as Record<string, unknown>;
+
+        // Defensive re-check: a late `CAPTURE_ENABLED = false`
+        // write still suppresses on-disk output.
+        if (!this.shouldCapture()) {
+            this.pendingFailures = [];
+            return;
+        }
+
+        const resultsDir = resolveTestResultsDir(envGlobal);
+        let failuresDir: string;
+        try {
+            failuresDir = ensureFailuresDir(resultsDir);
+        } catch (err) {
+            console.warn(
+                `[device-test-client] could not create failures dir at "${resultsDir}": ` +
+                    `${(err as Error).message}. Failure diagnostics will be skipped.`,
+                err
+            );
+            this.pendingFailures = [];
+            return;
+        }
+
+        for (const failure of this.pendingFailures) {
+            const sanitized = sanitizeTestPath(failure.testPath);
+            const bundleDir = join(failuresDir, sanitized);
+
+            // Capture-time + write-time warnings → ONE warn per bundle.
+            const warnings: Array<{ artifact: string; cause: Error }> = [...failure.captureWarnings];
+
+            const result = writeFailureBundle(bundleDir, {
+                screenshot: failure.screenshot,
+                domTree: failure.domTree,
+                recentLogs: failure.recentLogs,
+                streamHealth: failure.streamHealth,
+                error: failure.error
+            });
+
+            for (const f of result.failed) {
+                warnings.push(f);
+            }
+
+            if (warnings.length > 0) {
+                emitBundleWarning(sanitized, warnings);
+            }
+
+            // One-line pointer so reviewers find the bundle without
+            // knowing the `test-results/failures/...` convention.
+            // Skipped when nothing landed (mkdir failure).
+            if (result.written.length > 0) {
+                console.log(
+                    `[device-test-client] failure bundle written: ${bundleDir} ` + `(${result.written.join(", ")})`
+                );
+            }
+        }
+
+        this.pendingFailures = [];
+    }
+}
+
+/**
+ * Await `fn`; on throw, push `{artifact, cause}` and return null so
+ * the bundle writer still gets a partial input. Caller emits one
+ * consolidated warning per bundle.
+ */
+async function captureArtifact<T>(
+    artifact: string,
+    fn: () => Promise<T>,
+    warnings: Array<{ artifact: string; cause: Error }>
+): Promise<T | null> {
+    try {
+        return await fn();
+    } catch (err) {
+        warnings.push({ artifact, cause: toError(err) });
+        return null;
+    }
+}
+
+/**
+ * One warn per bundle. Pass each underlying `Error` separately so
+ * Node's console printer renders the full stack.
+ */
+function emitBundleWarning(sanitized: string, warnings: ReadonlyArray<{ artifact: string; cause: Error }>): void {
+    const summary = warnings.map(w => `${w.artifact}=${w.cause.message}`).join("; ");
+    console.warn(`[device-test-client] bundle "${sanitized}" had warnings: ${summary}`, ...warnings.map(w => w.cause));
+}
+
+function toError(err: unknown): Error {
+    return err instanceof Error ? err : new Error(String(err));
+}
+
+/**
+ * Emit a one-line stream-health summary via `console.warn` so
+ * Jest's reporter renders it inline with the failure. Replaces an
+ * earlier in-place mutation of `error.message`/`error.stack`,
+ * which threw on frozen errors and broke custom matchers that
+ * pinned on `expect(err.message).toMatch(...)`.
+ *
+ * Skipped on trivial snapshots so healthy runs don't gain noise.
+ * `testPath` is included in the prefix so a multi-failure run
+ * still attributes each summary to the right test.
+ */
+function emitStreamHealthSummary(testPath: string[], health: Record<string, unknown> | null): void {
+    if (!health) return;
+    const summary = formatStreamHealthSummary(health);
+    if (!summary) return;
+    const label = testPath.length > 0 ? testPath.join(" › ") : "<unknown test>";
+    console.warn(`[device-test-client] [log-stream-health] ${label}: ${summary}`);
+}
+
+/**
+ * One-line `LogStreamHealth` summary; `""` for trivially-clean
+ * snapshots so healthy runs stay terse. Reads fields defensively
+ * to avoid an env→types import edge.
+ */
+function formatStreamHealthSummary(health: Record<string, unknown>): string {
+    const gapCount = numberFrom(health.gapCount, 0);
+    const totalGapSeqSpan = numberFrom(health.totalGapSeqSpan, 0);
+    const openGap = health.openGap === true;
+    const server = isObject(health.serverMetrics) ? health.serverMetrics : null;
+    const reconnectCount = server ? numberFrom(server.reconnectCount, 0) : 0;
+    const totalDowntime = server ? numberFrom(server.totalDowntime, 0) : 0;
+    const trivial = gapCount === 0 && reconnectCount === 0 && !openGap;
+    if (trivial) return "";
+    const parts: string[] = [];
+    parts.push(`client gaps=${gapCount} (span=${totalGapSeqSpan} seqs)`);
+    if (openGap) parts.push(`open-gap=true`);
+    if (server) {
+        parts.push(`server reconnects=${reconnectCount} downtime=${Math.round(totalDowntime)}ms`);
+    } else if (health.serverMetrics === null) {
+        parts.push(`server metrics unavailable (rk server unreachable)`);
+    }
+    return parts.join("; ");
+}
+
+function numberFrom(v: unknown, fallback: number): number {
+    return typeof v === "number" && Number.isFinite(v) ? v : fallback;
+}
+
+function isObject(v: unknown): v is Record<string, unknown> {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+/** Build `[...describeAncestors, testName]`; drops ROOT_DESCRIBE_BLOCK. */
+function buildTestPath(test: CircusTestEntry): string[] {
+    const parts: string[] = [];
+    const ancestors: string[] = [];
+    let cursor: CircusNamedBlock | undefined = test.parent;
+    while (cursor) {
+        ancestors.unshift(cursor.name);
+        cursor = cursor.parent;
+    }
+    for (const name of ancestors) {
+        if (name === "ROOT_DESCRIBE_BLOCK") continue;
+        parts.push(name);
+    }
+    parts.push(test.name);
+    return parts;
+}
+
+/** Path for a hook failure with no test; leaf = `hook-<type>`. */
+function buildHookPath(hook: CircusHook): string[] {
+    const parts: string[] = [];
+    const ancestors: string[] = [];
+    let cursor: CircusNamedBlock | undefined = hook.parent;
+    while (cursor) {
+        ancestors.unshift(cursor.name);
+        cursor = cursor.parent;
+    }
+    for (const name of ancestors) {
+        if (name === "ROOT_DESCRIBE_BLOCK") continue;
+        parts.push(name);
+    }
+    parts.push(`hook-${hook.type}`);
+    return parts;
+}
+
+/**
+ * Pick the most actionable error from a circus entry. Last entry
+ * wins (follow-on errors are less interesting than the original).
+ */
+function pickError(errors: unknown[] | undefined, fallback: unknown): unknown {
+    if (errors && errors.length > 0) {
+        const last = errors[errors.length - 1];
+        if (Array.isArray(last) && last.length > 0) return last[0];
+        return last;
+    }
+    return fallback ?? new Error("unknown test failure");
+}
+
+function resolveTestResultsDir(envGlobal: Record<string, unknown>): string {
+    const fromGlobal = envGlobal[DEVICE_ENV_GLOBAL_KEY.TEST_RESULTS_DIR];
+    if (typeof fromGlobal === "string" && fromGlobal.length > 0) {
+        return fromGlobal;
+    }
+    return join(process.cwd(), TEST_RESULTS_DIR_NAME);
+}