@specific.dev/spectest 0.107.2 → 0.108.0

package/src/recorder.ts

@@ -8,6 +8,7 @@
 // current recorder is `null` and the `record*` helpers are no-ops, so
 // callers can invoke them unconditionally.
 
+import { AsyncLocalStorage } from "node:async_hooks";
 import type { AndroidStepDetails } from "./android-step.js";
 import { clearPendingNullish } from "./inspect.js";
 import { scopeAllowsRecording } from "./harness/instrumentation-scope.js";
@@ -27,6 +28,7 @@ export type TestEvent =
   | TerminalStepEvent
   | WaitEvent
   | FakeEvent
+  | ServiceHelperEvent
   | EnvEvent
   | EmailEvent
   // Open `kind`, so it goes last: narrowing the union by a literal kind
@@ -339,6 +341,14 @@ export interface FakeEvent extends BaseEvent {
   error?: string;
 }
 
+/** An annotated service helper has the same call/return shape as a fake.
+ * Only helpers returning an annotation emit this event. */
+export interface ServiceHelperEvent extends Omit<FakeEvent, "kind" | "fake"> {
+  kind: "service";
+  /** Service name — the key in `ctx.svc`. */
+  service: string;
+}
+
 /**
  * One captured email, as embedded on an {@link EmailEvent}. The HTML and
  * text bodies ride along (truncated to the output cap) so the dashboard
@@ -631,7 +641,12 @@ export interface EventReservation {
 }
 
 class Recorder {
-  private events: TestEvent[] = [];
+  private rootEvents: TestEvent[] = [];
+  readonly pendingHelpers = new Set<RecordingBranch>();
+  private get events(): TestEvent[] {
+    const branch = recordingBranches.getStore();
+    return branch?.owner === this ? branchEvents(branch) : this.rootEvents;
+  }
   private seq = 0;
   constructor(private readonly start = Date.now()) {}
 
@@ -733,6 +748,60 @@ class Recorder {
 
 let current: Recorder | null = null;
 
+interface RecordingBranch {
+  owner: Recorder;
+  events: TestEvent[];
+  parent: RecordingBranch | undefined;
+  destination: TestEvent[];
+  state: "open" | "kept" | "discarded";
+}
+
+const recordingBranches = new AsyncLocalStorage<RecordingBranch>();
+
+function branchEvents(branch: RecordingBranch): TestEvent[] {
+  return branch.state === "kept"
+    ? branch.parent ? branchEvents(branch.parent) : branch.destination
+    : branch.events;
+}
+
+function branchAllowsRecording(branch: RecordingBranch | undefined): boolean {
+  return !branch || (branch.owner === current && branch.state !== "discarded" &&
+    branchAllowsRecording(branch.parent));
+}
+
+/** Buffer a helper's async descendants until its return chooses between the
+ * implementation's events and one annotated helper call. Seqs still come from
+ * the test recorder, so concurrent calls and linked assertions stay unique.
+ * Poll truncation/grouping inside the helper applies only to its own buffer. */
+export function captureRecording(): {
+  run<T>(fn: () => T): T;
+  finish(keep: boolean): void;
+  isCurrent(): boolean;
+} {
+  if (!active()) return { run: (fn) => fn(), finish: () => {}, isCurrent: () => false };
+  const branch: RecordingBranch = {
+    owner: current!, events: [], parent: recordingBranches.getStore(),
+    destination: current!.drain(), state: "open",
+  };
+  current!.pendingHelpers.add(branch);
+  return {
+    run: (fn) => recordingBranches.run(branch, fn),
+    isCurrent: () => branch.owner === current && active(),
+    finish(keep) {
+      if (branch.state !== "open") return;
+      branch.owner.pendingHelpers.delete(branch);
+      if (keep && branchAllowsRecording(branch)) {
+        const destination = branch.parent ? branchEvents(branch.parent) : branch.destination;
+        for (const event of branch.events) destination.push(event);
+        branch.state = "kept";
+      } else {
+        branch.state = "discarded";
+      }
+      branch.events.length = 0;
+    },
+  };
+}
+
 // Counter-based pause: `pauseRecording`/`resumeRecording` nest safely
 // (a nested `ctx.poll` inside another `ctx.poll`'s predicate stays
 // suppressed until its own resume balances out). Active record* sites
@@ -751,7 +820,7 @@ export function resumeRecording(): void {
 }
 
 function active(): boolean {
-  return current !== null && paused === 0 && scopeAllowsRecording();
+  return current !== null && paused === 0 && scopeAllowsRecording() && branchAllowsRecording(recordingBranches.getStore());
 }
 
 export function startRecording(startedAt = Date.now()): void {
@@ -762,6 +831,18 @@ export function startRecording(startedAt = Date.now()): void {
 export function stopRecording(): TestEvent[] {
   if (!current) return [];
   const evs = current.drain();
+  // A timeout can stop the test before a helper returns. Keep its available
+  // diagnostics, then fence detached work out of any subsequent recording.
+  for (const branch of current.pendingHelpers) {
+    if (branchAllowsRecording(branch)) {
+      for (const event of branch.events) evs.push(event);
+    }
+  }
+  for (const branch of current.pendingHelpers) {
+    branch.events.length = 0;
+    branch.state = "discarded";
+  }
+  current.pendingHelpers.clear();
   current = null;
   paused = 0;
   return evs;
@@ -862,6 +943,13 @@ export function recordFake(
   return active() ? current!.push({ kind: "fake", ...ev }, reservation) : undefined;
 }
 
+export function recordServiceHelper(
+  ev: Omit<ServiceHelperEvent, "seq" | "tOffsetMs" | "kind">,
+  reservation?: EventReservation,
+): number | undefined {
+  return active() ? current!.push({ kind: "service", ...ev }, reservation) : undefined;
+}
+
 export function recordEnv(
   ev: Omit<EnvEvent, "seq" | "tOffsetMs" | "kind">,
   reservation?: EventReservation,
@@ -992,11 +1080,7 @@ export function recordWait(
   ev: Omit<WaitEvent, "seq" | "tOffsetMs" | "kind">,
   reservation?: EventReservation,
 ): number | undefined {
-  // Use `current` directly (not `active()`) so a `recordWait` at the
-  // end of a `ctx.poll` block lands even though the surrounding code
-  // just resumed from `paused`. Pushing this event is the whole point
-  // of the poll primitive.
-  return current?.push({ kind: "wait", ...ev }, reservation);
+  return active() ? current!.push({ kind: "wait", ...ev }, reservation) : undefined;
 }
 
 /** Number of events the active recorder has accumulated. Returns 0