@specific.dev/spectest 0.128.0 → 0.129.0

package/src/recorder.ts

@@ -467,6 +467,9 @@ export interface RecordedBrowserLocatorPart {
 
 export interface BrowserEvent extends BaseEvent {
   kind: "browser";
+  /** Explicit navigation options, when supplied by the test. */
+  timeout?: number;
+  waitUntil?: "load" | "domcontentloaded" | "networkidle" | "commit";
   action: BrowserAction;
   target?: RecordedBrowserLocatorPart[];
   destinationTarget?: RecordedBrowserLocatorPart[];
@@ -599,6 +602,14 @@ export type TerminalStepAction =
   | "exit"
   | "close";
 
+export type TerminalWaitMatcher =
+  | { kind: "text"; value: string }
+  | { kind: "regex"; value: string; flags: string }
+  | { kind: "custom"; description?: string };
+
+export type TerminalWaitOutcome = "matched" | "timed_out" | "failure_matched"
+  | "predicate_error" | "process_exited" | "cancelled";
+
 /**
  * One operation on an open interactive terminal — analogous to
  * `BrowserEvent`. The session's heavy asciicast frames live on the
@@ -622,9 +633,18 @@ export interface TerminalStepEvent extends BaseEvent {
   description?: string;
   /** How many polls `waitFor` made. */
   attempts?: number;
-  /** Whether `waitFor` matched (false means it timed out). */
+  /** Whether `waitFor` matched; see outcome for failure reasons. */
   matched?: boolean;
-  /** Exit code observed on `close`. */
+  /** The condition being observed, including an optional custom-predicate description. */
+  matcher?: TerminalWaitMatcher;
+  outcome?: TerminalWaitOutcome;
+  failureMatchers?: { description: string; matcher: TerminalWaitMatcher }[];
+  intervalMs?: number;
+  timeoutMs?: number;
+  /** Wait boundaries on the session clock, including time with no output. */
+  castStartTimeSec?: number;
+  castEndTimeSec?: number;
+  /** Exit code observed on exit, close, or a failed wait. */
   exitCode?: number;
   /** Rendered screen at the moment of the op (post-action), truncated. */
   screenPreview: string;

package/src/terminal.test.ts

@@ -0,0 +1,324 @@
+import { afterEach, expect, spyOn, test } from "bun:test";
+import { openTerminal } from "./terminal.js";
+import { startRecording, stopRecording } from "./recorder.js";
+
+afterEach(() => stopRecording());
+
+async function session(opts: { killExits?: boolean; eofExits?: boolean } = {}) {
+  let stream!: ReadableStreamDefaultController<Uint8Array>;
+  let resolveExit!: (code: number) => void;
+  let streamClosed = false;
+  let processExited = false;
+  const output = (text: string) => { if (!streamClosed) stream.enqueue(new TextEncoder().encode(text)); };
+  const endOutput = () => { if (!streamClosed) { streamClosed = true; stream.close(); } };
+  const exit = (code = 0, drain = true) => {
+    if (drain) endOutput();
+    if (!processExited) { processExited = true; resolveExit(code); }
+  };
+  const writes: string[] = [];
+  const kills: unknown[] = [];
+  const fake = {
+    stdout: new ReadableStream<Uint8Array>({ start(c) { stream = c; }, cancel() { streamClosed = true; } }),
+    stderr: new ReadableStream<Uint8Array>({ start(c) { c.close(); } }),
+    stdin: { write: (data: string) => {
+      writes.push(data);
+      if (data === "\x03") setTimeout(() => output("\r\n^C"), 0);
+      if (data === "\x04" && opts.eofExits) exit();
+    } },
+    exited: new Promise<number>((resolve) => { resolveExit = resolve; }),
+    kill: (signal: unknown) => { kills.push(signal); if (opts.killExits !== false) exit(137); },
+  };
+  const spawn = spyOn(Bun, "spawn").mockReturnValue(fake as unknown as ReturnType<typeof Bun.spawn>);
+  try {
+    const term = await openTerminal({
+      service: "rack", sessionId: "shell", recordEvents: true,
+      sink: { pushFrame() {}, markClosed() {} },
+    });
+    return { term, output, exit, endOutput, writes, kills, async close() {
+      exit();
+      try { await term.close(); } catch { /* a tested close failure remains memoized */ }
+      spawn.mockRestore();
+    } };
+  } catch (error) {
+    exit(); spawn.mockRestore(); throw error;
+  }
+}
+
+function waitEvents() {
+  return stopRecording().filter(e => e.kind === "terminal-step" && e.action === "waitFor");
+}
+
+test.each([
+  ["Initialized", { kind: "text", value: "Initialized" }],
+  [/Initialized/i, { kind: "regex", value: "Initialized", flags: "i" }],
+  [(screen: string) => screen.includes("Initialized"), { kind: "custom" }],
+] as const)("waitFor records its condition and bounds without an outer wait: %p", async (matcher, expected) => {
+  startRecording();
+  const s = await session();
+  try {
+    s.output("Booting\r\n");
+    const timer = setTimeout(() => s.output("Initialized\r\n"), 40);
+    try {
+      await s.term.waitFor("Rack is ready", matcher as string, { timeoutMs: 1000, intervalMs: 5 });
+    } finally { clearTimeout(timer); }
+    await s.term.press("Ctrl+C");
+    const events = stopRecording();
+    const wait = events.find(e => e.kind === "terminal-step" && e.action === "waitFor");
+    if (wait?.kind !== "terminal-step") throw new Error("Missing wait event");
+    expect(wait.matcher).toEqual(expected);
+    expect(wait.description).toBe("Rack is ready");
+    expect(wait.matched).toBe(true);
+    expect(wait.attempts).toBeGreaterThan(1);
+    expect(wait.timeoutMs).toBe(1000);
+    expect(wait.castEndTimeSec!).toBeGreaterThan(wait.castStartTimeSec!);
+    expect(wait.screenPreview).toContain("Initialized");
+    expect(wait.screenPreview).not.toContain("^C");
+    const press = events.find(e => e.kind === "terminal-step" && e.action === "press");
+    expect(press?.seq).toBeGreaterThan(wait.seq);
+    expect(events.filter(e => e.kind === "wait")).toHaveLength(0);
+  } finally { await s.close(); }
+});
+
+test("a quiet timeout records elapsed time even after the last terminal frame", async () => {
+  startRecording();
+  const s = await session();
+  try {
+    s.output("Still booting");
+    await expect(s.term.waitFor("Rack is ready", "Initialized", { timeoutMs: 60, intervalMs: 5 }))
+      .rejects.toThrow("timed out");
+    const wait = stopRecording().find(e => e.kind === "terminal-step" && e.action === "waitFor");
+    if (wait?.kind !== "terminal-step") throw new Error("Missing wait event");
+    expect(wait.matched).toBe(false);
+    expect(wait.durationMs).toBeGreaterThanOrEqual(60);
+    expect(wait.castEndTimeSec!).toBeGreaterThan(wait.castTimeSec);
+    expect(wait.screenPreview).toBe("Still booting");
+  } finally { await s.close(); }
+});
+
+
+test("records a thrown predicate error once, preserving its identity and observed screen", async () => {
+  const s = await session();
+  startRecording();
+  try {
+    s.output("Initialization Failed");
+    const failure = new Error("Rack initialization failed");
+    await expect(s.term.waitFor("Initialized", async screen => {
+      if (screen.includes("Failed")) {
+        // The screen can change while an async predicate is running. Keep
+        // the frame that was actually checked as the failure evidence.
+        s.output("\r\nLater unrelated output");
+        await Bun.sleep(5);
+        throw failure;
+      }
+      return false;
+    }, { intervalMs: 2 })).rejects.toBe(failure);
+    const events = waitEvents();
+    expect(events).toHaveLength(1);
+    expect(events[0]).toMatchObject({ outcome:"predicate_error", matched:false,
+      error:failure.message, screenPreview:"Initialization Failed" });
+  } finally { await s.close(); }
+});
+
+test("records declarative failure conditions and their outcome before accepting success", async () => {
+  const s = await session();
+  startRecording();
+  try {
+    s.output("Initialized\r\nInitialization Panicked");
+    await expect(s.term.waitFor("Rack initialized", "Initialized", { intervalMs:2,
+      failOn:[{description:"Rack initialization panicked",matcher:/Initialization Panicked/}],
+    })).rejects.toThrow("Rack initialization panicked");
+    expect(waitEvents()[0]).toMatchObject({outcome:"failure_matched", matched:false,
+      failureMatchers:[{description:"Rack initialization panicked",matcher:{kind:"regex",value:"Initialization Panicked",flags:""}}]});
+  } finally { await s.close(); }
+});
+
+test("checks final drained output before accepting process exit, without waiting a poll interval", async () => {
+  const s = await session();
+  startRecording();
+  try {
+    const pending = s.term.waitFor("Ready", "Initialized", {intervalMs:10000,timeoutMs:1000});
+    s.exit(0, false);
+    s.output("Initialized");
+    s.endOutput();
+    await pending;
+    expect(waitEvents()[0]).toMatchObject({outcome:"matched",screenPreview:"Initialized"});
+  } finally { await s.close(); }
+});
+
+test("a disconnect wakes a quiet wait and records the exit code", async () => {
+  const s = await session();
+  startRecording();
+  try {
+    const pending = s.term.waitFor("Ready", "Initialized", {intervalMs:10000,timeoutMs:1000});
+    s.output("Disconnected");
+    s.exit(255);
+    await expect(pending).rejects.toThrow("exited with code 255");
+    expect(waitEvents()[0]).toMatchObject({outcome:"process_exited",exitCode:255,screenPreview:"Disconnected"});
+  } finally { await s.close(); }
+});
+
+test("reading exited does not reserve an event before the process actually exits", async () => {
+  const s = await session();
+  startRecording();
+  try {
+    const exiting = s.term.exited;
+    expect(s.term.exited).toBe(exiting);
+    s.output("Ready");
+    await s.term.waitFor("Ready", "Ready", {intervalMs:2});
+    await s.term.press("Ctrl+C");
+    s.exit();
+    await exiting;
+    const events = stopRecording().filter(e => e.kind === "terminal-step");
+    expect(events.map(e => e.action)).toEqual(["waitFor", "press", "exit"]);
+    expect(events[2].tOffsetMs).toBeGreaterThanOrEqual(events[1].tOffsetMs);
+  } finally { await s.close(); }
+});
+
+test("abort stops polling, records cancellation once, and leaves the terminal usable", async () => {
+  const s = await session();
+  startRecording();
+  try {
+    const control = new AbortController();
+    let checks = 0;
+    const pending = s.term.waitFor("Ready", () => { checks++; return false; }, {signal:control.signal,intervalMs:5});
+    await Bun.sleep(10);
+    const failure = new Error("User cancelled");
+    control.abort(failure);
+    await expect(pending).rejects.toBe(failure);
+    const stopped = checks;
+    await Bun.sleep(15);
+    expect(checks).toBe(stopped);
+    expect(waitEvents()).toMatchObject([{outcome:"cancelled",error:"User cancelled"}]);
+    s.output("Ready");
+    await s.term.waitFor("Still usable", "Ready", {intervalMs:2});
+  } finally { await s.close(); }
+});
+
+test("async predicates are awaited and a hung predicate respects the deadline", async () => {
+  const s = await session();
+  startRecording();
+  try {
+    let checks = 0;
+    await s.term.waitFor("Async readiness", async () => ++checks === 2 ? "ready" : false,
+      {intervalMs:2,condition:"The async readiness check returns ready"});
+    expect(checks).toBe(2);
+    let finish!: (result: string) => void;
+    await expect(s.term.waitFor("Hung", () => new Promise<string>(resolve => {finish = resolve;}),
+      {timeoutMs:20})).rejects.toThrow("timed out");
+    finish("too late");
+    await Bun.sleep(5);
+    const events = waitEvents();
+    expect(events).toHaveLength(2);
+    expect(events[0]).toMatchObject({outcome:"matched",matcher:{kind:"custom",description:"The async readiness check returns ready"}});
+    expect(events[1]).toMatchObject({outcome:"timed_out",matched:false});
+  } finally { await s.close(); }
+});
+
+test("close sends EOF, cancels active waits, and is idempotent", async () => {
+  const s = await session({eofExits:true});
+  startRecording();
+  try {
+    const pending = s.term.waitFor("Ready", "Ready", {intervalMs:10000});
+    const rejected = pending.catch(error => error);
+    const closing = s.term.close();
+    expect(s.term.close()).toBe(closing);
+    await closing;
+    expect((await rejected).message).toContain("cancelled");
+    expect(s.writes).toContain("\x04");
+    expect(s.kills).toHaveLength(0);
+    const events = stopRecording().filter(e => e.kind === "terminal-step");
+    expect(events.filter(e => e.action === "close")).toHaveLength(1);
+    expect(events.find(e => e.action === "waitFor")).toMatchObject({outcome:"cancelled"});
+  } finally { await s.close(); }
+});
+
+test.each(["process", "pipe"])("close has a deadline when the %s never finishes", async (stuck) => {
+  const s = await session({killExits:false});
+  startRecording();
+  try {
+    if (stuck === "pipe") s.exit(0, false);
+    const closing = s.term.close({timeoutMs:40});
+    await expect(closing).rejects.toThrow("close timed out");
+    expect(s.term.close()).toBe(closing);
+    if (stuck === "process") expect(s.kills).toContain("SIGKILL");
+    expect(stopRecording().filter(e => e.kind === "terminal-step" && e.action === "close"))
+      .toMatchObject([{error:"Terminal close timed out after 40ms"}]);
+  } finally { await s.close(); }
+});
+
+test.skipIf(!Bun.which("script"))("real PTY drains its last screen and preserves the child exit status", async () => {
+  const spawn = Bun.spawn.bind(Bun);
+  const intercepted = spyOn(Bun, "spawn").mockImplementation(((args: string[], opts: unknown) => {
+    // Exercise the production PTY flags and streams, replacing only Docker.
+    return spawn([args[0], args[1], "printf 'Final status: Initialized\\n'; exit 7", args[3]], opts as never);
+  }) as typeof Bun.spawn);
+  startRecording();
+  let term: Awaited<ReturnType<typeof openTerminal>> | undefined;
+  try {
+    term = await openTerminal({service:"rack",sessionId:"real-pty",recordEvents:true,
+      sink:{pushFrame() {},markClosed() {}}});
+    await term.waitFor("Final status", "Final status: Initialized", {intervalMs:10000,timeoutMs:2000});
+    const result = await term.exited;
+    const { readRaw } = await import("./inspect.js");
+    expect(readRaw(result.exitCode)).toBe(7);
+    const events = stopRecording().filter(e => e.kind === "terminal-step");
+    expect(events.find(e => e.action === "waitFor")).toMatchObject({outcome:"matched",screenPreview:"Final status: Initialized"});
+    expect(events.find(e => e.action === "exit")).toMatchObject({exitCode:7});
+  } finally {
+    await term?.close();
+    intercepted.mockRestore();
+  }
+});
+
+test("an already-aborted wait never calls its predicate", async () => {
+  const s = await session();
+  startRecording();
+  try {
+    let checks = 0;
+    const signal = AbortSignal.abort(new Error("Already cancelled"));
+    await expect(s.term.waitFor("Ready", () => { checks++; return true; }, {signal}))
+      .rejects.toThrow("Already cancelled");
+    expect(checks).toBe(0);
+    expect(waitEvents()).toMatchObject([{outcome:"cancelled",attempts:0}]);
+  } finally { await s.close(); }
+});
+
+test("an async check interrupted by exit rechecks the final screen", async () => {
+  const s = await session();
+  startRecording();
+  try {
+    let release!: (value: boolean) => void;
+    const pending = s.term.waitFor("Ready", screen => screen.includes("Ready") ||
+      new Promise<boolean>(resolve => { release = resolve; }), {timeoutMs:1000});
+    await Bun.sleep(5);
+    s.output("Ready");
+    s.exit();
+    await Bun.sleep(5);
+    release(false);
+    await pending;
+    expect(waitEvents()).toMatchObject([{outcome:"matched",screenPreview:"Ready",attempts:2}]);
+  } finally { await s.close(); }
+});
+
+test("close escalates after EOF and returns the real killed status", async () => {
+  const s = await session();
+  try {
+    const result = await s.term.close({timeoutMs:100});
+    const { readRaw } = await import("./inspect.js");
+    expect(readRaw(result.exitCode)).toBe(137);
+    expect(s.writes).toEqual(["\x04"]);
+    expect(s.kills).toEqual(["SIGKILL"]);
+  } finally { await s.close(); }
+});
+
+test("exit cannot wait forever for an inherited output pipe", async () => {
+  const s = await session();
+  startRecording();
+  try {
+    const waiting = s.term.waitFor("Ready", "Ready", {timeoutMs:8000,intervalMs:10000});
+    s.exit(0, false);
+    await expect(waiting).rejects.toThrow("did not finish draining");
+    expect(waitEvents()).toMatchObject([{outcome:"process_exited",exitCode:0}]);
+    await expect(s.term.exited).rejects.toThrow("did not finish draining");
+  } finally { await s.close(); }
+}, 10000);