@roku-sdk/device-test-client 2.18.0 → 2.19.1

package/src/client/client.ts

@@ -11,6 +11,7 @@ import {
     xmlToJson,
     xmlToKeyValue
 } from "@roku-sdk/tooling/src/device-test-helpers";
+import type { DeviceTarget } from "@roku-sdk/tooling/src/tooling-utils/device-target";
 import { PNG } from "pngjs";
 
 import { summarizeTree, tryFindNode } from "../assertions/assertions";
@@ -23,11 +24,16 @@ import {
     ECP_INTERVAL_MS,
     ECP_RETRY_BACKOFF_MS,
     ENV_VAR,
+    FOREGROUND_FAILURE_STREAK_FATAL,
     HOME_SCREEN_GRACE_FRACTION,
     HOME_SCREEN_GRACE_MIN_MS,
     INSTALLER_PORT_PROBE_DEFAULT_TIMEOUT_MS,
     INSTALLER_PORT_PROBE_INTERVAL_MS,
     INSTALLER_PORT_TCP_TIMEOUT_MS,
+    INTEGRATION_BUILD_OUT_DIR,
+    LAUNCH_CRASH_RELAUNCH_GAP_MS,
+    LAUNCH_CRASH_RELAUNCH_MAX,
+    LOG_STREAM_RESYNC_GRACE_MS,
     READINESS_CONFIRM_POLLS,
     READINESS_POLL_INTERVAL_MS,
     READINESS_TIMEOUT_MS,
@@ -52,7 +58,7 @@ import {
     WaitForLogTimeoutError,
     WaitForNodeTimeoutError
 } from "../errors";
-import { parsePos } from "../logs/log-buffer";
+import { LogBuffer, parsePos } from "../logs/log-buffer";
 import { LogSession } from "../logs/log-session";
 import type {
     ActiveAppInfo,
@@ -60,6 +66,7 @@ import type {
     BuildAndDeployOptions,
     BuildAndLaunchWithParamsOptions,
     CaptureStableOptions,
+    DeploymentDriver,
     DeviceInfo,
     EcpCategory,
     KeySequenceOptions,
@@ -81,6 +88,7 @@ import type {
 import { getOrCreateBuildPromise, invalidateBuildCacheForApp } from "./build-cache";
 import type { ToolingDeps, ToolingDevice } from "./deploy";
 import {
+    buildLaunchPath,
     buildLaunchUrl,
     directoryExists,
     loadToolingDeps,
@@ -92,7 +100,13 @@ import {
 } from "./deploy";
 import { EcpRequestQueue } from "./ecp-queue";
 import { isEcpServerError, isTransientEcpError, retryOnTransient } from "./ecp-retry";
-import { markDeviceFatal, markDeviceUnhealthy } from "./health";
+import {
+    hasForegroundedChannel,
+    markChannelForegrounded,
+    markDeviceFatal,
+    markDeviceUnhealthy,
+    noteForegroundFailure
+} from "./health";
 import { asNodeTuple, isHomeScreenActiveApp, parseActiveApp, parseDeviceInfo, tupleToAppUiNode } from "./parsers";
 import { resolveServerUrl as resolveServerUrlShared } from "./server-url";
 
@@ -104,7 +118,9 @@ export class RkClient {
     public readonly keyDelay: number;
     public readonly deviceIp: string;
 
-    private readonly ecp: EcpClient;
+    private ecp: EcpClient;
+    private readonly driver: DeploymentDriver | undefined;
+    private driverTarget: DeviceTarget | undefined;
     private readonly queue: EcpRequestQueue;
     private readonly requestTimeoutMs: number;
     private readonly serverUrl: string;
@@ -112,23 +128,26 @@ export class RkClient {
     private _cachedDeviceInfo: DeviceInfo | null = null;
 
     constructor(opts: RkClientOptions = {}) {
-        if (!opts.deviceIp) {
+        this.driver = opts.driver;
+        if (!opts.deviceIp && !opts.driver) {
             throw new RkClientError(
                 `RkClient requires a deviceIp. Use createDefaultClient() for env-driven resolution.`,
                 "RK_DEVICE_IP_UNRESOLVED"
             );
         }
-        this.deviceIp = opts.deviceIp;
+        this.deviceIp = opts.deviceIp ?? opts.driver!.label;
         this.keyDelay = opts.keyDelay ?? DEFAULT_KEY_DELAY;
         this.requestTimeoutMs = opts.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
         this.serverUrl = resolveServerUrl(opts.serverUrl);
 
-        this.ecp = new EcpClient(this.deviceIp, this.requestTimeoutMs);
+        this.driverTarget = opts.driver?.initialTarget;
+        this.ecp = new EcpClient(this.driverTarget ?? this.deviceIp, this.requestTimeoutMs);
         this.queue = new EcpRequestQueue({ ...ECP_INTERVAL_MS, ...opts.intervals });
         // Construction is free (no I/O); first `ensureStarted()` POSTs
         // `/logs/start` and opens the SSE tail.
         this.logSession =
             opts.logSession ??
+            (opts.driver ? driverLogSession(opts.driver) : undefined) ??
             new LogSession({
                 serverUrl: this.serverUrl,
                 device: this.deviceIp,
@@ -136,6 +155,11 @@ export class RkClient {
             });
     }
 
+    /** Stop whatever the deployment driver started; no-op without one. Idempotent. */
+    async releaseDriver(): Promise<void> {
+        await this.driver?.release?.();
+    }
+
     /** Accessor for the active `rk server` URL (for setup helpers). */
     getServerUrl(): string {
         return this.serverUrl;
@@ -313,11 +337,26 @@ export class RkClient {
         return parseActiveApp(root);
     }
 
-    /** PNG screenshot bytes; rate-limited at 500ms between captures. */
+    /**
+     * PNG screenshot bytes; rate-limited at 500ms between captures. Throws on a driver-hosted run:
+     * pixel baselines are recorded from a physical device, so a capture from another host must fail
+     * loudly rather than compare against the wrong rendering and pass.
+     */
     async captureScreenshot(): Promise<Buffer> {
+        this.assertScreenshotSupported();
         return this.runEcp("capture", () => this.ecp.captureScreen("png"));
     }
 
+    private assertScreenshotSupported(): void {
+        if (this.driver) {
+            throw new RkClientError(
+                `Screenshot capture is not supported on this target (deployment driver "${this.driver.label}"). ` +
+                    "Use app-ui queries, or run the test on a device.",
+                "SCREENSHOT_UNSUPPORTED_TARGET"
+            );
+        }
+    }
+
     /**
      * Validate and send one keypress. Invalid keys throw before hitting
      * the queue so a typo in a test doesn't consume a slot.
@@ -329,6 +368,21 @@ export class RkClient {
         });
     }
 
+    /**
+     * Hold a key down for `holdMs` (ECP keydown, wait, keyup). The release is
+     * sent even if the wait is interrupted, so a failed test never leaves a
+     * key stuck down on the target.
+     */
+    async holdKey(key: string, holdMs: number): Promise<void> {
+        const normalized = normalizeKeyOrThrow(key);
+        await this.runEcp("keypress", () => this.ecp.keypress(normalized, "keydown"));
+        try {
+            await sleepUnref(holdMs);
+        } finally {
+            await this.runEcp("keypress", () => this.ecp.keypress(normalized, "keyup"));
+        }
+    }
+
     /**
      * Send a sequence of keypresses with an inter-key delay (between end
      * of one and start of next). All keys validated up-front so a typo
@@ -377,18 +431,29 @@ export class RkClient {
      * block on the readiness + dialog gate. HTTP errors propagate verbatim
      * unless the auto-launch fallback below absorbs them; readiness/dialog
      * failures already arrive as `DeployFailedError`.
+     *
+     * `logSince` marks where this launch's device log starts. A sideload
+     * passes the position from before `replace()`, which already launches
+     * the build; it defaults to the position before the POST.
      */
     private async launchAndAwaitReady(
         channelId: string,
         deepLink: Record<string, string> | undefined,
         timeoutMs: number,
-        readyNode?: NodePredicate
+        readyNode?: NodePredicate,
+        logSince: LogPosition = this.logPosition()
     ): Promise<void> {
-        const url = buildLaunchUrl(this.deviceIp, channelId, deepLink);
+        // The relaunch goes through `postLaunch`, so a driver-hosted run uses the driver's transport
+        // and never builds a URL from the driver's display label.
+        const gate = {
+            channelId,
+            timeoutMs,
+            readyNode,
+            relaunch: () => this.postLaunch(channelId, deepLink),
+            logSince
+        };
         try {
-            await this.runEcp("launch", async () => {
-                await postNoBody(url, this.requestTimeoutMs);
-            });
+            await this.runEcp("launch", () => this.postLaunch(channelId, deepLink));
         } catch (err) {
             // Newer firmware auto-launches sideloaded `dev` builds after
             // `replace()`, so the POST races a launch that is already
@@ -396,12 +461,12 @@ export class RkClient {
             // waiting on the auto-launched app instead of treating the
             // POST verdict as fatal.
             if (channelId === "dev" && deepLink === undefined && isAutoLaunchTolerableError(err)) {
-                await this.awaitReadyAndCheckDialog({ channelId, timeoutMs, readyNode });
+                await this.awaitReadyAndCheckDialog(gate);
                 return;
             }
             throw err;
         }
-        await this.awaitReadyAndCheckDialog({ channelId, timeoutMs, readyNode });
+        await this.awaitReadyAndCheckDialog(gate);
     }
 
     // -----------------------------------------------------------------
@@ -430,6 +495,62 @@ export class RkClient {
         return RkClient.detectSystemDialog(tree);
     }
 
+    /**
+     * What the device log since `since` says about `channelId`'s launch:
+     * whether it entered, and how many times it then exited with
+     * `EXIT_APP_ERROR`, the code for a channel that failed while starting.
+     * The log cannot tell a firmware launch failure from a build that
+     * crashes during mount; the relaunch cap and the failure streak bound
+     * what the second costs. Code that ran and then threw exits with
+     * another code and is not counted.
+     * An exit with no Entering line before it belongs to the build
+     * `replace()` ended. Reads only the client's buffer, so with no log
+     * session, or with `since` already evicted, it reports nothing.
+     */
+    private channelLaunchLog(since: LogPosition, channelId: string): { entered: boolean; failedLaunches: number } {
+        let lines: LogLine[];
+        try {
+            lines = this.logSession.buffer.linesSince(since);
+        } catch {
+            return { entered: false, failedLaunches: 0 };
+        }
+        const id = channelId.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+        const enter = new RegExp(`\\[scrpt\\.ctx\\.run\\.enter\\].*, id '${id}'`);
+        const failedExit = new RegExp(`\\[scrpt\\.ctx\\.run\\.exit\\].*, id '${id}', EXIT_APP_ERROR\\b`);
+        let entered = false;
+        let failedLaunches = 0;
+        for (const line of lines) {
+            if (enter.test(line)) {
+                entered = true;
+            } else if (entered && failedExit.test(line)) {
+                failedLaunches += 1;
+            }
+        }
+        return { entered, failedLaunches };
+    }
+
+    /**
+     * Re-request a launch the device log shows ending before the channel
+     * reached the screen. Best-effort: the readiness poll that follows
+     * judges the outcome, and a launcher busy with the previous attempt
+     * may reject the request.
+     */
+    private async relaunchAfterLaunchExit(
+        relaunch: () => Promise<void>,
+        channelId: string,
+        attempt: number
+    ): Promise<void> {
+        console.warn(
+            `[device-test-client] channel "${channelId}" exited before reaching the screen; ` +
+                `relaunching (${attempt}/${LAUNCH_CRASH_RELAUNCH_MAX}).`
+        );
+        try {
+            await this.runEcp("launch", relaunch);
+        } catch {
+            // See doc-block.
+        }
+    }
+
     /**
      * Single-shot crash probe used by polling loops between ticks.
      * Throws `AppCrashedError` if active-app is a home surface — see
@@ -528,6 +649,11 @@ export class RkClient {
         let lastStatus = "unknown";
         let lastErrorMessage: string | undefined;
 
+        // With a driver the installer arm is not probed from here: a driver's label is not an address, and
+        // the driver's own deploy retries until its host accepts the sideload, which is the readiness
+        // signal for `replace()` (the RCE driver included).
+        if (this.driver) return info;
+
         do {
             attempts += 1;
             const result = await tcpProbe(this.deviceIp, ROKU_INSTALLER_PORT, INSTALLER_PORT_TCP_TIMEOUT_MS);
@@ -563,6 +689,10 @@ export class RkClient {
      * fallback) passes on the same iteration — avoids one-tick races where
      * the app is launching but the scene has not rendered.
      *
+     * A poll also requires (c) no firmware overlay (`osd`) left in the
+     * tree, so "ready" means the app owns the screen rather than
+     * merely having rendered behind the launch facade.
+     *
      * Stability: requires `READINESS_CONFIRM_POLLS` consecutive matches
      * before declaring ready, catching the "crash shortly after splash"
      * pattern. Home-screen responses are tolerated while we have not
@@ -571,11 +701,19 @@ export class RkClient {
      * the full readiness budget expires. Once we HAVE seen app-owned
      * evidence, a persistent post-grace Home response is classified as
      * crashed-after-ready.
+     *
+     * The device log since `logSince` is the one signal that separates a
+     * launch that started and failed from one that never started: when it
+     * shows the channel exiting with `EXIT_APP_ERROR` after it entered,
+     * and the screen is Home past the grace window, `relaunch` is
+     * called again, up to `LAUNCH_CRASH_RELAUNCH_MAX` times.
      */
     private async awaitReadyAndCheckDialog(opts: {
         channelId: string;
         timeoutMs: number;
         readyNode?: NodePredicate;
+        relaunch: () => Promise<void>;
+        logSince: LogPosition;
     }): Promise<void> {
         const startedAt = Date.now();
         const deadline = startedAt + opts.timeoutMs;
@@ -611,6 +749,21 @@ export class RkClient {
         // explicitly identified the target channel. Once this is true,
         // a later Home report is a crash signal rather than active-app lag.
         let hadActiveChannelEvidence = false;
+        // Each logged launch failure earns at most one relaunch.
+        let relaunches = 0;
+        let lastLaunchAt = startedAt;
+        let failuresAnswered = 0;
+
+        // App-owned evidence of any kind — the channel in the tree, or its
+        // own ready node rendering — proves this VM foregrounds a sideloaded
+        // channel, which disqualifies the fatal verdict at the end of this
+        // method for the rest of the run. Reaching readiness is sufficient
+        // but not necessary: an app that renders and then never satisfies
+        // the caller's predicate still got foregrounded.
+        const noteChannelEvidence = (): void => {
+            hadChannelEvidence = true;
+            markChannelForegrounded(this.deviceIp);
+        };
 
         const treeContainsChannel = (node: AppUiNode, channelId: string): boolean => {
             if (node.tag === "plugin" && node.attrs?.id === channelId) {
@@ -619,6 +772,18 @@ export class RkClient {
             return node.children.some(child => treeContainsChannel(child, channelId));
         };
 
+        // A firmware overlay still in the tree — the launch facade a
+        // channel start puts up, reported as `<osd type="FacadeScreen"
+        // focused="true">`. The app's own nodes can already be behind
+        // it, so a predicate match on its own proves neither that the
+        // app is on screen nor that it can receive a key; a caller that
+        // captures a tree or presses a key the moment we return gets a
+        // node the baseline never had, and presses the facade swallows.
+        // Any `osd` counts, not just a focused one: it is firmware
+        // chrome either way, and a launched app's steady state has none.
+        const treeContainsOverlay = (node: AppUiNode): boolean =>
+            node.children.some(child => child.tag === "osd" || treeContainsOverlay(child));
+
         while (Date.now() < deadline) {
             const active = await this.queryActiveApp();
             lastActiveApp = active;
@@ -637,7 +802,7 @@ export class RkClient {
                     // tree as a stronger signal than active-app.
                     channelVisibleInTree = treeContainsChannel(tree, opts.channelId);
                     if (idMatches || channelVisibleInTree) {
-                        hadChannelEvidence = true;
+                        noteChannelEvidence();
                         hadActiveChannelEvidence = true;
                     }
                 } catch (err) {
@@ -665,7 +830,12 @@ export class RkClient {
                 opts.readyNode && isHomeScreenActiveApp(active) && predicateMatches && !hadActiveChannelEvidence
             );
             if (tree && (idMatches || channelVisibleInTree || readyNodeVisibleWhileHome)) {
-                if (predicateMatches) {
+                // The overlay check shares the stability counter rather
+                // than draining separately: the layer can blink out and
+                // back while it tears down, and `READINESS_CONFIRM_POLLS`
+                // consecutive clean polls already require it to be gone
+                // and stay gone.
+                if (predicateMatches && !treeContainsOverlay(tree)) {
                     // Dialog check on every match: a dialog appearing AFTER
                     // first-render must still fail the deploy.
                     const dialog = RkClient.detectSystemDialog(tree);
@@ -684,7 +854,7 @@ export class RkClient {
                     }
                     consecutiveMatches += 1;
                     hadAnyMatch = true;
-                    hadChannelEvidence = true;
+                    noteChannelEvidence();
                     if (consecutiveMatches >= READINESS_CONFIRM_POLLS) {
                         return;
                     }
@@ -718,6 +888,21 @@ export class RkClient {
                                 lastActiveApp: active
                             });
                         }
+                        // Active-app can report the channel for the
+                        // fraction of a second a failed launch lasts, so
+                        // channel evidence does not rule a relaunch out.
+                        if (
+                            relaunches < LAUNCH_CRASH_RELAUNCH_MAX &&
+                            Date.now() - lastLaunchAt >= LAUNCH_CRASH_RELAUNCH_GAP_MS
+                        ) {
+                            const { failedLaunches } = this.channelLaunchLog(opts.logSince, opts.channelId);
+                            if (failedLaunches > failuresAnswered) {
+                                failuresAnswered = failedLaunches;
+                                relaunches += 1;
+                                lastLaunchAt = Date.now();
+                                await this.relaunchAfterLaunchExit(opts.relaunch, opts.channelId, relaunches);
+                            }
+                        }
                         if (hadChannelEvidence && opts.readyNode) {
                             // The app launched but never satisfied the
                             // caller's readiness predicate. Do not relabel
@@ -743,14 +928,43 @@ export class RkClient {
         }
 
         if (lastActiveApp && isHomeScreenActiveApp(lastActiveApp) && !hadChannelEvidence) {
-            const reason = `app never left home screen after launch (active.id="${lastActiveApp.id}", title="${lastActiveApp.title}")`;
-            // FATAL, not merely unhealthy: the device answered ECP for the
-            // whole readiness budget but never foregrounded the sideloaded
-            // channel. ECP/installer liveness recovery cannot cure a
-            // foreground-incapable VM, so latch the process-wide fatal flag
-            // — the deploy-guard and recovery hook short-circuit on it
+            const launchLog = this.channelLaunchLog(opts.logSince, opts.channelId);
+            const exitDetail =
+                launchLog.failedLaunches > 0
+                    ? `; channel exited during launch ${launchLog.failedLaunches} time(s), relaunched ${relaunches} time(s)`
+                    : "";
+            const reason = `app never left home screen after launch (active.id="${lastActiveApp.id}", title="${lastActiveApp.title}"${exitDetail})`;
+            // Home for the whole budget with no channel evidence is either a
+            // foreground-incapable VM or a launch slower than the budget,
+            // and within a single deploy the two are identical. An earlier
+            // deploy that reached readiness on this VM breaks the tie: a
+            // device that has foregrounded a channel is not incapable of it,
+            // so the fault belongs to this launch and stays soft, letting
+            // the deploy-guard retry this deploy alone. The device log
+            // showing this deploy's channel entering breaks it the same
+            // way: the launch ran and died, so the VM can run one.
+            //
+            // Without that history, latch FATAL: ECP/installer liveness
+            // recovery cannot cure a foreground-incapable VM, so the
+            // deploy-guard and recovery hook short-circuit on the latch
             // instead of retrying every remaining suite against a dead VM.
-            markDeviceFatal(`deploy: app never left home screen after launch`);
+            // History earns a bounded number of soft verdicts, not an
+            // unlimited supply: a VM that worked and then died looks
+            // exactly like a bad launch from inside any single deploy,
+            // and staying soft forever means every remaining suite pays
+            // a full deploy budget against a dead VM until the job's own
+            // wall-clock kills it, which recycles nothing and retries
+            // nothing. Past the streak the verdict reverts to fatal so
+            // the cell recycles the slot and the job is retried on a
+            // live one.
+            if (
+                (hasForegroundedChannel(this.deviceIp) || launchLog.entered) &&
+                noteForegroundFailure(this.deviceIp) < FOREGROUND_FAILURE_STREAK_FATAL
+            ) {
+                markDeviceUnhealthy(`deploy: ${reason}`);
+            } else {
+                markDeviceFatal(`deploy: ${reason}`);
+            }
             throw new DeployFailedError(`Deploy failed: ${reason}`, {
                 deviceIp: this.deviceIp,
                 expectedChannelId: opts.channelId,
@@ -852,6 +1066,12 @@ export class RkClient {
      * could be partial/concatenated at the reconnect boundary).
      * `expectNoLog` is the asymmetric strict counterpart: absence is
      * unprovable across a gap.
+     *
+     * A window in which no line arrived at all gets one re-attach
+     * before the verdict: a subscription can stop delivering while
+     * both ends still believe it is attached, and from inside the
+     * wait that is indistinguishable from a device with nothing to
+     * say. See `LogSession.resync`.
      */
     async waitForLog(pattern: RegExp, opts: LogQueryOptions): Promise<LogLine> {
         await this.ensureLogSession();
@@ -878,14 +1098,23 @@ export class RkClient {
 
         return new Promise<LogLine>((resolve, reject) => {
             let settled = false;
+            let timer: ReturnType<typeof setTimeout> | undefined;
+            let resyncTried = false;
             const recent: LogLine[] = [];
             const settle = (fn: () => void): void => {
                 if (settled) return;
                 settled = true;
                 unsubscribe();
-                clearTimeout(timer);
+                if (timer !== undefined) clearTimeout(timer);
                 fn();
             };
+            const arm = (ms: number, onFire: () => void): void => {
+                timer = setTimeout(onFire, ms);
+                // Don't keep the event loop alive purely for this timer.
+                if (typeof (timer as { unref?: () => unknown }).unref === "function") {
+                    (timer as { unref: () => unknown }).unref();
+                }
+            };
             const unsubscribe = buffer.subscribe(entry => {
                 if (settled) return;
                 linesChecked += 1;
@@ -901,7 +1130,8 @@ export class RkClient {
                     settle(() => resolve(entry.line));
                 }
             });
-            const timer = setTimeout(() => {
+            const onDeadline = (): void => {
+                if (settled) return;
                 // A gap inside the window makes a non-result ambiguous;
                 // surface the gap rather than a bare timeout.
                 const gap = buffer.hasGapWithin(since);
@@ -916,10 +1146,37 @@ export class RkClient {
                     );
                     return;
                 }
+                // Not one line in the whole window, which an app with
+                // nothing to say and a stream that stopped delivering
+                // both produce, so re-attach and let the replay land
+                // before calling the marker absent. The subscription
+                // above stays live, so a replayed match resolves
+                // through it, and a replay that adds nothing is what
+                // narrows the verdict below to the app's own silence.
+                if (!resyncTried && linesChecked === 0 && typeof this.logSession.resync === "function") {
+                    resyncTried = true;
+                    arm(LOG_STREAM_RESYNC_GRACE_MS, onDeadline);
+                    void this.logSession.resync().catch(() => {
+                        // A failed re-attach adds no evidence; the
+                        // grace expires and the verdict below stands.
+                    });
+                    return;
+                }
                 const preview = recentLinesPreview(recent);
+                // Report what an empty window actually establishes. A
+                // re-attach that turned up nothing rules out lines lost
+                // on the way here, which leaves an app that logged
+                // nothing and a stream stalled at its far end — and
+                // those two are indistinguishable from this side.
+                // Naming only the stream would send the reader after a
+                // transport fault on every quiet window.
+                const silent =
+                    linesChecked === 0
+                        ? " — no output at all reached this window, re-attach included: the app logged nothing, or the stream stalled upstream"
+                        : "";
                 const msg =
                     `waitForLog timed out after ${timeoutMs}ms waiting for ${pattern} ` +
-                    `(since=${since}, linesChecked=${linesChecked})${preview ? `\nRecent lines:\n${preview}` : ""}`;
+                    `(since=${since}, linesChecked=${linesChecked}${silent})${preview ? `\nRecent lines:\n${preview}` : ""}`;
                 settle(() =>
                     reject(
                         new WaitForLogTimeoutError(msg, {
@@ -931,11 +1188,8 @@ export class RkClient {
                         })
                     )
                 );
-            }, timeoutMs);
-            // Don't keep the event loop alive purely for this timer.
-            if (typeof (timer as { unref?: () => unknown }).unref === "function") {
-                (timer as { unref: () => unknown }).unref();
-            }
+            };
+            arm(timeoutMs, onDeadline);
         });
     }
 
@@ -1077,6 +1331,11 @@ export class RkClient {
             );
         }
 
+        if (this.driver) {
+            await this.deployThroughDriver(absPath, opts);
+            return;
+        }
+
         // The build runs server-side via `requestServerBuild`, so we do
         // not need esbuild loaded in this process — keeps ~200 MiB of
         // orphan `esbuild --service` procs out of the build container.
@@ -1088,7 +1347,7 @@ export class RkClient {
 
         // Per-integration-test out-dir keeps artifacts out of the app's
         // own `dist-build` so local `rk build` runs don't collide.
-        const outDir = "dist-integration-test";
+        const outDir = INTEGRATION_BUILD_OUT_DIR;
         let pkgDir: string;
         // The build is memoised per-process via `getOrCreateBuildPromise`:
         // when the same `(absPath, outDir, buildType, dropConsole)` tuple
@@ -1160,6 +1419,7 @@ export class RkClient {
         const { ip, password } = await this.resolveTargetDevice(opts?.deviceSelector, absPath, tooling);
 
         const { appType, libraryName } = await readAppTypeFromManifest(pkgDir, tooling.readManifestEntries);
+        const launchLogSince = this.logPosition();
 
         try {
             const device = new tooling.RokuDevice(ip, password, await tooling.getTempDir());
@@ -1222,7 +1482,13 @@ export class RkClient {
         const channelId = opts?.channelId ?? "dev";
         const readinessTimeout = opts?.readinessTimeout ?? READINESS_TIMEOUT_MS;
         try {
-            await this.launchAndAwaitReady(channelId, opts?.deepLink, readinessTimeout, opts?.readyNode);
+            await this.launchAndAwaitReady(
+                channelId,
+                opts?.deepLink,
+                readinessTimeout,
+                opts?.readyNode,
+                launchLogSince
+            );
         } catch (err) {
             if (err instanceof DeployFailedError) {
                 invalidateBuildCacheForApp(absPath);
@@ -1245,6 +1511,26 @@ export class RkClient {
         }
     }
 
+    /** `buildAndDeploy` for a driver-hosted run: the driver builds and starts, ECP does readiness. */
+    private async deployThroughDriver(absPath: string, opts?: BuildAndDeployOptions): Promise<void> {
+        const channelId = opts?.channelId ?? "dev";
+        const logSince = this.logPosition();
+        try {
+            this.driverTarget = await this.driver!.deploy({ absPath, launchParams: opts?.deepLink });
+            this.ecp = new EcpClient(this.driverTarget, this.requestTimeoutMs);
+        } catch (err) {
+            invalidateBuildCacheForApp(absPath);
+            throw new BuildFailedError(`Build failed for ${absPath}: ${errorMessage(err)}.`, absPath, err);
+        }
+        await this.awaitReadyAndCheckDialog({
+            channelId,
+            timeoutMs: opts?.readinessTimeout ?? READINESS_TIMEOUT_MS,
+            readyNode: opts?.readyNode,
+            relaunch: () => this.postLaunch(channelId, opts?.deepLink),
+            logSince
+        });
+    }
+
     /**
      * Cold sideload + reliable deep-link delivery.
      *
@@ -1329,11 +1615,8 @@ export class RkClient {
         // the authoritative success signal.
         const ackPos = this.logPosition();
         const channelId = opts.channelId ?? "dev";
-        const launchUrl = buildLaunchUrl(this.deviceIp, channelId, deepLink);
         try {
-            await this.runEcp("launch", async () => {
-                await postNoBody(launchUrl, this.requestTimeoutMs);
-            });
+            await this.runEcp("launch", () => this.postLaunch(channelId, deepLink));
         } catch (err) {
             // The params-ack log — not the POST status — is the
             // authoritative signal here, so a POST that raced the
@@ -1458,6 +1741,7 @@ export class RkClient {
      * `lastPng` for artifacts (excluded from `toJSON`).
      */
     async captureStableScreenshot(opts: CaptureStableOptions): Promise<Buffer> {
+        this.assertScreenshotSupported();
         const interval = opts.interval ?? SCREENSHOT_STABLE_DEFAULT_INTERVAL_MS;
         const timeoutMs = opts.timeout;
         const deadline = Date.now() + timeoutMs;
@@ -1537,6 +1821,21 @@ export class RkClient {
      * Retry happens inside the queue slot so the backoff does not let
      * another request slip between the two attempts.
      */
+    /** POST the ECP launch request, through the driver's transport when one is in use. */
+    private async postLaunch(channelId: string, deepLink?: Record<string, string>): Promise<void> {
+        if (!this.driverTarget) {
+            await postNoBody(buildLaunchUrl(this.deviceIp, channelId, deepLink), this.requestTimeoutMs);
+            return;
+        }
+        // A driver's label is a display name (for example `rce:my-device`), not a host, so no URL is
+        // built from it: the transport only needs the path and query.
+        const path = buildLaunchPath(channelId, deepLink);
+        const res = await this.driverTarget.http(8060, path, { method: "POST" });
+        if (!res.ok) {
+            throw new Error(`POST ${path.split("?")[0]} failed: HTTP ${res.status}`);
+        }
+    }
+
     private runEcp<T>(category: EcpCategory, op: () => Promise<T>): Promise<T> {
         return this.queue.enqueue(category, () =>
             retryOnTransient(op, {
@@ -1547,6 +1846,15 @@ export class RkClient {
     }
 }
 
+/** A log session whose lines come from the driver's console feed instead of the rk server. */
+function driverLogSession(driver: DeploymentDriver): LogSessionLike {
+    const buffer = new LogBuffer();
+    driver.onLog(line => {
+        buffer.append(line);
+    });
+    return { ensureStarted: async () => {}, dispose: () => {}, buffer };
+}
+
 function errorMessage(err: unknown): string {
     if (err instanceof Error) return err.message;
     try {