@specific.dev/spectest 0.13.0 → 0.15.0

package/src/recorder.ts

@@ -25,7 +25,8 @@ export type TestEvent =
   | TerminalStepEvent
   | WaitEvent
   | FakeEvent
-  | EnvEvent;
+  | EnvEvent
+  | EmailEvent;
 
 interface BaseEvent {
   /** Order of *start* within the test. Reserved when an op begins (see
@@ -275,6 +276,69 @@ export interface FakeEvent extends BaseEvent {
   error?: 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
+ * can render the actual email a test asserted against.
+ */
+export interface EmailEventMessage {
+  /** Sender address. */
+  from?: string;
+  /** Recipient addresses. */
+  to?: string[];
+  cc?: string[];
+  bcc?: string[];
+  subject?: string;
+  /** RFC date of the message, ISO-formatted. */
+  date?: string;
+  /** HTML body (truncated to the output cap). */
+  html?: string;
+  htmlTruncated?: boolean;
+  /** Plain-text body (truncated to the output cap). */
+  text?: string;
+  textTruncated?: boolean;
+  attachments?: { filename: string; contentType: string; size: number }[];
+}
+
+/** One row of a mailbox listing embedded on an {@link EmailEvent}. */
+export interface EmailEventSummary {
+  from?: string;
+  to?: string[];
+  subject?: string;
+  /** Plain-text preview of the body. */
+  snippet?: string;
+  date?: string;
+}
+
+/**
+ * One call to an email service's helpers (`ctx.svc.<name>.lastEmail(...)`
+ * etc.). Single-message ops embed the full captured message — including its
+ * HTML body — so timelines can render the email itself; listing ops embed
+ * compact summaries. The return value is `wrap()`ped against this event's
+ * seq, so `expect(...)` on it nests under this step (same mechanism as
+ * http/db/fake). Inside a `ctx.poll` predicate the event ride-alongs with
+ * the poll's iteration events: failed iterations get truncated, the winning
+ * one survives as a child of the `wait` event.
+ */
+export interface EmailEvent extends BaseEvent {
+  kind: "email";
+  /** Service key of the mail server (`ctx.svc.<service>`). */
+  service: string;
+  /** Helper called, e.g. `"lastEmail"`. */
+  op: string;
+  /** Human-readable match criteria, e.g. `to alice@example.com`. */
+  query?: string;
+  /** Number of matching messages (listing ops / mailbox size on error). */
+  count?: number;
+  /** The captured message (single-message ops). */
+  message?: EmailEventMessage;
+  /** Message summaries (listing ops). */
+  messages?: EmailEventSummary[];
+  durationMs: number;
+  /** Set if the op threw (e.g. the mail server's query API failed). */
+  error?: string;
+}
+
 /**
  * A runtime mutation of the environment — `ctx.startService` /
  * `ctx.stopService` / `ctx.dnsName`, whether called from a test or from a
@@ -663,6 +727,13 @@ export function recordEnv(
   return active() ? current!.push({ kind: "env", ...ev }, reservation) : undefined;
 }
 
+export function recordEmail(
+  ev: Omit<EmailEvent, "seq" | "tOffsetMs" | "kind">,
+  reservation?: EventReservation,
+): number | undefined {
+  return active() ? current!.push({ kind: "email", ...ev }, reservation) : undefined;
+}
+
 /**
  * Recorded once per `ctx.poll(...)` call. Stands in for the suppressed
  * intermediate iterations and gives downstream tagged values