@specific.dev/spectest 0.125.0 → 0.126.0

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

@@ -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
 `;
@@ -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/package.json

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

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

@@ -68,3 +68,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

@@ -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
 `;
@@ -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";