@specific.dev/spectest 0.116.2 → 0.118.0

package/dist/daemon.js

@@ -78,7 +78,7 @@ import { openTerminal } from "./terminal.js";
 // client is passed to descendants as a test's return value.
 import { openMcp } from "./mcp.js";
 import { trackHelpers } from "./helper-tracking.js";
-import { isRecording, recordEnv, recordExec, recordStep, recordTerminal, recordWait, reserveEvent, recorderEventCount, recorderMarkChildren, recorderTruncate, startRecording, stopRecording, truncateUtf8, } from "./recorder.js";
+import { isRecording, recordEnv, recordExec, recordStep, namedStep, recordTerminal, recordWait, reserveEvent, recorderEventCount, recorderMarkChildren, recorderTruncate, startRecording, stopRecording, truncateUtf8, } from "./recorder.js";
 import { readRaw, wrap } from "./inspect.js";
 import { setRecordSecrets } from "./record-secrets.js";
 import { setReplayEnvironmentMode } from "./replay-mode.js";
@@ -4446,6 +4446,7 @@ async function runOne(testCase) {
     const phones = phoneScope(start);
     const ctx = {
         ...base,
+        step: namedStep,
         // exec/terminal/poll wrap their results at runtime (the recorder is
         // active), so the ctx interface types them wrapped. The impls' own
         // return types stay raw — hence the bridging casts.
@@ -4942,6 +4943,7 @@ async function evalCode(code) {
     const phones = phoneScope(start, { record: false });
     const ctx = {
         ...base,
+        step: namedStep,
         // Bun does not propagate the import() caller's AsyncLocalStorage into
         // the snippet's module evaluation. Enter the eval scope at the ctx.fetch
         // call itself so top-level awaits and imported helpers get wrapped values

package/dist/index.d.ts

@@ -1201,6 +1201,11 @@ export type TestFn<T = void, P = undefined, S extends ServicesMap = ServicesMap,
  * as the factory's output (e.g. a Bun SQL pool for `postgres(...)`).
  */
 export interface TestContext<P = undefined, S extends ServicesMap = ServicesMap, F extends FakesMap = FakesMap> extends Omit<SpectestContext<S, F>, "exec"> {
+    /** Name one operation or group several operations in the test timeline.
+     * Steps may nest and run concurrently. Returns the callback's value without
+     * changing its type or assertion provenance. Errors propagate unchanged;
+     * a step adds no retries, timeout, or snapshot boundary. */
+    step<T>(name: string, callback: () => T | Promise<T>): Promise<T>;
     /** Run a command inside a service container — a string via `sh -lc`,
      *  or an array as exact argv. The result is {@link Wrapped}, so
      *  `res.stdout` is a `Carrier<string>` — assert via `expect(res.stdout)`

package/dist/recorder.d.ts

@@ -574,7 +574,7 @@ export interface EventReservation {
  * 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 declare function captureRecording(): {
+export declare function captureRecording(groupSeq?: number): {
     run<T>(fn: () => T): T;
     finish(keep: boolean): void;
     isCurrent(): boolean;
@@ -722,6 +722,8 @@ export interface StepEvent extends BaseEvent {
     kind: string;
     /** The step's one-line summary in the timeline. */
     title: string;
+    /** An authored ctx.step scope, displayed as a collapsible group. */
+    group?: boolean;
     /** Native action semantics; titles are presentation only. */
     android?: AndroidStepDetails;
     blocks?: StepBlock[];
@@ -730,6 +732,9 @@ export interface StepEvent extends BaseEvent {
     error?: string;
 }
 export declare function recordStep(ev: Omit<StepEvent, "seq" | "tOffsetMs">, reservation?: EventReservation): number | undefined;
+/** A named recording scope. Values and thrown errors pass through unchanged.
+ * Buffering isolates concurrent scopes and preserves poll/helper grouping. */
+export declare function namedStep<T>(name: string, callback: () => T | Promise<T>): Promise<T>;
 export declare function recordEmail(ev: Omit<EmailEvent, "seq" | "tOffsetMs" | "kind">, reservation?: EventReservation): number | undefined;
 /**
  * Recorded once per `ctx.poll(...)` call. Stands in for the suppressed

package/dist/recorder.js

@@ -15,6 +15,7 @@ class Recorder {
     start;
     rootEvents = [];
     pendingHelpers = new Set();
+    pendingSteps = new Map();
     get events() {
         const branch = recordingBranches.getStore();
         return branch?.owner === this ? branchEvents(branch) : this.rootEvents;
@@ -36,6 +37,7 @@ class Recorder {
             clearPendingNullish();
         const seq = reservation?.seq ?? this.seq++;
         this.events.push({
+            parentSeq: recordingBranches.getStore()?.groupSeq,
             ...ev,
             seq,
             tOffsetMs: reservation?.tOffsetMs ?? Date.now() - this.start,
@@ -75,7 +77,7 @@ class Recorder {
             const ev = this.events[i];
             if (ev.seq === parentSeq)
                 continue;
-            if (ev.parentSeq !== undefined)
+            if (ev.parentSeq !== undefined && ev.parentSeq !== recordingBranches.getStore()?.groupSeq)
                 continue;
             ev.parentSeq = parentSeq;
         }
@@ -126,11 +128,12 @@ function branchAllowsRecording(branch) {
  * 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() {
+export function captureRecording(groupSeq) {
     if (!active())
         return { run: (fn) => fn(), finish: () => { }, isCurrent: () => false };
     const branch = {
         owner: current, events: [], parent: recordingBranches.getStore(),
+        groupSeq: groupSeq ?? recordingBranches.getStore()?.groupSeq,
         destination: current.drain(), state: "open",
     };
     current.pendingHelpers.add(branch);
@@ -179,6 +182,10 @@ export function stopRecording() {
     if (!current)
         return [];
     const evs = current.drain();
+    for (const [event, started] of current.pendingSteps) {
+        event.durationMs = Date.now() - started;
+    }
+    current.pendingSteps.clear();
     // 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) {
@@ -259,6 +266,45 @@ export function recordEnv(ev, reservation) {
 export function recordStep(ev, reservation) {
     return active() ? current.push(ev, reservation) : undefined;
 }
+/** A named recording scope. Values and thrown errors pass through unchanged.
+ * Buffering isolates concurrent scopes and preserves poll/helper grouping. */
+export async function namedStep(name, callback) {
+    if (typeof name !== "string" || !name.trim()) {
+        throw new TypeError("ctx.step requires a non-empty name");
+    }
+    if (!active())
+        return await callback();
+    const owner = current;
+    const started = Date.now();
+    const seq = recordStep({
+        kind: "step", title: name, group: true, status: "error",
+        error: "Step did not finish before the test ended.", durationMs: 0,
+    });
+    const event = owner.drain().find((event) => event.seq === seq);
+    owner.pendingSteps.set(event, started);
+    const recording = captureRecording(seq);
+    try {
+        const value = await recording.run(callback);
+        if (recording.isCurrent()) {
+            event.status = "passed";
+            delete event.error;
+        }
+        return value;
+    }
+    catch (error) {
+        if (recording.isCurrent()) {
+            event.status = "error";
+            event.error = error instanceof Error ? error.message : String(error);
+        }
+        throw error;
+    }
+    finally {
+        if (recording.isCurrent())
+            event.durationMs = Date.now() - started;
+        owner.pendingSteps.delete(event);
+        recording.finish(true);
+    }
+}
 export function recordEmail(ev, reservation) {
     return active() ? current.push({ kind: "email", ...ev }, reservation) : undefined;
 }

package/package.json

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

package/src/daemon.ts

@@ -206,6 +206,7 @@ import {
   recordEnv,
   recordExec,
   recordStep,
+  namedStep,
   recordTerminal,
   recordWait,
   reserveEvent,
@@ -5367,6 +5368,7 @@ async function runOne(testCase: TestCase<unknown>): Promise<RunResult> {
   const phones = phoneScope(start);
   const ctx: TestContext<unknown> = {
     ...base,
+    step: namedStep,
     // exec/terminal/poll wrap their results at runtime (the recorder is
     // active), so the ctx interface types them wrapped. The impls' own
     // return types stay raw — hence the bridging casts.
@@ -5929,6 +5931,7 @@ async function evalCode(code: string): Promise<EvalResult> {
   const phones = phoneScope(start, { record: false });
   const ctx: TestContext<undefined> = {
     ...base,
+    step: namedStep,
     // Bun does not propagate the import() caller's AsyncLocalStorage into
     // the snippet's module evaluation. Enter the eval scope at the ctx.fetch
     // call itself so top-level awaits and imported helpers get wrapped values

package/src/index.ts

@@ -1866,6 +1866,11 @@ export interface TestContext<
   S extends ServicesMap = ServicesMap,
   F extends FakesMap = FakesMap,
 > extends Omit<SpectestContext<S, F>, "exec"> {
+  /** Name one operation or group several operations in the test timeline.
+   * Steps may nest and run concurrently. Returns the callback's value without
+   * changing its type or assertion provenance. Errors propagate unchanged;
+   * a step adds no retries, timeout, or snapshot boundary. */
+  step<T>(name: string, callback: () => T | Promise<T>): Promise<T>;
   /** Run a command inside a service container — a string via `sh -lc`,
    *  or an array as exact argv. The result is {@link Wrapped}, so
    *  `res.stdout` is a `Carrier<string>` — assert via `expect(res.stdout)`

package/src/named-step.test.ts

@@ -0,0 +1,111 @@
+import { afterEach, expect, test } from "bun:test";
+import { annotate } from "./annotate.js";
+import { trackHelpers } from "./helper-tracking.js";
+import { expect as assertValue } from "./index.js";
+import { adoptNullishTag, readTag, wrap } from "./inspect.js";
+import {
+  captureRecording, namedStep, recordStep, recordWait, recorderEventCount,
+  recorderMarkChildren, startRecording, stopRecording,
+} from "./recorder.js";
+
+afterEach(() => stopRecording());
+const operation = (title: string) => recordStep({ kind: "example", title })!;
+
+test("returns values unchanged and nests scopes without flattening operations", async () => {
+  startRecording();
+  const value = await namedStep("outer", () => namedStep("inner", () => {
+    return wrap({ total: 42 }, operation("read"));
+  }));
+  const events = stopRecording();
+  expect(events.map(e => [e.seq, e.parentSeq])).toEqual([[0, undefined], [1, 0], [2, 1]]);
+  expect(readTag(value.total)?.sourceSeq).toBe(2);
+  expect(value.total.unwrap()).toBe(42);
+});
+
+test("keeps nullable provenance when the callback returns", async () => {
+  startRecording();
+  const value = await namedStep("read nullable", () => wrap({ total: null }, operation("read")).total);
+  expect(value).toBeNull();
+  expect(readTag(adoptNullishTag(value))).toEqual({ sourceSeq: 1, path: ["total"] });
+});
+
+test("concurrent scopes never capture each other's operations", async () => {
+  startRecording();
+  let release!: () => void;
+  const gate = new Promise<void>(resolve => { release = resolve; });
+  await Promise.all([
+    namedStep("first", async () => { await gate; operation("first child"); }),
+    namedStep("second", () => { operation("second child"); release(); }),
+  ]);
+  const events = stopRecording();
+  const parent = (title: string) => events.find(e => "title" in e && e.title === title)!;
+  expect(parent("first child").parentSeq).toBe(parent("first").seq);
+  expect(parent("second child").parentSeq).toBe(parent("second").seq);
+});
+
+test("poll grouping and captured helper annotations keep their own hierarchy", async () => {
+  startRecording();
+  await namedStep("scope", () => {
+    const from = recorderEventCount();
+    const helper = captureRecording();
+    helper.run(() => operation("helper"));
+    helper.finish(true);
+    const wait = recordWait({ description: "ready", attempts: 1, durationMs: 1, passed: true })!;
+    recorderMarkChildren(from, wait);
+  });
+  const events = stopRecording();
+  expect(events.find(e => e.seq === 1)?.parentSeq).toBe(2);
+  expect(events.find(e => e.seq === 2)?.parentSeq).toBe(0);
+});
+
+test("retains diagnostics and propagates the identical thrown error", async () => {
+  startRecording();
+  const error = new Error("checkout failed");
+  try {
+    await namedStep("checkout", () => { operation("before failure"); throw error; });
+    throw new Error("expected callback failure");
+  } catch (caught) { expect(caught).toBe(error); }
+  const events = stopRecording();
+  expect(events[0]).toMatchObject({ group: true, status: "error", error: "checkout failed" });
+  expect(events[1]?.parentSeq).toBe(0);
+});
+
+test("a timeout retains unfinished scopes and fences late work from the next test", async () => {
+  startRecording();
+  let release!: () => void;
+  const gate = new Promise<void>(resolve => { release = resolve; });
+  const pending = namedStep("unfinished", async () => {
+    operation("before timeout");
+    await gate;
+    operation("late");
+  });
+  const events = stopRecording();
+  expect(events).toHaveLength(2);
+  expect(events[0]).toMatchObject({ group: true, status: "error" });
+  expect(events[1]?.parentSeq).toBe(0);
+  startRecording();
+  release();
+  await pending;
+  expect(stopRecording()).toEqual([]);
+});
+
+test("works without recording and rejects blank names", async () => {
+  const value = { key: "web" as const, total: 42 };
+  expect(await namedStep("plain", () => value)).toBe(value);
+  await expect(namedStep("  ", () => value)).rejects.toThrow("non-empty name");
+});
+
+
+test("annotated helper children and external assertions retain provenance inside a named scope", async () => {
+  startRecording();
+  const helpers = trackHelpers("fake", "mail", {
+    latest() { return annotate({ subject: "Invoice" }, "email"); },
+  });
+  const mail = await namedStep("Read email", () => helpers.latest());
+  assertValue(mail.subject).toBe("Invoice");
+  const events = stopRecording();
+  const helper = events.find(event => event.kind === "fake")!;
+  expect(helper.parentSeq).toBe(0);
+  expect(events.find(event => event.kind === "email")?.parentSeq).toBe(helper.seq);
+  expect(events.find(event => event.kind === "assertion")).toMatchObject({ sourceSeq: helper.seq });
+});

package/src/recorder.ts

@@ -643,6 +643,7 @@ export interface EventReservation {
 class Recorder {
   private rootEvents: TestEvent[] = [];
   readonly pendingHelpers = new Set<RecordingBranch>();
+  readonly pendingSteps = new Map<StepEvent, number>();
   private get events(): TestEvent[] {
     const branch = recordingBranches.getStore();
     return branch?.owner === this ? branchEvents(branch) : this.rootEvents;
@@ -666,6 +667,7 @@ class Recorder {
     if (ev.kind !== "assertion") clearPendingNullish();
     const seq = reservation?.seq ?? this.seq++;
     this.events.push({
+      parentSeq: recordingBranches.getStore()?.groupSeq,
       ...ev,
       seq,
       tOffsetMs: reservation?.tOffsetMs ?? Date.now() - this.start,
@@ -708,7 +710,7 @@ class Recorder {
     for (let i = startIdx; i < this.events.length; i++) {
       const ev = this.events[i]!;
       if (ev.seq === parentSeq) continue;
-      if (ev.parentSeq !== undefined) continue;
+      if (ev.parentSeq !== undefined && ev.parentSeq !== recordingBranches.getStore()?.groupSeq) continue;
       ev.parentSeq = parentSeq;
     }
   }
@@ -749,6 +751,8 @@ class Recorder {
 let current: Recorder | null = null;
 
 interface RecordingBranch {
+  /** Nearest authored scope; internal poll/helper grouping may refine it. */
+  groupSeq?: number;
   owner: Recorder;
   events: TestEvent[];
   parent: RecordingBranch | undefined;
@@ -773,7 +777,7 @@ function branchAllowsRecording(branch: RecordingBranch | undefined): boolean {
  * 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(): {
+export function captureRecording(groupSeq?: number): {
   run<T>(fn: () => T): T;
   finish(keep: boolean): void;
   isCurrent(): boolean;
@@ -781,6 +785,7 @@ export function captureRecording(): {
   if (!active()) return { run: (fn) => fn(), finish: () => {}, isCurrent: () => false };
   const branch: RecordingBranch = {
     owner: current!, events: [], parent: recordingBranches.getStore(),
+    groupSeq: groupSeq ?? recordingBranches.getStore()?.groupSeq,
     destination: current!.drain(), state: "open",
   };
   current!.pendingHelpers.add(branch);
@@ -831,6 +836,10 @@ export function startRecording(startedAt = Date.now()): void {
 export function stopRecording(): TestEvent[] {
   if (!current) return [];
   const evs = current.drain();
+  for (const [event, started] of current.pendingSteps) {
+    event.durationMs = Date.now() - started;
+  }
+  current.pendingSteps.clear();
   // 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) {
@@ -1038,6 +1047,8 @@ export interface StepEvent extends BaseEvent {
   kind: string;
   /** The step's one-line summary in the timeline. */
   title: string;
+  /** An authored ctx.step scope, displayed as a collapsible group. */
+  group?: boolean;
   /** Native action semantics; titles are presentation only. */
   android?: AndroidStepDetails;
   blocks?: StepBlock[];
@@ -1053,6 +1064,42 @@ export function recordStep(
   return active() ? current!.push(ev, reservation) : undefined;
 }
 
+/** A named recording scope. Values and thrown errors pass through unchanged.
+ * Buffering isolates concurrent scopes and preserves poll/helper grouping. */
+export async function namedStep<T>(name: string, callback: () => T | Promise<T>): Promise<T> {
+  if (typeof name !== "string" || !name.trim()) {
+    throw new TypeError("ctx.step requires a non-empty name");
+  }
+  if (!active()) return await callback();
+  const owner = current!;
+  const started = Date.now();
+  const seq = recordStep({
+    kind: "step", title: name, group: true, status: "error",
+    error: "Step did not finish before the test ended.", durationMs: 0,
+  })!;
+  const event = owner.drain().find((event) => event.seq === seq)! as StepEvent;
+  owner.pendingSteps.set(event, started);
+  const recording = captureRecording(seq);
+  try {
+    const value = await recording.run(callback);
+    if (recording.isCurrent()) {
+      event.status = "passed";
+      delete event.error;
+    }
+    return value;
+  } catch (error) {
+    if (recording.isCurrent()) {
+      event.status = "error";
+      event.error = error instanceof Error ? error.message : String(error);
+    }
+    throw error;
+  } finally {
+    if (recording.isCurrent()) event.durationMs = Date.now() - started;
+    owner.pendingSteps.delete(event);
+    recording.finish(true);
+  }
+}
+
 export function recordEmail(
   ev: Omit<EmailEvent, "seq" | "tOffsetMs" | "kind">,
   reservation?: EventReservation,