@specific.dev/spectest 0.49.0 → 0.51.0

package/src/recorder.test.ts

@@ -0,0 +1,57 @@
+import { describe, expect, test } from "bun:test";
+
+import {
+  recordEmail,
+  recordFake,
+  recordWait,
+  recorderEventCount,
+  recorderMarkChildren,
+  reserveEvent,
+  startRecording,
+  stopRecording,
+} from "./recorder.js";
+
+describe("markChildren", () => {
+  test("groups a poll's kept iteration under the wait", () => {
+    startRecording();
+    const from = recorderEventCount();
+    recordFake({ fake: "resend", member: "lastEmailTo", args: [], durationMs: 1 });
+    const wait = recordWait({ description: "the mail arrives", attempts: 1, durationMs: 2, passed: true })!;
+    recorderMarkChildren(from, wait);
+    const events = stopRecording();
+
+    const fake = events.find((e) => e.kind === "fake")!;
+    expect(fake.parentSeq).toBe(wait);
+    // The wait never becomes its own child.
+    expect(events.find((e) => e.kind === "wait")!.parentSeq).toBeUndefined();
+  });
+
+  // A fake helper's `annotate(...)` child is that call's value, so it stays a
+  // child of the FAKE event even when the call happened inside a poll
+  // predicate. Overwriting it with the wait's seq made the wait itself render
+  // as the email, with the fake call showing raw JSON below it.
+  test("keeps an already-grouped event under its own parent", () => {
+    startRecording();
+    const from = recorderEventCount();
+    // The call's own slot is reserved first, exactly as invokeFakeHelper does.
+    const resv = reserveEvent();
+    const fakeSeq = recordFake(
+      { fake: "resend", member: "lastEmailTo", args: [], durationMs: 1 },
+      resv,
+    )!;
+    recordEmail({
+      parentSeq: fakeSeq,
+      annotation: true,
+      service: "resend",
+      op: "lastEmailTo",
+      message: { subject: "Ditt formulär" },
+      durationMs: 1,
+    });
+    const wait = recordWait({ description: "the mail arrives", attempts: 1, durationMs: 2, passed: true })!;
+    recorderMarkChildren(from, wait);
+    const events = stopRecording();
+
+    expect(events.find((e) => e.kind === "fake")!.parentSeq).toBe(wait);
+    expect(events.find((e) => e.kind === "email")!.parentSeq).toBe(fakeSeq);
+  });
+});

package/src/recorder.ts

@@ -26,7 +26,11 @@ export type TestEvent =
   | WaitEvent
   | FakeEvent
   | EnvEvent
-  | EmailEvent;
+  | EmailEvent
+  // Open `kind`, so it goes last: narrowing the union by a literal kind
+  // still reaches the specific member above, and this one carries anything
+  // a component describes in presentation terms.
+  | StepEvent;
 
 interface BaseEvent {
   /** Order of *start* within the test. Reserved when an op begins (see
@@ -469,6 +473,15 @@ export interface BrowserEvent extends BaseEvent {
   dy?: number;
   x?: number;
   y?: number;
+  /**
+   * rrweb node id of the element a settled `expect(locator)` step asserted on
+   * — the element's identity in this session's recording. Playwright calls an
+   * element below the fold visible, so the frame the step seeks to need not
+   * contain it; with this the viewer finds the node in the replayed DOM and
+   * scrolls it into view. Absent when the SDK couldn't measure it (an element
+   * in a frame, one rrweb hasn't serialized, a matcher whose subject is gone).
+   */
+  targetNodeId?: number;
   /** Screenshot image format. */
   format?: string;
   /** For `waitFor`: how many times the predicate was polled. */
@@ -637,13 +650,22 @@ class Recorder {
     }
   }
 
-  /** Stamp `parentSeq` onto every event at index >= `startIdx`. Used
-   *  by `ctx.poll` to group the kept iteration's events under the
-   *  resulting wait event. */
+  /** Stamp `parentSeq` onto every event at index >= `startIdx` that isn't
+   *  already grouped under something else. Used by `ctx.poll` to group the
+   *  kept iteration's events under the resulting wait event.
+   *
+   *  An event that already carries a `parentSeq` keeps it: it belongs to a
+   *  step *inside* this one, and re-parenting it here would flatten the
+   *  nesting the UI renders from. The case that made this matter is a fake
+   *  helper called in a poll predicate — its `annotate(...)` child is the
+   *  fake call's value, and stamping the wait's seq over it made the WAIT
+   *  render as an email/chat while the fake call showed raw JSON. Its
+   *  ancestor is still the wait, one level up through the fake event. */
   markChildren(startIdx: number, parentSeq: number): void {
     for (let i = startIdx; i < this.events.length; i++) {
       const ev = this.events[i]!;
       if (ev.seq === parentSeq) continue;
+      if (ev.parentSeq !== undefined) continue;
       ev.parentSeq = parentSeq;
     }
   }
@@ -819,6 +841,59 @@ export function recordEnv(
   return active() ? current!.push({ kind: "env", ...ev }, reservation) : undefined;
 }
 
+/**
+ * One block of step detail, in the dashboard's presentation vocabulary
+ * (`crates/control-plane/src/web/blocks.rs`, which owns the closed set).
+ * A server that predates a block type skips it rather than failing, so a
+ * newer SDK's step degrades to the blocks the server knows.
+ */
+export type StepBlock =
+  | { type: "text"; text: string }
+  | { type: "code"; code: string; lang?: string; label?: string }
+  | { type: "json"; value: unknown; label?: string }
+  | { type: "kv"; rows: { label: string; value?: string; error?: boolean }[] }
+  | { type: "table"; columns: string[]; rows: unknown[][] }
+  | { type: "htmlSandbox"; html: string; label?: string }
+  | { type: "chat"; messages: ChatBlockMessage[]; label?: string };
+
+/** One message of a `chat` block. */
+export interface ChatBlockMessage {
+  /** Who sent it. The transcript is drawn as the end user would see it, so
+   *  `self` (the end user's own messages) sits on the right and `other` on
+   *  the left. */
+  side?: "self" | "other";
+  text?: string;
+  /** Arrived in *this* step: drawn with an entrance animation. Only the
+   *  producer knows this, so only the producer sets it. */
+  new?: boolean;
+}
+
+/**
+ * A step that describes itself in presentation terms — a title plus an
+ * ordered list of blocks — instead of as one of the recorder's hard-coded
+ * kinds. This is the seam that lets a component ship a new kind of step
+ * with no server change: `kind` stays an opaque grouping/diff-alignment
+ * label and never decides how the step draws.
+ */
+export interface StepEvent extends BaseEvent {
+  /** Opaque. Groups the step and aligns it across runs; never matched on
+   *  to pick a renderer. */
+  kind: string;
+  /** The step's one-line summary in the timeline. */
+  title: string;
+  blocks?: StepBlock[];
+  status?: "passed" | "failed" | "error";
+  durationMs?: number;
+  error?: string;
+}
+
+export function recordStep(
+  ev: Omit<StepEvent, "seq" | "tOffsetMs">,
+  reservation?: EventReservation,
+): number | undefined {
+  return active() ? current!.push(ev, reservation) : undefined;
+}
+
 export function recordEmail(
   ev: Omit<EmailEvent, "seq" | "tOffsetMs" | "kind">,
   reservation?: EventReservation,