@specific.dev/spectest 0.126.0 → 0.128.0

package/dist/harness/coverage-target.js

@@ -0,0 +1,54 @@
+// Runtime adapters operate on this same context in Docker and nested runtimes.
+// Counter baselines belong to an instance; source identity belongs to its image.
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { attachCoverageSourceOptions, coverageAdapters, coverageReportsMode, resolveCoverageSourceOptions } from "../coverage.js";
+import { applyCoverageDelta, readCoverageDir } from "./coverage.js";
+export async function captureCoverageTarget(options) {
+    const { context: ctx, coverage, root, baseline } = options;
+    const adapters = coverageAdapters(coverage);
+    const written = new Set();
+    const delta = new Set();
+    const context = { ...ctx, async writeReport(name, content) {
+            const resolved = path.resolve(ctx.reportDir, name);
+            if (!resolved.startsWith(path.resolve(ctx.reportDir) + path.sep))
+                throw new Error("coverage report escapes directory");
+            await fs.mkdir(path.dirname(resolved), { recursive: true });
+            await fs.writeFile(resolved + ".tmp", content);
+            await fs.rename(resolved + ".tmp", resolved);
+            written.add(name);
+        } };
+    try {
+        ctx.signal.throwIfAborted();
+        const policies = await resolveCoverageSourceOptions(adapters, ctx, typeof coverage === "object" ? {
+            sourceRoot: coverage.sourceRoot, excludeSources: coverage.excludeSources,
+        } : undefined);
+        for (const adapter of adapters) {
+            if (adapter.collect || adapter.load)
+                throw new Error(`adapter ${adapter.name} cannot run inside a container; attach browser coverage to the cluster service`);
+            written.clear();
+            await adapter.capture?.(context);
+            if (adapter.reports === "delta")
+                for (const name of written)
+                    delta.add(name);
+        }
+        if (baseline && options.inventoryAvailable !== false) {
+            const units = new Set();
+            for (const adapter of adapters)
+                for (const unit of await adapter.inventory?.(context) ?? [])
+                    units.add(unit);
+            await context.writeReport("inventory.units", [...units].sort().join("\n"));
+        }
+        ctx.signal.throwIfAborted();
+        const capture = await readCoverageDir(ctx.service, ctx.reportDir);
+        if (baseline)
+            await fs.rm(path.join(ctx.reportDir, "inventory.units"), { force: true });
+        capture.root = root;
+        attachCoverageSourceOptions(capture, policies);
+        const result = applyCoverageDelta({ ...capture, service: options.counterKey ?? capture.service }, coverageReportsMode(coverage), delta);
+        return { ...result, service: capture.service };
+    }
+    catch (error) {
+        return { service: ctx.service, reports: [], error: String(error) };
+    }
+}

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
@@ -40,7 +41,7 @@ export { McpHttpError, McpRpcError, McpAuthDeniedError, } from "./mcp.js";
 import { isLocator, getLocatorProbe, isBrowserSession, getBrowserProbe, } from "./locator.js";
 import { escapeInvisible, textDifferenceNote, } from "./text-match.js";
 import { describeUrlPattern } from "./url-match.js";
-import { applyCoverageAdapters, validateCoverage } from "./coverage.js";
+import { applyCoverageAdapters, coverageAdapters, validateCoverage } from "./coverage.js";
 import { resolveExistingProjectPath } from "./project-files.js";
 export { ca } from "./environment-ca.js";
 // Low-level ingress primitives + the framework lowering that the friendly
@@ -184,6 +185,15 @@ function expandServiceGroups(input) {
             // Rewrite relative dependsOn to final keys; a spread keeps function
             // fields (helpers/setup) and the enumerable-symbol ingress decls.
             const final = { ...svc, ...(part === entry.primary ? primaryOverrides : {}) };
+            // Component-owned nested containers keep their collection when callers
+            // add ordinary service coverage (for example browser coverage on k3s).
+            const collectors = coverageAdapters(svc.coverage).filter(adapter => adapter.collect);
+            if (part === entry.primary && collectors.length && primaryOverrides.coverage !== undefined) {
+                const extra = primaryOverrides.coverage;
+                final.coverage = { ...(typeof extra === "object" ? extra : {}), adapters: [
+                        ...collectors, ...coverageAdapters(extra).filter(adapter => !collectors.includes(adapter)),
+                    ] };
+            }
             if (final.dependsOn?.length) {
                 final.dependsOn = final.dependsOn.map((d) => partKeys.has(d) ? naming.key(d) : d);
             }
@@ -663,12 +673,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.126.0",
+  "version": "0.128.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.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");

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;
@@ -78,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,