@specific.dev/spectest 0.89.0 → 0.90.0

package/src/android.test.ts

@@ -0,0 +1,180 @@
+import { describe, expect, test } from "bun:test";
+import {
+  androidApp,
+  androidScope,
+  androidRecordingChunk,
+  releaseAndroidRecording,
+} from "./android.js";
+import { startRecording, stopRecording } from "./recorder.js";
+
+describe("Android case lifecycle", () => {
+  test("preserves the Appium session, seals recordings per case and records idle-only children", async () => {
+    const requests: { path: string; method: string; body: any }[] = [];
+    const captures = new Map<string, number>();
+    const video = Buffer.from("fake-mp4");
+    let failStop = false;
+    let failClick = false;
+    const server = Bun.serve({
+      port: 0,
+      hostname: "127.0.0.1",
+      async fetch(req) {
+        const url = new URL(req.url),
+          path = url.pathname;
+        const body = req.method === "POST" ? await req.json().catch(() => ({})) : undefined;
+        requests.push({ path, method: req.method, body });
+        const json = (v: unknown) => Response.json(v);
+        if (path === "/recordings" && req.method === "POST") {
+          const now = Date.now();
+          captures.set(body.id, now);
+          return json({ startedAtMs: now });
+        }
+        if (path.startsWith("/recordings/")) {
+          const id = path.split("/")[2];
+          if (path.endsWith("/stop"))
+            return failStop
+              ? Response.json({ error: "encoder failed" }, { status: 500 })
+              : json({
+                  bytes: video.length,
+                  closedAtMs: captures.get(id)! + 60000,
+                  mediaDurationMs: 1000,
+                  width: 360,
+                  height: 640,
+                });
+          if (req.method === "DELETE") {
+            captures.delete(id);
+            return json({ released: true });
+          }
+          const offset = Number(url.searchParams.get("offset")),
+            limit = Number(url.searchParams.get("limit"));
+          return json({
+            total: video.length,
+            offset,
+            b64: video.subarray(offset, offset + limit).toString("base64"),
+          });
+        }
+        if (path === "/session") return json({ value: { sessionId: "kept-session" } });
+        if (path.endsWith("/click") && failClick)
+          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("/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 } });
+        if (path.endsWith("/screenshot"))
+          return json({ value: Buffer.from("PNG").toString("base64") });
+        return json({ value: null });
+      },
+    });
+    const endpoint = `http://127.0.0.1:${server.port}`;
+    const app = androidApp({
+      name: "phone",
+      package: "com.example.app",
+      endpoint,
+      recorderEndpoint: endpoint,
+      serial: "phone-device:5555",
+      recording: {},
+    });
+    startRecording();
+    try {
+      const parent = androidScope("parent", Date.now());
+      await parent.begin([app]);
+      const [a, b] = await Promise.all([parent.open(app), parent.open(app)]);
+      expect(a).toBe(b);
+      await a.getByText('a "quoted" label').fill("private draft");
+      expect((await a.getById("com.example.app:id/draft").text()).unwrap()).toBe("inherited draft");
+      expect(Buffer.from(await a.screenshot()).toString()).toBe("PNG");
+      const [recording] = await parent.finish();
+      expect(recording.error).toBeUndefined();
+      expect(recording.closedAtMs - recording.openedAtMs).toBe(60000);
+      expect(recording.mediaDurationMs).toBe(1000);
+      expect(JSON.stringify(recording)).not.toContain("b64");
+      const chunk = (await androidRecordingChunk(recording.id, 2, 3)) as {
+        offset: number;
+        b64: string;
+      };
+      expect(chunk.offset).toBe(2);
+      expect(Buffer.from(chunk.b64, "base64").toString()).toBe("ke-");
+      await expect(androidRecordingChunk(recording.id, -1, 10)).rejects.toThrow("range");
+      await expect(androidRecordingChunk(recording.id, 0, 6291457)).rejects.toThrow("range");
+      await expect(a.back()).rejects.toThrow("finished test");
+
+      // A real child inherits the registries and sessions from the snapshot.
+      // It starts a new video even when all it does is wait for another service.
+      const idle = androidScope("idle-child", Date.now());
+      await idle.begin([app]);
+      expect(captures.has(recording.id)).toBe(false);
+      const [idleVideo] = await idle.finish();
+      expect(idleVideo.id).not.toBe(recording.id);
+      expect(idleVideo.error).toBeUndefined();
+      await releaseAndroidRecording(idleVideo.id);
+
+      const child = androidScope("active-child", Date.now());
+      await child.begin([app]);
+      const phone = await child.open(app);
+      await phone.getByText("Save").tap();
+      await phone.tap(270, 1800);
+      failClick = true;
+      await expect(phone.getByText("Gone").tap()).rejects.toThrow("Gone");
+      failClick = false;
+      const [childVideo] = await child.finish();
+      expect(childVideo.taps).toHaveLength(2);
+      expect(childVideo.taps![0]).toMatchObject({ x: 0.5, y: 0.2 });
+      expect(childVideo.taps![1]).toMatchObject({ x: 0.25, y: 0.75 });
+      expect(childVideo.taps![0].offsetMs).toBeGreaterThanOrEqual(childVideo.openedAtMs);
+      expect(idleVideo.taps).toEqual([]);
+      expect(recording.taps).toEqual([]);
+      await releaseAndroidRecording(childVideo.id);
+      const hidden = androidScope("no-tap-markers", Date.now());
+      const withoutMarkers = await hidden.open({ ...app, showTouches: false });
+      const rectRequests = requests.filter(r => r.path.endsWith("/rect")).length;
+      await withoutMarkers.getByText("Save").tap();
+      const [hiddenVideo] = await hidden.finish();
+      expect(hiddenVideo.taps).toEqual([]);
+      expect(requests.filter(r => r.path.endsWith("/rect"))).toHaveLength(rectRequests);
+      await releaseAndroidRecording(hiddenVideo.id);
+      const starts = requests.filter((r) => r.path === "/session");
+      expect(starts).toHaveLength(1);
+      expect(starts[0].body.capabilities.alwaysMatch).toMatchObject({
+        "appium:noReset": true,
+        "appium:autoLaunch": false,
+        "appium:newCommandTimeout": 0,
+      });
+      expect(requests.some((r) => r.method === "DELETE" && r.path.startsWith("/session"))).toBe(
+        false,
+      );
+      expect(requests.find((r) => r.body?.using === "-android uiautomator")?.body.value).toBe(
+        'new UiSelector().text("a \\"quoted\\" label")',
+      );
+
+      failStop = true;
+      const failed = androidScope("failed", Date.now());
+      await failed.begin([app]);
+      const [bad] = await failed.finish();
+      expect(bad.error).toContain("encoder failed");
+      expect(captures.size).toBe(0); // failed captures are released too
+      const events = stopRecording();
+      expect(events.filter((e) => e.kind === "android").length).toBe(7);
+    } finally {
+      stopRecording();
+      server.stop(true);
+    }
+  });
+
+  test("recording can be disabled and late work cannot start after a timeout", async () => {
+    const scope = androidScope("timed-out", Date.now());
+    scope.deactivate();
+    await expect(scope.begin()).rejects.toThrow("finished test");
+    expect(await scope.finish()).toEqual([]);
+    const disabled = androidApp({
+      name: "off",
+      package: "com.example",
+      endpoint: "http://unused",
+      recorderEndpoint: "http://unused",
+      serial: "device",
+      recording: false,
+    });
+    const idle = androidScope("disabled", Date.now());
+    await idle.begin([disabled]);
+    expect(await idle.finish()).toEqual([]);
+  });
+});

package/src/android.ts

@@ -0,0 +1,444 @@
+import { createHash } from "node:crypto";
+import { rawFetch } from "./harness/raw-fetch.js";
+import { recordStep, reserveEvent } from "./recorder.js";
+import { wrap, type Wrapped } from "./inspect.js";
+
+export interface AndroidRecordingOptions {
+  /** Maximum dimension of the video, default 1280. */
+  maxSize?: number;
+  /** Maximum frame rate, default 15. Static screens produce few frames. */
+  maxFps?: number;
+  /** H.264 bitrate target in bits/second, default 2,000,000. */
+  bitRate?: number;
+}
+export const ANDROID_APP: unique symbol = Symbol.for("spectest.androidApp");
+export interface AndroidApp {
+  readonly [ANDROID_APP]: true;
+  readonly name: string;
+  readonly endpoint: string;
+  readonly recorderEndpoint: string;
+  readonly serial: string;
+  readonly package: string;
+  readonly recording: false | AndroidRecordingOptions;
+  readonly showTouches?: boolean;
+}
+export function androidApp(options: Omit<AndroidApp, typeof ANDROID_APP>): AndroidApp {
+  return { ...options, [ANDROID_APP]: true as const };
+}
+export function isAndroidApp(value: unknown): value is AndroidApp {
+  return !!value && typeof value === "object" && (value as AndroidApp)[ANDROID_APP] === true;
+}
+
+export class AppiumError extends Error {
+  constructor(
+    public readonly code: string,
+    message: string,
+  ) {
+    super(message);
+    this.name = "AppiumError";
+  }
+}
+async function request<T>(url: string, method = "GET", body?: unknown): Promise<T> {
+  const response = await rawFetch(url, {
+    method,
+    ...(body === undefined
+      ? {}
+      : { headers: { "Content-Type": "application/json" }, body: JSON.stringify(body) }),
+    signal: AbortSignal.timeout(120000),
+  });
+  const data = (await response.json()) as {
+    value?: T & { error?: string; message?: string };
+    error?: string;
+  };
+  if (!response.ok || data.value?.error || data.error)
+    throw new AppiumError(
+      data.value?.error ?? "unknown error",
+      data.value?.message ?? data.error ?? `Android request failed (${response.status})`,
+    );
+  return ("value" in data ? data.value : data) as T;
+}
+
+// Both the Appium session and this registry are preserved by a VM snapshot.
+// Never reset/relaunch the app or delete its session at a case boundary.
+const sessions = new Map<string, Promise<string>>();
+async function session(app: AndroidApp): Promise<string> {
+  const key = JSON.stringify([app.endpoint, app.serial, app.package]);
+  let pending = sessions.get(key);
+  if (!pending) {
+    pending = request<{ sessionId: string }>(`${app.endpoint}/session`, "POST", {
+      capabilities: {
+        alwaysMatch: {
+          platformName: "Android",
+          "appium:automationName": "UiAutomator2",
+          "appium:udid": app.serial,
+          "appium:appPackage": app.package,
+          "appium:noReset": true,
+          "appium:autoLaunch": false,
+          "appium:dontStopAppOnReset": true,
+          "appium:newCommandTimeout": 0,
+        },
+      },
+    })
+      .then((result) => {
+        if (!result.sessionId) throw new Error("Appium returned no session id");
+        return result.sessionId;
+      })
+      .catch((error) => {
+        sessions.delete(key);
+        throw error;
+      });
+    sessions.set(key, pending);
+  }
+  return pending;
+}
+
+export interface AndroidElement {
+  tap(): Promise<void>;
+  fill(text: string): Promise<void>;
+  text(): Promise<Wrapped<string>>;
+  isDisplayed(): Promise<Wrapped<boolean>>;
+  waitFor(options?: { state?: "visible" | "hidden"; timeoutMs?: number }): Promise<void>;
+}
+export interface Android {
+  getByAccessibilityId(id: string): AndroidElement;
+  getById(resourceId: string): AndroidElement;
+  getByText(text: string): AndroidElement;
+  /** Appium selector, e.g. -android uiautomator or xpath. */
+  locator(using: string, value: string): AndroidElement;
+  tap(x: number, y: number): Promise<void>;
+  swipe(direction: "up" | "down" | "left" | "right"): Promise<void>;
+  back(): Promise<void>;
+  pageSource(): Promise<Wrapped<string>>;
+  /** PNG bytes. */
+  screenshot(): Promise<Uint8Array>;
+  /** Appium extension command, e.g. mobile: getDeviceInfo. */
+  execute<T = unknown>(script: string, args?: Record<string, unknown>): Promise<Wrapped<T>>;
+}
+
+export interface AndroidTap {
+  /** Milliseconds from the case start, in the same clock as the video manifest. */
+  offsetMs: number;
+  /** Normalized screen coordinates, independent of encoding resolution. */
+  x: number;
+  y: number;
+}
+export interface AndroidRecording {
+  id: string;
+  name: string;
+  package: string;
+  openedAtMs: number;
+  closedAtMs: number;
+  mediaDurationMs: number;
+  width: number;
+  height: number;
+  bytes: number;
+  taps?: AndroidTap[];
+  error?: string;
+}
+interface Parked {
+  app: AndroidApp;
+  recording: AndroidRecording;
+}
+const parked = new Map<string, Parked>();
+let epoch = 0;
+
+/** A case owns capture and handle lifetime; the Android/Appium processes outlive it. */
+export function androidScope(
+  caseId: string,
+  testStartedAt: number,
+  options: { record?: boolean } = {},
+) {
+  let active = true;
+  const captures = new Map<string, Promise<{ app: AndroidApp; id: string; openedAtMs: number }>>();
+  const handles = new Map<string, Promise<Android>>();
+  const taps = new Map<string, AndroidTap[]>();
+  const assertActive = () => {
+    if (!active) throw new Error("This Android handle belongs to a finished test");
+  };
+  async function capture(app: AndroidApp) {
+    assertActive();
+    if (app.recording === false || options.record === false) return;
+    let pending = captures.get(app.name);
+    if (!pending) {
+      if (captures.size >= 8) throw new Error("A case can record at most eight Android devices");
+      const id = createHash("sha256").update(`${caseId}:${app.name}:${++epoch}`).digest("hex");
+      pending = request<{ startedAtMs: number }>(`${app.recorderEndpoint}/recordings`, "POST", {
+        id,
+        ...app.recording,
+      }).then((result) => ({
+        app,
+        id,
+        openedAtMs: Math.max(0, result.startedAtMs - testStartedAt),
+      }));
+      captures.set(app.name, pending);
+    }
+    await pending;
+  }
+  async function begin(apps: Iterable<AndroidApp> = []) {
+    assertActive();
+    // Previous artifacts were fetched before the VM was handed off. Forked
+    // children can discard their inherited copies without touching siblings.
+    for (const [id, previous] of parked) {
+      await request(`${previous.app.recorderEndpoint}/recordings/${id}`, "DELETE");
+      parked.delete(id);
+    }
+    for (const app of apps) await capture(app);
+    assertActive();
+  }
+  async function open(app: AndroidApp): Promise<Android> {
+    assertActive();
+    if (!isAndroidApp(app))
+      throw new Error("ctx.android(): pass the handle from an android() service");
+    let pending = handles.get(app.name);
+    if (pending) return pending;
+    pending = (async () => {
+      await capture(app);
+      assertActive();
+      const sid = await session(app);
+      assertActive();
+      const command = <T>(method: string, path: string, body?: unknown) => {
+        assertActive();
+        return request<T>(
+          `${app.endpoint}/session/${encodeURIComponent(sid)}${path}`,
+          method,
+          body,
+        );
+      };
+      async function tapMarker(point: { x: number; y: number } | string) {
+        if (!captures.has(app.name) || app.showTouches === false) return;
+        // Appium injects touches after Android's physical-touch visualizer.
+        // Keep markers alongside the video; never change tap semantics or fail
+        // a test just because optional visual feedback could not be measured.
+        try {
+          const screen = await command<{ width: number; height: number }>("GET", "/window/rect");
+          const rect = typeof point === "string"
+            ? await command<{ x: number; y: number; width: number; height: number }>("GET", `${point}/rect`)
+            : { ...point, width: 0, height: 0 };
+          const x = (rect.x + rect.width / 2) / screen.width;
+          const y = (rect.y + rect.height / 2) / screen.height;
+          if (![x, y].every(v => Number.isFinite(v) && v >= 0 && v <= 1)) return;
+          return { x, y, offsetMs: Date.now() - testStartedAt };
+        } catch { return; }
+      }
+      function saveTap(marker: AndroidTap | undefined) {
+        if (!marker || !active) return;
+        const list = taps.get(app.name) ?? [];
+        if (list.length < 10000) list.push(marker);
+        taps.set(app.name, list);
+      }
+      async function op<T>(title: string, fn: () => Promise<T>): Promise<Wrapped<T>> {
+        assertActive();
+        const reservation = reserveEvent(),
+          started = Date.now();
+        try {
+          const result = await fn();
+          const seq = recordStep(
+            {
+              kind: "android",
+              title: `${app.name}: ${title}`,
+              durationMs: Date.now() - started,
+              status: "passed",
+            },
+            reservation,
+          );
+          return wrap(result, seq) as Wrapped<T>;
+        } catch (error) {
+          recordStep(
+            {
+              kind: "android",
+              title: `${app.name}: ${title}`,
+              durationMs: Date.now() - started,
+              status: "failed",
+              error: String(error),
+            },
+            reservation,
+          );
+          throw error;
+        }
+      }
+      const element = (using: string, value: string): AndroidElement => {
+        const label = `${using}=${value}`;
+        const find = async () => {
+          const result = await command<Record<string, string>>("POST", "/element", {
+            using,
+            value,
+          });
+          const id = result["element-6066-11e4-a52e-4f735466cecf"];
+          if (!id) throw new Error("Appium returned no element id");
+          return `/element/${encodeURIComponent(id)}`;
+        };
+        const displayed = 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;
+          }
+        };
+        return {
+          async tap() {
+            await op(`tap ${label}`, async () => {
+              const path = await find();
+              const marker = await tapMarker(path);
+              await command("POST", `${path}/click`, {});
+              saveTap(marker);
+            });
+          },
+          async fill(text) {
+            await op(`fill ${label}`, async () => {
+              const path = await find();
+              await command("POST", `${path}/clear`, {});
+              await command("POST", `${path}/value`, { text });
+            });
+          },
+          text: () =>
+            op(`text ${label}`, async () => command<string>("GET", `${await find()}/text`)),
+          isDisplayed: () => op(`visible ${label}`, displayed),
+          async waitFor(options = {}) {
+            const timeout = options.timeoutMs ?? 10000;
+            if (!Number.isFinite(timeout) || timeout < 0) throw new Error("Invalid wait timeout");
+            await op(`wait for ${options.state ?? "visible"} ${label}`, 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}`);
+            });
+          },
+        };
+      };
+      return {
+        locator: element,
+        getByAccessibilityId: (id) => element("accessibility id", id),
+        getById: (id) => element("id", id),
+        getByText: (text) =>
+          element("-android uiautomator", `new UiSelector().text(${JSON.stringify(text)})`),
+        async tap(x, y) {
+          await op(`tap (${x}, ${y})`, async () => {
+            const marker = await tapMarker({ x, y });
+            await command("POST", "/execute/sync", { script: "mobile: clickGesture", args: [{ x, y }] });
+            saveTap(marker);
+          });
+        },
+        async swipe(direction) {
+          await op(`swipe ${direction}`, async () => {
+            const rect = await command<{ width: number; height: number }>("GET", "/window/rect");
+            await command("POST", "/execute/sync", {
+              script: "mobile: swipeGesture",
+              args: [
+                {
+                  left: rect.width * 0.1,
+                  top: rect.height * 0.1,
+                  width: rect.width * 0.8,
+                  height: rect.height * 0.8,
+                  direction,
+                  percent: 0.75,
+                },
+              ],
+            });
+          });
+        },
+        async back() {
+          await op("back", () => command("POST", "/back", {}));
+        },
+        pageSource: () => op("page source", () => command<string>("GET", "/source")),
+        async screenshot() {
+          const value = await op("screenshot", () => command<string>("GET", "/screenshot"));
+          return Buffer.from(value.unwrap(), "base64");
+        },
+        execute: <T>(script: string, args: Record<string, unknown> = {}) =>
+          op(script, () => command<T>("POST", "/execute/sync", { script, args: [args] })),
+      } satisfies Android;
+    })();
+    handles.set(app.name, pending);
+    return pending;
+  }
+  async function finish(): Promise<AndroidRecording[]> {
+    active = false;
+    const result: AndroidRecording[] = [];
+    for (const [name, pending] of captures) {
+      let owner: AndroidApp | undefined;
+      let recording: AndroidRecording = {
+        id: "",
+        name,
+        package: "",
+        openedAtMs: 0,
+        closedAtMs: Date.now() - testStartedAt,
+        mediaDurationMs: 0,
+        width: 0,
+        height: 0,
+        bytes: 0,
+        taps: taps.get(name) ?? [],
+      };
+      try {
+        const { app, id, openedAtMs } = await pending;
+        owner = app;
+        recording = { ...recording, id, package: app.package, openedAtMs };
+        const stopped = await request<{
+          bytes: number;
+          closedAtMs: number;
+          mediaDurationMs: number;
+          width: number;
+          height: number;
+        }>(`${app.recorderEndpoint}/recordings/${id}/stop`, "POST");
+        recording = {
+          ...recording,
+          bytes: stopped.bytes,
+          width: stopped.width,
+          height: stopped.height,
+          mediaDurationMs: stopped.mediaDurationMs,
+          closedAtMs: Math.max(openedAtMs, stopped.closedAtMs - testStartedAt),
+        };
+        parked.set(id, { app, recording });
+      } catch (error) {
+        recording.error = String(error);
+        // A failed finalization still owns a file in the tools container.
+        if (recording.id) {
+          if (owner)
+            await request(`${owner.recorderEndpoint}/recordings/${recording.id}`, "DELETE").catch(
+              () => {},
+            );
+        }
+      }
+      result.push(recording);
+    }
+    return result;
+  }
+  return {
+    begin,
+    open,
+    finish,
+    deactivate: () => {
+      active = false;
+    },
+  };
+}
+
+export async function androidRecordingChunk(id: string, offset: unknown, limit: unknown) {
+  const entry = parked.get(id);
+  if (!entry) throw new Error("Unknown Android recording");
+  const start = Number(offset ?? 0),
+    count = Number(limit ?? 6291456);
+  if (
+    !Number.isSafeInteger(start) ||
+    start < 0 ||
+    !Number.isSafeInteger(count) ||
+    count < 1 ||
+    count > 6291456
+  )
+    throw new Error("Invalid recording chunk range");
+  return request(`${entry.app.recorderEndpoint}/recordings/${id}?offset=${start}&limit=${count}`);
+}
+export async function releaseAndroidRecording(id: string) {
+  const entry = parked.get(id);
+  if (entry) {
+    await request(`${entry.app.recorderEndpoint}/recordings/${id}`, "DELETE");
+    parked.delete(id);
+  }
+  return { released: true };
+}