@specific.dev/spectest 0.125.0 → 0.127.0

package/dist/android-step.d.ts

@@ -8,6 +8,13 @@ export interface AndroidTarget {
 export interface AndroidStepDetails {
     device: string;
     action: "tap" | "fill" | "text" | "visible" | "wait" | "swipe" | "back" | "source" | "screenshot" | "execute";
+    /** Normalized screen bounds observed by this operation. */
+    bounds?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
     target?: AndroidTarget;
     point?: {
         x: number;

package/dist/android.d.ts

@@ -24,10 +24,24 @@ export declare class AppiumError extends Error {
     readonly code: string;
     constructor(code: string, message: string);
 }
+export declare const ANDROID_ASSERT: unique symbol;
+export type AndroidMatcher = "toBeVisible" | "toBeHidden" | "toHaveText" | "toContainText";
+export interface AndroidAssertionResult {
+    sourceSeq?: number;
+    actual?: unknown;
+    error?: unknown;
+}
 export interface AndroidElement {
-    tap(): Promise<void>;
-    fill(text: string): Promise<void>;
-    text(): Promise<Wrapped<string>>;
+    [ANDROID_ASSERT](matcher: AndroidMatcher, negated: boolean, expected: string | RegExp | undefined, timeoutMs?: number): Promise<AndroidAssertionResult>;
+    tap(options?: {
+        timeoutMs?: number;
+    }): Promise<void>;
+    fill(text: string, options?: {
+        timeoutMs?: number;
+    }): Promise<void>;
+    text(options?: {
+        timeoutMs?: number;
+    }): Promise<Wrapped<string>>;
     isDisplayed(): Promise<Wrapped<boolean>>;
     waitFor(options?: {
         state?: "visible" | "hidden";

package/dist/android.js

@@ -42,6 +42,10 @@ async function session(app) {
             capabilities: {
                 alwaysMatch: {
                     platformName: "Android",
+                    // Conditions are explicit waits. Do not stack a session-wide lookup
+                    // wait or UiSelector's own 10s wait underneath their deadline.
+                    timeouts: { implicit: 0 },
+                    "appium:settings[waitForSelectorTimeout]": 0,
                     "appium:automationName": "UiAutomator2",
                     "appium:udid": app.serial,
                     "appium:appPackage": app.package,
@@ -65,6 +69,7 @@ async function session(app) {
     }
     return pending;
 }
+export const ANDROID_ASSERT = Symbol.for("spectest.androidAssert");
 const parked = new Map();
 let epoch = 0;
 /** A case owns capture and handle lifetime; the Android/Appium processes outlive it. */
@@ -155,13 +160,13 @@ export function androidScope(caseId, testStartedAt, options = {}) {
                     list.push(marker);
                 taps.set(app.name, list);
             }
-            async function op(operation, fn) {
+            async function op(operation, fn, settled) {
                 assertActive();
                 const android = { device: app.name, ...operation };
                 const title = androidStepTitle(android);
                 const reservation = reserveEvent(), started = Date.now();
                 try {
-                    const result = await fn();
+                    const result = await fn(android);
                     const seq = recordStep({
                         kind: "android",
                         title,
@@ -169,10 +174,11 @@ export function androidScope(caseId, testStartedAt, options = {}) {
                         durationMs: Date.now() - started,
                         status: "passed",
                     }, reservation);
+                    settled?.(seq);
                     return wrap(result, seq);
                 }
                 catch (error) {
-                    recordStep({
+                    const seq = recordStep({
                         kind: "android",
                         title,
                         android,
@@ -180,9 +186,46 @@ export function androidScope(caseId, testStartedAt, options = {}) {
                         status: "failed",
                         error: String(error),
                     }, reservation);
+                    settled?.(seq);
                     throw error;
                 }
             }
+            async function bounds(path, details) {
+                delete details.bounds;
+                if (!captures.has(app.name))
+                    return;
+                try {
+                    if (!await command("GET", `${path}/displayed`))
+                        return;
+                    const screen = await command("GET", "/window/rect");
+                    const rect = await command("GET", `${path}/rect`);
+                    const box = { x: rect.x / screen.width, y: rect.y / screen.height, width: rect.width / screen.width, height: rect.height / screen.height };
+                    if (Object.values(box).every(Number.isFinite) && box.width > 0 && box.height > 0)
+                        details.bounds = box;
+                }
+                catch { /* Replay decoration must not change the operation's result. */ }
+            }
+            const transient = (error) => error instanceof AppiumError && ["no such element", "stale element reference"].includes(error.code);
+            async function until(probe, label, timeoutMs = 10000) {
+                if (!Number.isFinite(timeoutMs) || timeoutMs < 0)
+                    throw new Error("Invalid wait timeout");
+                const deadline = Date.now() + timeoutMs;
+                while (true) {
+                    assertActive();
+                    try {
+                        const value = await probe();
+                        if (value !== undefined)
+                            return value;
+                    }
+                    catch (error) {
+                        if (!transient(error))
+                            throw error;
+                    }
+                    if (Date.now() >= deadline)
+                        throw new Error(`Timed out waiting for ${label}`);
+                    await new Promise(resolve => setTimeout(resolve, Math.min(100, deadline - Date.now())));
+                }
+            }
             const element = (using, value, target = androidTarget(using, value)) => {
                 const label = androidTargetLabel(target);
                 const find = async () => {
@@ -195,49 +238,102 @@ export function androidScope(caseId, testStartedAt, options = {}) {
                         throw new Error("Appium returned no element id");
                     return `/element/${encodeURIComponent(id)}`;
                 };
-                const displayed = async () => {
+                const visiblePath = async () => {
                     try {
-                        return await command("GET", `${await find()}/displayed`);
+                        const path = await find();
+                        return await command("GET", `${path}/displayed`) ? path : undefined;
                     }
                     catch (error) {
-                        if (error instanceof AppiumError &&
-                            ["no such element", "stale element reference"].includes(error.code))
-                            return false;
+                        if (transient(error))
+                            return undefined;
                         throw error;
                     }
                 };
+                const ready = (timeoutMs) => until(async () => {
+                    const path = await visiblePath();
+                    return path && await command("GET", `${path}/enabled`) ? path : undefined;
+                }, `${label} to be visible and enabled`, timeoutMs);
                 return {
-                    async tap() {
+                    async tap(options = {}) {
                         await op({ action: "tap", target }, async () => {
-                            const path = await find();
+                            const path = await ready(options.timeoutMs);
                             const marker = await tapMarker(path);
+                            // Never retry an input dispatch: a transport failure may occur
+                            // after the app has received it.
                             await command("POST", `${path}/click`, {});
                             saveTap(marker);
                         });
                     },
-                    async fill(text) {
-                        await op({ action: "fill", target }, async () => {
-                            const path = await find();
+                    async fill(text, options = {}) {
+                        await op({ action: "fill", target }, async (details) => {
+                            const path = await ready(options.timeoutMs);
                             await command("POST", `${path}/clear`, {});
                             await command("POST", `${path}/value`, { text });
+                            await bounds(path, details);
                         });
                     },
-                    text: () => op({ action: "text", target }, async () => command("GET", `${await find()}/text`)),
-                    isDisplayed: () => op({ action: "visible", target }, displayed),
+                    text: (options = {}) => op({ action: "text", target }, async (details) => {
+                        return until(async () => {
+                            const path = await find();
+                            const value = await command("GET", `${path}/text`);
+                            await bounds(path, details);
+                            return value;
+                        }, label, options.timeoutMs);
+                    }),
+                    isDisplayed: () => op({ action: "visible", target }, async (details) => {
+                        const path = await visiblePath();
+                        if (path)
+                            await bounds(path, details);
+                        return !!path;
+                    }),
                     async waitFor(options = {}) {
-                        const timeout = options.timeoutMs ?? 10000;
-                        if (!Number.isFinite(timeout) || timeout < 0)
-                            throw new Error("Invalid wait timeout");
-                        await op({ action: "wait", target, state: options.state ?? "visible" }, async () => {
-                            const end = Date.now() + timeout;
-                            do {
-                                if ((await displayed()) === (options.state !== "hidden"))
-                                    return;
-                                await new Promise((resolve) => setTimeout(resolve, 100));
-                            } while (Date.now() < end);
-                            throw new Error(`Timed out waiting for ${label}`);
+                        await op({ action: "wait", target, state: options.state ?? "visible" }, async (details) => {
+                            await until(async () => {
+                                const path = await visiblePath();
+                                if (path)
+                                    await bounds(path, details);
+                                else
+                                    delete details.bounds;
+                                return (!!path === (options.state !== "hidden")) ? true : undefined;
+                            }, `${label} to be ${options.state ?? "visible"}`, options.timeoutMs);
                         });
                     },
+                    async [ANDROID_ASSERT](matcher, negated, expected, timeoutMs) {
+                        let sourceSeq, actual, error;
+                        const visibility = matcher === "toBeVisible" || matcher === "toBeHidden";
+                        try {
+                            await op({ action: visibility ? "wait" : "text", target,
+                                ...(visibility ? { state: ((matcher === "toBeVisible") !== negated ? "visible" : "hidden") } : {}) }, async (details) => {
+                                await until(async () => {
+                                    let path;
+                                    let matches;
+                                    if (visibility) {
+                                        path = await visiblePath();
+                                        actual = !!path;
+                                        matches = matcher === "toBeVisible" ? !!path : !path;
+                                    }
+                                    else {
+                                        path = await find();
+                                        const text = await command("GET", `${path}/text`);
+                                        actual = text;
+                                        const normalize = (value) => value.replace(/\s+/g, " ").trim();
+                                        matches = expected instanceof RegExp
+                                            ? new RegExp(expected.source, expected.flags).test(text)
+                                            : matcher === "toContainText" ? normalize(text).includes(normalize(expected)) : normalize(text) === normalize(expected);
+                                    }
+                                    if (path)
+                                        await bounds(path, details);
+                                    else
+                                        delete details.bounds;
+                                    return matches !== negated ? true : undefined;
+                                }, `${label} ${negated ? "not " : ""}${matcher}${expected === undefined ? "" : ` ${expected}`}`, timeoutMs);
+                            }, seq => { sourceSeq = seq; });
+                        }
+                        catch (cause) {
+                            error = cause;
+                        }
+                        return { sourceSeq, actual, error };
+                    },
                 };
             };
             return {

package/dist/components/android-recording-state.mjs

@@ -0,0 +1,28 @@
+// scrcpy opens its output before receiving codec metadata or a video frame.
+// Only the patched recorder's first-frame signal makes an immediate stop safe.
+export const FIRST_VIDEO_FRAME = "SPECTEST_FIRST_VIDEO_FRAME";
+export const RECORDER_CAPABILITY = "spectest-first-frame-v1";
+
+export function requireRecorderCapability(version) {
+  if (!version.includes(RECORDER_CAPABILITY)) {
+    throw new Error("Android toolsImage needs scrcpy with the spectest-first-frame-v1 patch; rebuild it from ANDROID_TOOLS_DOCKERFILE");
+  }
+}
+
+export function observeRecorderOutput(record, chunk) {
+  record.log = (record.log + chunk).slice(-16000);
+  if (!record.started && record.log.includes(FIRST_VIDEO_FRAME)) {
+    record.started = true;
+    record.startedAtMs = Date.now();
+  }
+}
+
+export async function waitForRecorderFrame(record, timeoutMs = 10000) {
+  const deadline = Date.now() + timeoutMs;
+  while (true) {
+    if (record.error) throw new Error(`${record.error}: ${record.log}`);
+    if (record.started) return { startedAtMs: record.startedAtMs };
+    if (Date.now() >= deadline) throw new Error(`Recorder first video frame timed out: ${record.log}`);
+    await new Promise(resolve => setTimeout(resolve, Math.min(50, deadline - Date.now())));
+  }
+}

package/dist/components/android-runtime.mjs

@@ -1,5 +1,6 @@
 // Runs inside the Android tools container, in the same snapshotted VM.
 import http from "node:http";
+import { requireRecorderCapability, observeRecorderOutput, waitForRecorderFrame } from "./android-recording-state.mjs";
 import { spawn, execFile } from "node:child_process";
 import { promisify } from "node:util";
 import { mkdir, stat, open, rm } from "node:fs/promises";
@@ -74,6 +75,7 @@ bootstrap().catch((error) => {
 });
 
 async function startRecording(body) {
+  requireRecorderCapability((await exec("scrcpy", ["--version"], { timeout: 5000 })).stdout);
   if (!/^[a-z0-9-]{1,100}$/.test(body.id)) throw new Error("invalid recording id");
   if (recordings.has(body.id)) throw new Error("recording already exists");
   if ([...recordings.values()].some((r) => !r.stopped))
@@ -121,19 +123,13 @@ async function startRecording(body) {
       record.error = error.message;
       resolve(-1);
     });
-    child.on("exit", (code) => {
+    child.on("close", (code) => {
       if (!record.stopped) record.error = `Recorder exited early (${code})`;
       resolve(code);
     });
   });
   for (const output of [child.stdout, child.stderr])
-    output.on("data", (b) => {
-      record.log = (record.log + b).slice(-16000);
-      if (!record.started && record.log.includes("Recording started")) {
-        record.started = true;
-        record.startedAtMs = Date.now();
-      }
-    });
+    output.on("data", (b) => observeRecorderOutput(record, b));
   record.guard = setInterval(async () => {
     if ((await stat(path).catch(() => ({ size: 0 }))).size > maxBytes) {
       record.error = "Recording exceeded 256 MiB";
@@ -141,12 +137,7 @@ async function startRecording(body) {
     }
   }, 1000);
   try {
-    for (let i = 0; i < 200; i++) {
-      if (record.error) throw new Error(`${record.error}: ${record.log}`);
-      if (record.started) return { startedAtMs: record.startedAtMs };
-      await sleep(50);
-    }
-    throw new Error(`Recorder startup timed out: ${record.log}`);
+    return await waitForRecorderFrame(record);
   } catch (error) {
     clearInterval(record.guard);
     record.stopped = true;

package/dist/components/android.d.ts

@@ -6,7 +6,7 @@ export interface AndroidOptions {
     package: string;
     /** Launch activity, for example .MainActivity. */
     activity: string;
-    /** Android image; default is the tested Android 14 arm64-only redroid image. */
+    /** Android image; default is the pinned Android 16 64-bit-only redroid image. */
     image?: string;
     /** Optional prebuilt image containing the same tools as ANDROID_TOOLS_DOCKERFILE. */
     toolsImage?: string;
@@ -19,7 +19,7 @@ export interface AndroidOptions {
     recording?: false | AndroidRecordingOptions;
     dependsOn?: string[];
 }
-export declare const ANDROID_TOOLS_DOCKERFILE = "FROM node:22-bookworm-slim\nRUN apt-get update && apt-get install -y --no-install-recommends adb aapt apksigner zipalign ffmpeg default-jdk-headless ca-certificates openssl curl gcc pkg-config meson ninja-build libsdl2-dev libavcodec-dev libavdevice-dev libavformat-dev libavutil-dev libswresample-dev libusb-1.0-0-dev && rm -rf /var/lib/apt/lists/*\nRUN curl -fL https://github.com/Genymobile/scrcpy/archive/refs/tags/v3.3.1.tar.gz | tar xz -C /tmp && curl -fL https://github.com/Genymobile/scrcpy/releases/download/v3.3.1/scrcpy-server-v3.3.1 -o /tmp/scrcpy-server && meson setup /tmp/scrcpy-build /tmp/scrcpy-3.3.1 --buildtype=release -Dprebuilt_server=/tmp/scrcpy-server && ninja -C /tmp/scrcpy-build -j4 install && rm -rf /tmp/scrcpy*\nENV ANDROID_HOME=/opt/android JAVA_HOME=/usr/lib/jvm/default-java APPIUM_HOME=/opt/appium\nRUN mkdir -p /opt/android/platform-tools && for tool in adb aapt aapt2 apksigner zipalign; do ln -s /usr/bin/$tool /opt/android/platform-tools/$tool; done && npm install -g appium@3.8.0 && appium driver install uiautomator2@8.7.0\n";
+export declare const ANDROID_TOOLS_DOCKERFILE: string;
 /** Native Android, Appium and software recording, all inside the environment VM. */
 export declare function android(options: AndroidOptions): import("../index.js").ServiceGroup<{
     device: {

package/dist/components/android.js

@@ -4,9 +4,26 @@ import { serviceGroup } from "../index.js";
 import { resolveExistingProjectPath } from "../project-files.js";
 import { androidApp } from "../android.js";
 import { ENVIRONMENT_CA_PATH } from "../environment-ca.js";
+// Instrument the pinned recorder at the point its first real video packet is
+// retained. This follows the MP4 header and survives an immediate SIGINT.
+const recorderPatch = String.raw `from pathlib import Path
+p = Path('/tmp/scrcpy-3.3.1/app/src/recorder.c')
+s = p.read_text()
+a = '    int64_t pts_origin = AV_NOPTS_VALUE;'
+b = '            video_pkt_previous = video_pkt;'
+assert s.count(a) == 1 and s.count(b) == 1
+s = s.replace(a, a + '\n    bool spectest_first_frame = true;')
+s = s.replace(b, b + '\n            if (spectest_first_frame) {\n                LOGI("SPECTEST_FIRST_VIDEO_FRAME");\n                spectest_first_frame = false;\n            }')
+p.write_text(s)
+p = Path('/tmp/scrcpy-3.3.1/app/src/version.c')
+s = p.read_text()
+a = 'scrcpy_print_version(void) {'
+assert s.count(a) == 1
+p.write_text(s.replace(a, a + '\n    puts("spectest-first-frame-v1");'))`;
+const shellQuote = (value) => "'" + value.replaceAll("'", "'\\''") + "'";
 export const ANDROID_TOOLS_DOCKERFILE = `FROM node:22-bookworm-slim
-RUN apt-get update && apt-get install -y --no-install-recommends adb aapt apksigner zipalign ffmpeg default-jdk-headless ca-certificates openssl curl gcc pkg-config meson ninja-build libsdl2-dev libavcodec-dev libavdevice-dev libavformat-dev libavutil-dev libswresample-dev libusb-1.0-0-dev && rm -rf /var/lib/apt/lists/*
-RUN curl -fL https://github.com/Genymobile/scrcpy/archive/refs/tags/v3.3.1.tar.gz | tar xz -C /tmp && curl -fL https://github.com/Genymobile/scrcpy/releases/download/v3.3.1/scrcpy-server-v3.3.1 -o /tmp/scrcpy-server && meson setup /tmp/scrcpy-build /tmp/scrcpy-3.3.1 --buildtype=release -Dprebuilt_server=/tmp/scrcpy-server && ninja -C /tmp/scrcpy-build -j4 install && rm -rf /tmp/scrcpy*
+RUN apt-get update && apt-get install -y --no-install-recommends adb aapt apksigner zipalign ffmpeg default-jdk-headless ca-certificates openssl curl gcc python3 pkg-config meson ninja-build libsdl2-dev libavcodec-dev libavdevice-dev libavformat-dev libavutil-dev libswresample-dev libusb-1.0-0-dev && rm -rf /var/lib/apt/lists/*
+RUN curl -fL https://github.com/Genymobile/scrcpy/archive/refs/tags/v3.3.1.tar.gz | tar xz -C /tmp && curl -fL https://github.com/Genymobile/scrcpy/releases/download/v3.3.1/scrcpy-server-v3.3.1 -o /tmp/scrcpy-server && python3 -c ${shellQuote(recorderPatch.replaceAll("\n", ";"))} && meson setup /tmp/scrcpy-build /tmp/scrcpy-3.3.1 --buildtype=release -Dprebuilt_server=/tmp/scrcpy-server && ninja -C /tmp/scrcpy-build -j4 install && rm -rf /tmp/scrcpy*
 ENV ANDROID_HOME=/opt/android JAVA_HOME=/usr/lib/jvm/default-java APPIUM_HOME=/opt/appium
 RUN mkdir -p /opt/android/platform-tools && for tool in adb aapt aapt2 apksigner zipalign; do ln -s /usr/bin/$tool /opt/android/platform-tools/$tool; done && npm install -g appium@3.8.0 && appium driver install uiautomator2@8.7.0
 `;
@@ -30,7 +47,7 @@ export function android(options) {
                 image: {
                     type: "registry",
                     reference: options.image ??
-                        "redroid/redroid:14.0.0_64only-latest@sha256:0a611199ba2e0b5d60af39b3327a517f6407231f4352114ed3bd3cbfe2be69aa",
+                        "redroid/redroid:16.0.0_64only-latest@sha256:7b1e389bd15f37af3bcd06138f5b2ffa7cfba4332bd5ef54c53e99c2f160a15b",
                 },
                 privileged: true,
                 // Android's netd ignores resolv.conf. Use Docker's per-container DNS,
@@ -62,6 +79,10 @@ export function android(options) {
                         path: "/spectest-android.mjs",
                         content: readFileSync(new URL("./android-runtime.mjs", import.meta.url), "utf8"),
                     },
+                    {
+                        path: "/android-recording-state.mjs",
+                        content: readFileSync(new URL("./android-recording-state.mjs", import.meta.url), "utf8"),
+                    },
                     {
                         path: "/spectest-android-trust.mjs",
                         content: readFileSync(new URL("./android-trust.mjs", import.meta.url), "utf8"),

package/dist/components/index.d.ts

@@ -15,4 +15,4 @@ export { microsoft, type MicrosoftOptions } from "./microsoft.js";
 export { okta, type OktaOptions } from "./okta.js";
 export { replayFake, type ReplayFakeOptions, type ReplayFakeContext, type ReplayHandler, type ReplayKey, type WebSocketKey, type ReplayWebSocketMessage, type CassetteWebSocket, type CassetteWebSocketMessage, type WebSocketTiming, type ReplayRequest, type MatchKey, type JsonValue, type InjectRule, type InjectMatch, type StringMatch, type SignConfig, type AwsSigV4Sign, type ReplayHelpers, type ReplaySummary, type Cassette, type CassetteInteraction, type CassetteRequest, type CassetteResponse, type CassetteState, } from "./replayFake.js";
 export { electron, type ElectronOptions } from "./electron.js";
-export { android, type AndroidOptions } from "./android.js";
+export { android, ANDROID_TOOLS_DOCKERFILE, type AndroidOptions } from "./android.js";

package/dist/components/index.js

@@ -24,4 +24,4 @@ export { microsoft } from "./microsoft.js";
 export { okta } from "./okta.js";
 export { replayFake, } from "./replayFake.js";
 export { electron } from "./electron.js";
-export { android } from "./android.js";
+export { android, ANDROID_TOOLS_DOCKERFILE } from "./android.js";

package/dist/index.d.ts

@@ -4,7 +4,7 @@ import type { InjectRule, SignConfig } from "./fake-upstream.js";
 export type { InjectRule, InjectMatch, StringMatch, SignConfig, AwsSigV4Sign } from "./fake-upstream.js";
 export type { Phone, PhoneOptions, CallOptions, SpeechOptions } from "./phone.js";
 import type { Phone, PhoneOptions } from "./phone.js";
-import type { Android, AndroidApp } from "./android.js";
+import { type Android, type AndroidApp, type AndroidElement } from "./android.js";
 import { type InteractiveEntrypoint, type InteractiveEntrypoints } from "./interactive.js";
 export type { InteractiveEntrypoint, InteractiveEntrypoints } from "./interactive.js";
 export type { Android, AndroidApp, AndroidElement, AndroidRecordingOptions } from "./android.js";
@@ -1959,9 +1959,29 @@ export interface BrowserAssertion extends BrowserMatchers {
     /** Negate every matcher (retries until the negated condition holds). */
     not: BrowserMatchers;
 }
+export declare function expect(actual: AndroidElement, message?: string): AndroidAssertion;
 export declare function expect(actual: Locator, message?: string): LocatorAssertion;
 export declare function expect(actual: Browser, message?: string): BrowserAssertion;
 export declare function expect(actual: Provenanced, message?: string): Expectation;
+/** Retrying native Android assertions. Timeout is in milliseconds (default 10 s;
+ * zero performs one observation). Each assertion records one Android step. */
+export interface AndroidMatchers {
+    toBeVisible(options?: {
+        timeout?: number;
+    }): Promise<void>;
+    toBeHidden(options?: {
+        timeout?: number;
+    }): Promise<void>;
+    toHaveText(expected: string | RegExp, options?: {
+        timeout?: number;
+    }): Promise<void>;
+    toContainText(expected: string | RegExp, options?: {
+        timeout?: number;
+    }): Promise<void>;
+}
+export interface AndroidAssertion extends AndroidMatchers {
+    not: AndroidMatchers;
+}
 /**
  * Assert on a value with **no provenance** — a computed number, a frame read
  * off a raw `WebSocket` you opened yourself, anything that never flowed from a

package/dist/index.js

@@ -1,5 +1,6 @@
 import { validateServiceNetwork } from "./harness/service-network.js";
 import { stripVTControlCharacters } from "node:util";
+import { ANDROID_ASSERT } from "./android.js";
 import { resolveEntrypoints } from "./interactive.js";
 // Spectest SDK. The user's single `spectest/index.ts` calls
 // `defineEnvironment({ name, services })` once, defines test cases via
@@ -663,12 +664,35 @@ export class ExpectationError extends Error {
     }
 }
 export function expect(actual, message) {
+    if (actual && typeof actual === "object" && ANDROID_ASSERT in actual)
+        return buildAndroidAssertion(actual, message);
     if (isLocator(actual))
         return buildLocatorAssertion(actual, message);
     if (isBrowserSession(actual))
         return buildBrowserAssertion(actual, message);
     return expectValue(actual, message);
 }
+function buildAndroidAssertion(element, message) {
+    const matchers = (negated) => {
+        const run = async (matcher, expected, timeout) => {
+            const result = await element[ANDROID_ASSERT](matcher, negated, expected, timeout);
+            const error = result.error === undefined ? undefined : new ExpectationError(String(result.error));
+            if (error)
+                error.cause = result.error;
+            recordAssertion({ matcher, negated, passed: !error, message, sourceSeq: result.sourceSeq,
+                actual: safeSerialize(result.actual), expected: expected === undefined ? undefined : safeSerialize(assertionExpected(expected)), error: error?.message });
+            if (error)
+                throw error;
+        };
+        return {
+            toBeVisible: options => run("toBeVisible", undefined, options?.timeout),
+            toBeHidden: options => run("toBeHidden", undefined, options?.timeout),
+            toHaveText: (expected, options) => run("toHaveText", expected, options?.timeout),
+            toContainText: (expected, options) => run("toContainText", expected, options?.timeout),
+        };
+    };
+    return Object.assign(matchers(false), { not: matchers(true) });
+}
 function expectValue(actual, message) {
     // The first parameter is typed to the {@link Provenanced} family so a raw
     // value (`expect(res.status === 200)`, `expect(2 + 2)`) is a *compile error* —

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specific.dev/spectest",
-  "version": "0.125.0",
+  "version": "0.127.0",
   "description": "Spectest SDK for defining test environments in TypeScript.",
   "type": "module",
   "main": "./dist/index.js",

package/src/android-actions.test.ts

@@ -0,0 +1,121 @@
+import { afterEach, expect, test } from "bun:test";
+import { androidApp, androidScope } from "./android.js";
+import { expect as assert, ExpectationError } from "./index.js";
+import { startRecording, stopRecording } from "./recorder.js";
+
+const cleanups: (() => void)[] = [];
+afterEach(() => { stopRecording(); cleanups.splice(0).forEach(fn => fn()); });
+
+async function fixture() {
+  let finds = 0, clicks = 0, clears = 0, values = 0;
+  let missing = 0, invisible = 0, disabled = 0;
+  let text = "Saved", invalid = false, failClick = false;
+  const server = Bun.serve({ port: 0, hostname: "127.0.0.1", async fetch(req) {
+    const path = new URL(req.url).pathname;
+    const value = (value: unknown) => Response.json({ value });
+    const error = (error: string) => Response.json({ value: { error, message: error } }, { status: 404 });
+    if (path === "/recordings") return value({ startedAtMs: Date.now() });
+    if (path === "/session") return value({ sessionId: "test" });
+    if (path.endsWith("/element")) {
+      finds++;
+      if (invalid) return error("invalid selector");
+      if (missing-- > 0) return error("no such element");
+      return value({ "element-6066-11e4-a52e-4f735466cecf": `e${finds}` });
+    }
+    if (path.endsWith("/displayed")) return value(!(invisible-- > 0));
+    if (path.endsWith("/enabled")) return value(!(disabled-- > 0));
+    if (path.endsWith("/window/rect")) return value({ width: 100, height: 200 });
+    if (path.endsWith("/rect")) return value({ x: 10, y: 40, width: 80, height: 20 });
+    if (path.endsWith("/text")) return value(text);
+    if (path.endsWith("/clear")) { clears++; return value(null); }
+    if (path.endsWith("/value")) { values++; return value(null); }
+    if (path.endsWith("/click")) { clicks++; return failClick ? error("stale element reference") : value(null); }
+    return value(null);
+  } });
+  const endpoint = `http://127.0.0.1:${server.port}`;
+  const scope = androidScope(`test-${server.port}`, Date.now());
+  cleanups.push(() => { scope.deactivate(); server.stop(true); });
+  startRecording();
+  const phone = await scope.open(androidApp({ name: "phone", endpoint, recorderEndpoint: endpoint, serial: "device", package: "app", recording: {} }));
+  return { scope, phone, stats: () => ({ finds, clicks, clears, values }),
+    configure(options: { missing?: number; invisible?: number; disabled?: number; text?: string; invalid?: boolean; failClick?: boolean }) {
+      missing = options.missing ?? 0; invisible = options.invisible ?? 0; disabled = options.disabled ?? 0;
+      text = options.text ?? text; invalid = options.invalid ?? false; failClick = options.failClick ?? false;
+    } };
+}
+
+test("tap and fill wait for visible enabled elements, recording one step each", async () => {
+  const f = await fixture();
+  f.configure({ missing: 1, invisible: 1, disabled: 1 });
+  await f.phone.getByText("Save").tap({ timeoutMs: 1000 });
+  f.configure({ missing: 1 });
+  await f.phone.getById("draft").fill("private text", { timeoutMs: 1000 });
+  expect(f.stats()).toMatchObject({ clicks: 1, clears: 1, values: 1 });
+  const events = stopRecording();
+  expect(events).toHaveLength(2);
+  expect(events[1]).toMatchObject({ android: { action: "fill", bounds: { x: 0.1, y: 0.2, width: 0.8, height: 0.1 } } });
+  expect(JSON.stringify(events)).not.toContain("private text");
+});
+
+test("native assertions retry without emitting polling attempts and preserve provenance", async () => {
+  const f = await fixture();
+  f.configure({ missing: 2 });
+  await assert(f.phone.getByText("Saved"), "save completes").toBeVisible({ timeout: 1000 });
+  f.configure({ text: "Loading" });
+  const change = setTimeout(() => f.configure({ text: "  Saved\n successfully " }), 150);
+  await assert(f.phone.getById("status")).toHaveText("Saved successfully", { timeout: 1000 });
+  clearTimeout(change);
+  await assert(f.phone.getById("status")).toContainText(/Saved/g);
+  await assert(f.phone.getById("status")).not.toHaveText("Loading");
+  f.configure({ missing: 10 });
+  await assert(f.phone.getById("gone")).toBeHidden({ timeout: 0 });
+  await assert(f.phone.getById("gone")).not.toBeVisible({ timeout: 0 });
+  const events = stopRecording();
+  const steps = events.filter(e => e.kind === "android");
+  const assertions = events.filter(e => e.kind === "assertion");
+  expect(steps).toHaveLength(6);
+  expect(assertions).toHaveLength(6);
+  for (let i = 0; i < steps.length; i++) expect(assertions[i]).toMatchObject({ sourceSeq: steps[i].seq, passed: true });
+  expect(steps[0]).toMatchObject({ android: { bounds: { x: 0.1, y: 0.2, width: 0.8, height: 0.1 } } });
+});
+
+test("timeouts and invalid selectors fail once, and dispatched clicks are never retried", async () => {
+  const f = await fixture();
+  f.configure({ missing: 100 });
+  await expect(assert(f.phone.getById("missing")).toBeVisible({ timeout: 0 })).rejects.toBeInstanceOf(ExpectationError);
+  expect(f.stats().finds).toBe(1);
+  f.configure({ invalid: true });
+  await expect(f.phone.getById("bad").tap()).rejects.toThrow("invalid selector");
+  expect(f.stats().finds).toBe(2);
+  f.configure({ failClick: true });
+  await expect(f.phone.getById("save").tap()).rejects.toThrow("stale element reference");
+  expect(f.stats().clicks).toBe(1);
+  const events = stopRecording();
+  expect(events.filter(e => e.kind === "android")).toHaveLength(3);
+  expect(events.find(e => e.kind === "assertion")).toMatchObject({ passed: false, sourceSeq: events[0].seq });
+});
+
+test("immediate visibility checks stay immediate; read waits and canceled waits stop", async () => {
+  const f = await fixture();
+  f.configure({ missing: 100 });
+  expect((await f.phone.getById("missing").isDisplayed()).unwrap()).toBe(false);
+  expect(f.stats().finds).toBe(1);
+  f.configure({ missing: 1 });
+  expect((await f.phone.getById("status").text({ timeoutMs: 500 })).unwrap()).toBe("Saved");
+  f.configure({ missing: 100 });
+  const pending = f.phone.getById("missing").waitFor();
+  setTimeout(() => f.scope.deactivate(), 30);
+  await expect(pending).rejects.toThrow("finished test");
+});
+
+test("a completed disappearance wait clears the earlier visible target, like browser replay", async () => {
+  const f = await fixture();
+  const hide = setTimeout(() => f.configure({ missing: 100 }), 50);
+  await assert(f.phone.getById("spinner")).toBeHidden({ timeout: 1000 });
+  clearTimeout(hide);
+  const events = stopRecording();
+  const step = events.find(e => e.kind === "android")!;
+  expect(step).toMatchObject({ android: { state: "hidden" }, status: "passed" });
+  expect(step.android?.bounds).toBeUndefined();
+  expect(f.stats().finds).toBeGreaterThan(1);
+});

package/src/android-step.ts

@@ -18,6 +18,8 @@ export interface AndroidStepDetails {
     | "source"
     | "screenshot"
     | "execute";
+  /** Normalized screen bounds observed by this operation. */
+  bounds?: { x: number; y: number; width: number; height: number };
   target?: AndroidTarget;
   point?: { x: number; y: number };
   direction?: "up" | "down" | "left" | "right";

package/src/android.test.ts

@@ -57,6 +57,7 @@ describe("Android case lifecycle", () => {
           return Response.json({ value: { error: "stale element reference", message: "Gone" } }, { status: 404 });
         if (path.endsWith("/element"))
           return json({ value: { "element-6066-11e4-a52e-4f735466cecf": "element-1" } });
+        if (path.endsWith("/displayed") || path.endsWith("/enabled")) return json({ value: true });
         if (path.endsWith("/text")) return json({ value: "inherited draft" });
         if (path.endsWith("/window/rect")) return json({ value: { width: 1080, height: 2400 } });
         if (path.endsWith("/rect")) return json({ value: { x: 100, y: 400, width: 880, height: 160 } });
@@ -135,6 +136,8 @@ describe("Android case lifecycle", () => {
       const starts = requests.filter((r) => r.path === "/session");
       expect(starts).toHaveLength(1);
       expect(starts[0].body.capabilities.alwaysMatch).toMatchObject({
+        timeouts: { implicit: 0 },
+        "appium:settings[waitForSelectorTimeout]": 0,
         "appium:noReset": true,
         "appium:autoLaunch": false,
         "appium:newCommandTimeout": 0,

package/src/android.ts

@@ -70,6 +70,10 @@ async function session(app: AndroidApp): Promise<string> {
       capabilities: {
         alwaysMatch: {
           platformName: "Android",
+          // Conditions are explicit waits. Do not stack a session-wide lookup
+          // wait or UiSelector's own 10s wait underneath their deadline.
+          timeouts: { implicit: 0 },
+          "appium:settings[waitForSelectorTimeout]": 0,
           "appium:automationName": "UiAutomator2",
           "appium:udid": app.serial,
           "appium:appPackage": app.package,
@@ -93,10 +97,14 @@ async function session(app: AndroidApp): Promise<string> {
   return pending;
 }
 
+export const ANDROID_ASSERT: unique symbol = Symbol.for("spectest.androidAssert");
+export type AndroidMatcher = "toBeVisible" | "toBeHidden" | "toHaveText" | "toContainText";
+export interface AndroidAssertionResult { sourceSeq?: number; actual?: unknown; error?: unknown }
 export interface AndroidElement {
-  tap(): Promise<void>;
-  fill(text: string): Promise<void>;
-  text(): Promise<Wrapped<string>>;
+  [ANDROID_ASSERT](matcher: AndroidMatcher, negated: boolean, expected: string | RegExp | undefined, timeoutMs?: number): Promise<AndroidAssertionResult>;
+  tap(options?: { timeoutMs?: number }): Promise<void>;
+  fill(text: string, options?: { timeoutMs?: number }): Promise<void>;
+  text(options?: { timeoutMs?: number }): Promise<Wrapped<string>>;
   isDisplayed(): Promise<Wrapped<boolean>>;
   waitFor(options?: { state?: "visible" | "hidden"; timeoutMs?: number }): Promise<void>;
 }
@@ -227,14 +235,14 @@ export function androidScope(
         if (list.length < 10000) list.push(marker);
         taps.set(app.name, list);
       }
-      async function op<T>(operation: Omit<AndroidStepDetails, "device">, fn: () => Promise<T>): Promise<Wrapped<T>> {
+      async function op<T>(operation: Omit<AndroidStepDetails, "device">, fn: (details: AndroidStepDetails) => Promise<T>, settled?: (seq: number | undefined) => void): Promise<Wrapped<T>> {
         assertActive();
         const android = { device: app.name, ...operation };
         const title = androidStepTitle(android);
         const reservation = reserveEvent(),
           started = Date.now();
         try {
-          const result = await fn();
+          const result = await fn(android);
           const seq = recordStep(
             {
               kind: "android",
@@ -245,9 +253,10 @@ export function androidScope(
             },
             reservation,
           );
+          settled?.(seq);
           return wrap(result, seq) as Wrapped<T>;
         } catch (error) {
-          recordStep(
+          const seq = recordStep(
             {
               kind: "android",
               title,
@@ -258,9 +267,35 @@ export function androidScope(
             },
             reservation,
           );
+          settled?.(seq);
           throw error;
         }
       }
+      async function bounds(path: string, details: AndroidStepDetails) {
+        delete details.bounds;
+        if (!captures.has(app.name)) return;
+        try {
+          if (!await command<boolean>("GET", `${path}/displayed`)) return;
+          const screen = await command<{ width: number; height: number }>("GET", "/window/rect");
+          const rect = await command<{ x: number; y: number; width: number; height: number }>("GET", `${path}/rect`);
+          const box = { x: rect.x / screen.width, y: rect.y / screen.height, width: rect.width / screen.width, height: rect.height / screen.height };
+          if (Object.values(box).every(Number.isFinite) && box.width > 0 && box.height > 0) details.bounds = box;
+        } catch { /* Replay decoration must not change the operation's result. */ }
+      }
+      const transient = (error: unknown) => error instanceof AppiumError && ["no such element", "stale element reference"].includes(error.code);
+      async function until<T>(probe: () => Promise<T | undefined>, label: string, timeoutMs = 10000): Promise<T> {
+        if (!Number.isFinite(timeoutMs) || timeoutMs < 0) throw new Error("Invalid wait timeout");
+        const deadline = Date.now() + timeoutMs;
+        while (true) {
+          assertActive();
+          try {
+            const value = await probe();
+            if (value !== undefined) return value;
+          } catch (error) { if (!transient(error)) throw error; }
+          if (Date.now() >= deadline) throw new Error(`Timed out waiting for ${label}`);
+          await new Promise(resolve => setTimeout(resolve, Math.min(100, deadline - Date.now())));
+        }
+      }
       const element = (using: string, value: string, target: AndroidTarget = androidTarget(using, value)): AndroidElement => {
         const label = androidTargetLabel(target);
         const find = async () => {
@@ -272,49 +307,88 @@ export function androidScope(
           if (!id) throw new Error("Appium returned no element id");
           return `/element/${encodeURIComponent(id)}`;
         };
-        const displayed = async () => {
+        const visiblePath = async () => {
           try {
-            return await command<boolean>("GET", `${await find()}/displayed`);
-          } catch (error) {
-            if (
-              error instanceof AppiumError &&
-              ["no such element", "stale element reference"].includes(error.code)
-            )
-              return false;
-            throw error;
-          }
+            const path = await find();
+            return await command<boolean>("GET", `${path}/displayed`) ? path : undefined;
+          } catch (error) { if (transient(error)) return undefined; throw error; }
         };
+        const ready = (timeoutMs?: number) => until(async () => {
+          const path = await visiblePath();
+          return path && await command<boolean>("GET", `${path}/enabled`) ? path : undefined;
+        }, `${label} to be visible and enabled`, timeoutMs);
         return {
-          async tap() {
+          async tap(options = {}) {
             await op({ action: "tap", target }, async () => {
-              const path = await find();
+              const path = await ready(options.timeoutMs);
               const marker = await tapMarker(path);
+              // Never retry an input dispatch: a transport failure may occur
+              // after the app has received it.
               await command("POST", `${path}/click`, {});
               saveTap(marker);
             });
           },
-          async fill(text) {
-            await op({ action: "fill", target }, async () => {
-              const path = await find();
+          async fill(text, options = {}) {
+            await op({ action: "fill", target }, async (details) => {
+              const path = await ready(options.timeoutMs);
               await command("POST", `${path}/clear`, {});
               await command("POST", `${path}/value`, { text });
+              await bounds(path, details);
             });
           },
-          text: () =>
-            op({ action: "text", target }, async () => command<string>("GET", `${await find()}/text`)),
-          isDisplayed: () => op({ action: "visible", target }, displayed),
+          text: (options = {}) => op({ action: "text", target }, async (details) => {
+            return until(async () => {
+              const path = await find();
+              const value = await command<string>("GET", `${path}/text`);
+              await bounds(path, details);
+              return value;
+            }, label, options.timeoutMs);
+          }),
+          isDisplayed: () => op({ action: "visible", target }, async (details) => {
+            const path = await visiblePath();
+            if (path) await bounds(path, details);
+            return !!path;
+          }),
           async waitFor(options = {}) {
-            const timeout = options.timeoutMs ?? 10000;
-            if (!Number.isFinite(timeout) || timeout < 0) throw new Error("Invalid wait timeout");
-            await op({ action: "wait", target, state: options.state ?? "visible" }, async () => {
-              const end = Date.now() + timeout;
-              do {
-                if ((await displayed()) === (options.state !== "hidden")) return;
-                await new Promise((resolve) => setTimeout(resolve, 100));
-              } while (Date.now() < end);
-              throw new Error(`Timed out waiting for ${label}`);
+            await op({ action: "wait", target, state: options.state ?? "visible" }, async (details) => {
+              await until(async () => {
+                const path = await visiblePath();
+                if (path) await bounds(path, details);
+                else delete details.bounds;
+                return (!!path === (options.state !== "hidden")) ? true : undefined;
+              }, `${label} to be ${options.state ?? "visible"}`, options.timeoutMs);
             });
           },
+          async [ANDROID_ASSERT](matcher, negated, expected, timeoutMs) {
+            let sourceSeq: number | undefined, actual: unknown, error: unknown;
+            const visibility = matcher === "toBeVisible" || matcher === "toBeHidden";
+            try {
+              await op({ action: visibility ? "wait" : "text", target,
+                ...(visibility ? { state: ((matcher === "toBeVisible") !== negated ? "visible" : "hidden") as "visible" | "hidden" } : {}) }, async (details) => {
+                await until(async () => {
+                  let path: string | undefined;
+                  let matches: boolean;
+                  if (visibility) {
+                    path = await visiblePath();
+                    actual = !!path;
+                    matches = matcher === "toBeVisible" ? !!path : !path;
+                  } else {
+                    path = await find();
+                    const text = await command<string>("GET", `${path}/text`);
+                    actual = text;
+                    const normalize = (value: string) => value.replace(/\s+/g, " ").trim();
+                    matches = expected instanceof RegExp
+                      ? new RegExp(expected.source, expected.flags).test(text)
+                      : matcher === "toContainText" ? normalize(text).includes(normalize(expected!)) : normalize(text) === normalize(expected!);
+                  }
+                  if (path) await bounds(path, details);
+                  else delete details.bounds;
+                  return matches !== negated ? true : undefined;
+                }, `${label} ${negated ? "not " : ""}${matcher}${expected === undefined ? "" : ` ${expected}`}`, timeoutMs);
+              }, seq => { sourceSeq = seq; });
+            } catch (cause) { error = cause; }
+            return { sourceSeq, actual, error };
+          },
         };
       };
       return {

package/src/components/android-recording-state.mjs

@@ -0,0 +1,28 @@
+// scrcpy opens its output before receiving codec metadata or a video frame.
+// Only the patched recorder's first-frame signal makes an immediate stop safe.
+export const FIRST_VIDEO_FRAME = "SPECTEST_FIRST_VIDEO_FRAME";
+export const RECORDER_CAPABILITY = "spectest-first-frame-v1";
+
+export function requireRecorderCapability(version) {
+  if (!version.includes(RECORDER_CAPABILITY)) {
+    throw new Error("Android toolsImage needs scrcpy with the spectest-first-frame-v1 patch; rebuild it from ANDROID_TOOLS_DOCKERFILE");
+  }
+}
+
+export function observeRecorderOutput(record, chunk) {
+  record.log = (record.log + chunk).slice(-16000);
+  if (!record.started && record.log.includes(FIRST_VIDEO_FRAME)) {
+    record.started = true;
+    record.startedAtMs = Date.now();
+  }
+}
+
+export async function waitForRecorderFrame(record, timeoutMs = 10000) {
+  const deadline = Date.now() + timeoutMs;
+  while (true) {
+    if (record.error) throw new Error(`${record.error}: ${record.log}`);
+    if (record.started) return { startedAtMs: record.startedAtMs };
+    if (Date.now() >= deadline) throw new Error(`Recorder first video frame timed out: ${record.log}`);
+    await new Promise(resolve => setTimeout(resolve, Math.min(50, deadline - Date.now())));
+  }
+}

package/src/components/android-runtime.mjs

@@ -1,5 +1,6 @@
 // Runs inside the Android tools container, in the same snapshotted VM.
 import http from "node:http";
+import { requireRecorderCapability, observeRecorderOutput, waitForRecorderFrame } from "./android-recording-state.mjs";
 import { spawn, execFile } from "node:child_process";
 import { promisify } from "node:util";
 import { mkdir, stat, open, rm } from "node:fs/promises";
@@ -74,6 +75,7 @@ bootstrap().catch((error) => {
 });
 
 async function startRecording(body) {
+  requireRecorderCapability((await exec("scrcpy", ["--version"], { timeout: 5000 })).stdout);
   if (!/^[a-z0-9-]{1,100}$/.test(body.id)) throw new Error("invalid recording id");
   if (recordings.has(body.id)) throw new Error("recording already exists");
   if ([...recordings.values()].some((r) => !r.stopped))
@@ -121,19 +123,13 @@ async function startRecording(body) {
       record.error = error.message;
       resolve(-1);
     });
-    child.on("exit", (code) => {
+    child.on("close", (code) => {
       if (!record.stopped) record.error = `Recorder exited early (${code})`;
       resolve(code);
     });
   });
   for (const output of [child.stdout, child.stderr])
-    output.on("data", (b) => {
-      record.log = (record.log + b).slice(-16000);
-      if (!record.started && record.log.includes("Recording started")) {
-        record.started = true;
-        record.startedAtMs = Date.now();
-      }
-    });
+    output.on("data", (b) => observeRecorderOutput(record, b));
   record.guard = setInterval(async () => {
     if ((await stat(path).catch(() => ({ size: 0 }))).size > maxBytes) {
       record.error = "Recording exceeded 256 MiB";
@@ -141,12 +137,7 @@ async function startRecording(body) {
     }
   }, 1000);
   try {
-    for (let i = 0; i < 200; i++) {
-      if (record.error) throw new Error(`${record.error}: ${record.log}`);
-      if (record.started) return { startedAtMs: record.startedAtMs };
-      await sleep(50);
-    }
-    throw new Error(`Recorder startup timed out: ${record.log}`);
+    return await waitForRecorderFrame(record);
   } catch (error) {
     clearInterval(record.guard);
     record.stopped = true;

package/src/components/android.test.ts

@@ -32,6 +32,7 @@ test("Android expands into two VM services with an APK input and private Appium/
     const env = JSON.parse(output);
     const device = env.services["phone-device"],
       tools = env.services.phone;
+    expect(device.image.reference).toBe("redroid/redroid:16.0.0_64only-latest@sha256:7b1e389bd15f37af3bcd06138f5b2ffa7cfba4332bd5ef54c53e99c2f160a15b");
     expect(device.privileged).toBe(true);
     expect(device.args).toContain("androidboot.redroid_width=1080");
     expect(device.args).toContain("androidboot.redroid_height=2400");
@@ -68,3 +69,62 @@ test("bad dimensions and identifiers fail before image builds", () => {
     android({ apk: "spectest/tests/app.apk", package: "com.example", activity: ".MainActivity" }),
   ).toThrow("invalidate snapshots");
 });
+
+test("recorder waits for a retained first frame before an immediate stop, including split output", async () => {
+  const { spawn } = await import("node:child_process");
+  const { observeRecorderOutput, waitForRecorderFrame } = await import("./android-recording-state.mjs");
+  // Opening the output is deliberately separate from receiving the frame.
+  // This models scrcpy's static-screen path: only SIGINT flushes the last frame.
+  const child = spawn("node", ["-e", `
+    let retained = false;
+    process.on('SIGINT', () => {
+      process.stdout.write(retained ? 'VALID_VIDEO_WITH_TRAILER' : 'INVALID_EMPTY_VIDEO');
+      process.exit(retained ? 0 : 1);
+    });
+    process.stdin.once('data', () => {
+      retained = true;
+      process.stdout.write('SPECTEST_FIRST_VIDEO_');
+      setImmediate(() => process.stdout.write('FRAME\\n'));
+    });
+    process.stdout.write('Recording started to mp4 file: fixture.mp4\\n');
+  `]);
+  const record = { log: "", error: null as string | null, started: false, startedAtMs: 0 };
+  let opened!: () => void;
+  const outputOpened = new Promise<void>(resolve => { opened = resolve; });
+  child.stdout.on("data", chunk => {
+    observeRecorderOutput(record, chunk);
+    if (record.log.includes("Recording started")) opened();
+  });
+  const closed = new Promise<number | null>(resolve => child.on("close", resolve));
+  try {
+    await outputOpened;
+    let ready = false;
+    const waiting = waitForRecorderFrame(record).then(value => { ready = true; return value; });
+    await new Promise(resolve => setImmediate(resolve));
+    expect(ready).toBe(false);
+    expect(record.started).toBe(false);
+    const frameRequested = Date.now();
+    child.stdin.write("deliver first frame");
+    const result = await waiting;
+    expect(result.startedAtMs).toBeGreaterThanOrEqual(frameRequested);
+    child.kill("SIGINT");
+    expect(await closed).toBe(0);
+    expect(record.log).toContain("VALID_VIDEO_WITH_TRAILER");
+    expect(record.log).not.toContain("INVALID_EMPTY_VIDEO");
+  } finally {
+    child.kill("SIGKILL");
+    await closed;
+  }
+});
+
+test("recorder rejects missing frames, early exit and unpatched custom tools explicitly", async () => {
+  const { requireRecorderCapability, observeRecorderOutput, waitForRecorderFrame } = await import("./android-recording-state.mjs");
+  expect(() => requireRecorderCapability("scrcpy 3.3.1\n")).toThrow("rebuild it from ANDROID_TOOLS_DOCKERFILE");
+  expect(() => requireRecorderCapability("scrcpy 3.3.1\nspectest-first-frame-v1\n")).not.toThrow();
+  const record = { log: "", error: null as string | null, started: false, startedAtMs: 0 };
+  observeRecorderOutput(record, "Recording started to mp4 file: empty.mp4\n");
+  await expect(waitForRecorderFrame(record, 20)).rejects.toThrow("first video frame timed out");
+  record.error = "Recorder exited early (1)";
+  observeRecorderOutput(record, "SPECTEST_FIRST_VIDEO_FRAME\n");
+  await expect(waitForRecorderFrame(record)).rejects.toThrow("Recorder exited early");
+});

package/src/components/android.ts

@@ -12,7 +12,7 @@ export interface AndroidOptions {
   package: string;
   /** Launch activity, for example .MainActivity. */
   activity: string;
-  /** Android image; default is the tested Android 14 arm64-only redroid image. */
+  /** Android image; default is the pinned Android 16 64-bit-only redroid image. */
   image?: string;
   /** Optional prebuilt image containing the same tools as ANDROID_TOOLS_DOCKERFILE. */
   toolsImage?: string;
@@ -26,9 +26,27 @@ export interface AndroidOptions {
   dependsOn?: string[];
 }
 
+// Instrument the pinned recorder at the point its first real video packet is
+// retained. This follows the MP4 header and survives an immediate SIGINT.
+const recorderPatch = String.raw`from pathlib import Path
+p = Path('/tmp/scrcpy-3.3.1/app/src/recorder.c')
+s = p.read_text()
+a = '    int64_t pts_origin = AV_NOPTS_VALUE;'
+b = '            video_pkt_previous = video_pkt;'
+assert s.count(a) == 1 and s.count(b) == 1
+s = s.replace(a, a + '\n    bool spectest_first_frame = true;')
+s = s.replace(b, b + '\n            if (spectest_first_frame) {\n                LOGI("SPECTEST_FIRST_VIDEO_FRAME");\n                spectest_first_frame = false;\n            }')
+p.write_text(s)
+p = Path('/tmp/scrcpy-3.3.1/app/src/version.c')
+s = p.read_text()
+a = 'scrcpy_print_version(void) {'
+assert s.count(a) == 1
+p.write_text(s.replace(a, a + '\n    puts("spectest-first-frame-v1");'))`;
+const shellQuote = (value: string) => "'" + value.replaceAll("'", "'\\''") + "'";
+
 export const ANDROID_TOOLS_DOCKERFILE = `FROM node:22-bookworm-slim
-RUN apt-get update && apt-get install -y --no-install-recommends adb aapt apksigner zipalign ffmpeg default-jdk-headless ca-certificates openssl curl gcc pkg-config meson ninja-build libsdl2-dev libavcodec-dev libavdevice-dev libavformat-dev libavutil-dev libswresample-dev libusb-1.0-0-dev && rm -rf /var/lib/apt/lists/*
-RUN curl -fL https://github.com/Genymobile/scrcpy/archive/refs/tags/v3.3.1.tar.gz | tar xz -C /tmp && curl -fL https://github.com/Genymobile/scrcpy/releases/download/v3.3.1/scrcpy-server-v3.3.1 -o /tmp/scrcpy-server && meson setup /tmp/scrcpy-build /tmp/scrcpy-3.3.1 --buildtype=release -Dprebuilt_server=/tmp/scrcpy-server && ninja -C /tmp/scrcpy-build -j4 install && rm -rf /tmp/scrcpy*
+RUN apt-get update && apt-get install -y --no-install-recommends adb aapt apksigner zipalign ffmpeg default-jdk-headless ca-certificates openssl curl gcc python3 pkg-config meson ninja-build libsdl2-dev libavcodec-dev libavdevice-dev libavformat-dev libavutil-dev libswresample-dev libusb-1.0-0-dev && rm -rf /var/lib/apt/lists/*
+RUN curl -fL https://github.com/Genymobile/scrcpy/archive/refs/tags/v3.3.1.tar.gz | tar xz -C /tmp && curl -fL https://github.com/Genymobile/scrcpy/releases/download/v3.3.1/scrcpy-server-v3.3.1 -o /tmp/scrcpy-server && python3 -c ${shellQuote(recorderPatch.replaceAll("\n", ";"))} && meson setup /tmp/scrcpy-build /tmp/scrcpy-3.3.1 --buildtype=release -Dprebuilt_server=/tmp/scrcpy-server && ninja -C /tmp/scrcpy-build -j4 install && rm -rf /tmp/scrcpy*
 ENV ANDROID_HOME=/opt/android JAVA_HOME=/usr/lib/jvm/default-java APPIUM_HOME=/opt/appium
 RUN mkdir -p /opt/android/platform-tools && for tool in adb aapt aapt2 apksigner zipalign; do ln -s /usr/bin/$tool /opt/android/platform-tools/$tool; done && npm install -g appium@3.8.0 && appium driver install uiautomator2@8.7.0
 `;
@@ -60,7 +78,7 @@ export function android(options: AndroidOptions) {
           type: "registry" as const,
           reference:
             options.image ??
-            "redroid/redroid:14.0.0_64only-latest@sha256:0a611199ba2e0b5d60af39b3327a517f6407231f4352114ed3bd3cbfe2be69aa",
+            "redroid/redroid:16.0.0_64only-latest@sha256:7b1e389bd15f37af3bcd06138f5b2ffa7cfba4332bd5ef54c53e99c2f160a15b",
         },
         privileged: true,
         // Android's netd ignores resolv.conf. Use Docker's per-container DNS,
@@ -92,6 +110,10 @@ export function android(options: AndroidOptions) {
             path: "/spectest-android.mjs",
             content: readFileSync(new URL("./android-runtime.mjs", import.meta.url), "utf8"),
           },
+          {
+            path: "/android-recording-state.mjs",
+            content: readFileSync(new URL("./android-recording-state.mjs", import.meta.url), "utf8"),
+          },
           {
             path: "/spectest-android-trust.mjs",
             content: readFileSync(new URL("./android-trust.mjs", import.meta.url), "utf8"),

package/src/components/index.ts

@@ -111,4 +111,4 @@ export {
 } from "./replayFake.js";
 export { electron, type ElectronOptions } from "./electron.js";
 
-export { android, type AndroidOptions } from "./android.js";
+export { android, ANDROID_TOOLS_DOCKERFILE, type AndroidOptions } from "./android.js";

package/src/index.ts

@@ -6,7 +6,7 @@ import type { InjectRule, SignConfig } from "./fake-upstream.js";
 export type { InjectRule, InjectMatch, StringMatch, SignConfig, AwsSigV4Sign } from "./fake-upstream.js";
 export type { Phone, PhoneOptions, CallOptions, SpeechOptions } from "./phone.js";
 import type { Phone, PhoneOptions } from "./phone.js";
-import type { Android, AndroidApp } from "./android.js";
+import { ANDROID_ASSERT, type Android, type AndroidApp, type AndroidElement, type AndroidMatcher } from "./android.js";
 import { resolveEntrypoints, type InteractiveEntrypoint, type InteractiveEntrypoints } from "./interactive.js";
 export type { InteractiveEntrypoint, InteractiveEntrypoints } from "./interactive.js";
 export type { Android, AndroidApp, AndroidElement, AndroidRecordingOptions } from "./android.js";
@@ -3030,18 +3030,49 @@ export interface BrowserAssertion extends BrowserMatchers {
 // `expect(value)` the synchronous value matchers. The two object overloads are
 // listed first so they win over `Provenanced` (neither has `unwrap`); a
 // Locator and a Browser are structurally disjoint, so their order is free.
+export function expect(actual: AndroidElement, message?: string): AndroidAssertion;
 export function expect(actual: Locator, message?: string): LocatorAssertion;
 export function expect(actual: Browser, message?: string): BrowserAssertion;
 export function expect(actual: Provenanced, message?: string): Expectation;
 export function expect(
-  actual: Provenanced | Locator | Browser,
+  actual: Provenanced | Locator | Browser | AndroidElement,
   message?: string,
-): Expectation | LocatorAssertion | BrowserAssertion {
+): Expectation | LocatorAssertion | BrowserAssertion | AndroidAssertion {
+  if (actual && typeof actual === "object" && ANDROID_ASSERT in actual) return buildAndroidAssertion(actual as AndroidElement, message);
   if (isLocator(actual)) return buildLocatorAssertion(actual, message);
   if (isBrowserSession(actual)) return buildBrowserAssertion(actual, message);
   return expectValue(actual as Provenanced, message);
 }
 
+/** Retrying native Android assertions. Timeout is in milliseconds (default 10 s;
+ * zero performs one observation). Each assertion records one Android step. */
+export interface AndroidMatchers {
+  toBeVisible(options?: { timeout?: number }): Promise<void>;
+  toBeHidden(options?: { timeout?: number }): Promise<void>;
+  toHaveText(expected: string | RegExp, options?: { timeout?: number }): Promise<void>;
+  toContainText(expected: string | RegExp, options?: { timeout?: number }): Promise<void>;
+}
+export interface AndroidAssertion extends AndroidMatchers { not: AndroidMatchers }
+function buildAndroidAssertion(element: AndroidElement, message?: string): AndroidAssertion {
+  const matchers = (negated: boolean): AndroidMatchers => {
+    const run = async (matcher: AndroidMatcher, expected?: string | RegExp, timeout?: number) => {
+      const result = await element[ANDROID_ASSERT](matcher, negated, expected, timeout);
+      const error = result.error === undefined ? undefined : new ExpectationError(String(result.error));
+      if (error) error.cause = result.error;
+      recordAssertion({ matcher, negated, passed: !error, message, sourceSeq: result.sourceSeq,
+        actual: safeSerialize(result.actual), expected: expected === undefined ? undefined : safeSerialize(assertionExpected(expected)), error: error?.message });
+      if (error) throw error;
+    };
+    return {
+      toBeVisible: options => run("toBeVisible", undefined, options?.timeout),
+      toBeHidden: options => run("toBeHidden", undefined, options?.timeout),
+      toHaveText: (expected, options) => run("toHaveText", expected, options?.timeout),
+      toContainText: (expected, options) => run("toContainText", expected, options?.timeout),
+    };
+  };
+  return Object.assign(matchers(false), { not: matchers(true) });
+}
+
 function expectValue(actual: Provenanced, message?: string): Expectation {
   // The first parameter is typed to the {@link Provenanced} family so a raw
   // value (`expect(res.status === 200)`, `expect(2 + 2)`) is a *compile error* —