@specific.dev/spectest 0.14.0 → 0.16.0

package/src/components/email.ts

@@ -0,0 +1,398 @@
+// `email()` — a real SMTP server as a spectest service. The app under test
+// points its SMTP transport at `<key>:1025` and sends mail exactly as it
+// would in production; every message is captured instead of delivered.
+// Tests read the mailbox through typed helpers on `ctx.svc.<key>`
+// (`lastEmail`, `emails`, `clear`), each recorded as an `email` event on
+// the test timeline — single-message ops embed the full captured message
+// (HTML body included) so the dashboard renders the actual email the test
+// asserted against, and returns come back inspect-wrapped so
+// `expect(mail.subject)` links under the step. To wait for a message to
+// *arrive*, use the standard `ctx.poll` with `lastEmail` as the predicate
+// (it returns `undefined` while the mailbox is empty); the winning
+// iteration's `email` event survives poll truncation, so the message still
+// renders nested under the wait step.
+//
+// Captured mail lives in the server's process memory, so it snapshots and
+// forks with the rest of the environment: a `dependsOn` child inherits the
+// parent's mailbox, sibling forks never see each other's messages — the
+// same isolation contract as fake state.
+
+import type { ServiceDefinition } from "../index.js";
+import {
+  pauseRecording,
+  recordEmail,
+  reserveEvent,
+  resumeRecording,
+  truncateUtf8,
+  type EmailEventMessage,
+  type EmailEventSummary,
+} from "../recorder.js";
+import { wrap } from "../inspect.js";
+import type { Wrapped } from "../inspect.js";
+
+const DEFAULT_IMAGE = "axllent/mailpit:v1.30";
+const SMTP_PORT = 1025;
+const API_PORT = 8025;
+
+export interface EmailOptions {
+  /** TCP port the SMTP listener binds. Default `1025`. */
+  smtpPort?: number;
+  /** Override the underlying mail-server image. */
+  image?: string;
+  /** Extra environment variables forwarded to the container. */
+  env?: Record<string, string>;
+}
+
+export interface EmailAttachment {
+  filename: string;
+  contentType: string;
+  /** Decoded size in bytes. */
+  size: number;
+}
+
+/** A fully captured email, as returned by `lastEmail`. */
+export interface EmailMessage {
+  id: string;
+  /** Sender address. */
+  from: string;
+  /** Recipient addresses. */
+  to: string[];
+  cc: string[];
+  bcc: string[];
+  subject: string;
+  /** Message date, ISO-formatted. */
+  date: string;
+  /** Plain-text body ("" when the mail had none). */
+  text: string;
+  /** HTML body ("" when the mail had none). */
+  html: string;
+  attachments: EmailAttachment[];
+}
+
+/** A mailbox-listing row, as returned by `emails()`. */
+export interface EmailSummary {
+  id: string;
+  from: string;
+  to: string[];
+  subject: string;
+  /** Plain-text preview of the body. */
+  snippet: string;
+  date: string;
+  /** Attachment count. */
+  attachments: number;
+}
+
+/** Filter for `emails()` listings. All given fields must match. */
+export interface EmailMatch {
+  /** A recipient address, compared case-insensitively. */
+  to?: string;
+  /** The sender address, compared case-insensitively. */
+  from?: string;
+  /** Subject substring (string) or pattern (RegExp). */
+  subject?: string | RegExp;
+}
+
+/** Helpers an `email(...)` service exposes on `ctx.svc.<name>`. */
+export interface EmailHelpers {
+  /**
+   * The newest captured message, in full (or `undefined` while the mailbox
+   * is empty) — which makes it the natural `ctx.poll` predicate for waiting
+   * on delivery; assert on its fields once it returns:
+   *
+   * ```ts
+   * const mail = await ctx.poll("welcome email", () => ctx.svc.email.lastEmail());
+   * expect(mail.to).toContain("alice@example.com");
+   * ```
+   *
+   * To wait for a *specific* message when several are in flight, check
+   * fields inside the predicate:
+   *
+   * ```ts
+   * const mail = await ctx.poll("reset email", async () => {
+   *   const m = await ctx.svc.email.lastEmail();
+   *   return m && /reset/i.test(m.unwrap().subject) ? m : undefined;
+   * });
+   * ```
+   */
+  lastEmail(): Promise<Wrapped<EmailMessage> | undefined>;
+  /** All captured messages matching `match`, newest first. */
+  emails(match?: EmailMatch): Promise<Wrapped<EmailSummary[]>>;
+  /** Delete every captured message. */
+  clear(): Promise<void>;
+}
+
+/**
+ * A capture-everything SMTP server. Drop into `environment.services`:
+ *
+ * ```ts
+ * services: {
+ *   email: email(),
+ *   app: {
+ *     ...,
+ *     env: { SMTP_HOST: "email", SMTP_PORT: "1025" },
+ *   },
+ * }
+ * ```
+ *
+ * The app sends real SMTP (any or no credentials are accepted, no TLS
+ * required); tests assert on what arrived, using the standard `ctx.poll`
+ * to wait for delivery:
+ *
+ * ```ts
+ * const mail = await ctx.poll("welcome email", () => ctx.svc.email.lastEmail());
+ * expect(mail.to).toContain("alice@example.com");
+ * expect(mail.subject).toBe("Welcome!");
+ * expect(mail.html).toContain("Alice");
+ * ```
+ */
+export function email(opts: EmailOptions = {}) {
+  const smtpPort = opts.smtpPort ?? SMTP_PORT;
+  const reference = opts.image ?? DEFAULT_IMAGE;
+  // `satisfies` (not a return-type annotation) so the helpers factory's
+  // literal return type flows through to `ctx.svc.<name>` — see the note
+  // in postgres.ts.
+  return {
+    image: { type: "registry" as const, reference },
+    env: {
+      // Accept whatever AUTH the app offers (including none, over
+      // plaintext), so an app configured with production-style SMTP
+      // credentials runs unchanged against the capture server.
+      MP_SMTP_AUTH_ACCEPT_ANY: "1",
+      MP_SMTP_AUTH_ALLOW_INSECURE: "1",
+      ...(smtpPort !== SMTP_PORT
+        ? { MP_SMTP_BIND_ADDR: `0.0.0.0:${smtpPort}` }
+        : {}),
+      ...(opts.env ?? {}),
+    },
+    ports: [smtpPort, API_PORT],
+    readyCheck: {
+      type: "http" as const,
+      port: API_PORT,
+      path: "/livez",
+      timeoutSecs: 60,
+    },
+    helpers: ({ name }: { name: string }): EmailHelpers =>
+      buildHelpers(name, `http://${name}:${API_PORT}`),
+  } satisfies ServiceDefinition<EmailHelpers>;
+}
+
+/**
+ * Build the mailbox helpers for an `email()` service, by its services-map
+ * key. For components that expose a shared mailbox on their own handle
+ * (e.g. `supabase({ mail: true })` surfacing `ctx.svc.supabase.mail`) —
+ * the recorded `email` events carry `service` so the dashboard attributes
+ * them to the right container.
+ */
+export function emailHelpers(service: string, apiPort: number = API_PORT): EmailHelpers {
+  return buildHelpers(service, `http://${service}:${apiPort}`);
+}
+
+function buildHelpers(service: string, base: string): EmailHelpers {
+  return {
+    async lastEmail() {
+      return instrumented(service, "lastEmail", undefined, async () => {
+        const [hit] = await listAll(base); // newest first
+        if (!hit) return { value: undefined, count: 0 };
+        const value = await getMessage(base, hit.id);
+        return { value, message: toEventMessage(value) };
+      });
+    },
+
+    emails(match) {
+      return instrumented(service, "emails", describeMatch(match), async () => {
+        const value = (await listAll(base)).filter((s) => matches(s, match));
+        return {
+          value,
+          count: value.length,
+          messages: value.slice(0, EVENT_LIST_CAP).map(toEventSummary),
+        };
+      });
+    },
+
+    async clear() {
+      await instrumented(service, "clear", undefined, async () => {
+        await api(base, "/api/v1/messages", { method: "DELETE" });
+        return { value: undefined };
+      });
+    },
+  };
+}
+
+/** Newest-first mailbox listing rows returned by `emails()` are capped at
+ *  this many entries on the recorded event (the return value itself is
+ *  never truncated). */
+const EVENT_LIST_CAP = 50;
+
+/** Run one helper op: reserve a timeline slot up front, record an `email`
+ *  event when the op settles, and hand the value back inspect-wrapped
+ *  against that event so assertions on it nest under the step. */
+async function instrumented<T>(
+  service: string,
+  op: string,
+  query: string | undefined,
+  body: () => Promise<{
+    value: T;
+    message?: EmailEventMessage;
+    messages?: EmailEventSummary[];
+    count?: number;
+  }>,
+): Promise<Wrapped<T>> {
+  const started = Date.now();
+  const resv = reserveEvent();
+  try {
+    const { value, message, messages, count } = await body();
+    const seq = recordEmail(
+      { service, op, query, message, messages, count, durationMs: Date.now() - started },
+      resv,
+    );
+    return wrap(value, seq) as Wrapped<T>;
+  } catch (err) {
+    const e = err as Error;
+    recordEmail(
+      {
+        service,
+        op,
+        query,
+        durationMs: Date.now() - started,
+        error: e?.message ?? String(err),
+      },
+      resv,
+    );
+    throw err;
+  }
+}
+
+/** Query the mail server's HTTP API. Recording is paused around the fetch
+ *  so these internal polls don't land as `http` events on the timeline —
+ *  the helper records one consolidated `email` event instead. */
+async function api(base: string, path: string, init?: RequestInit): Promise<unknown> {
+  pauseRecording();
+  try {
+    const res = await fetch(`${base}${path}`, init);
+    if (!res.ok) {
+      throw new Error(`email server API ${path} failed: HTTP ${res.status}`);
+    }
+    const text = await res.text();
+    if (text === "") return undefined;
+    try {
+      return JSON.parse(text);
+    } catch {
+      // Mutating endpoints reply with a plain-text acknowledgement.
+      return text;
+    }
+  } finally {
+    resumeRecording();
+  }
+}
+
+interface RawAddress {
+  Name?: string;
+  Address?: string;
+}
+
+function addresses(v: unknown): string[] {
+  if (!Array.isArray(v)) return [];
+  return v.map((a) => (a as RawAddress)?.Address ?? "").filter((a) => a !== "");
+}
+
+async function listAll(base: string): Promise<EmailSummary[]> {
+  const data = (await api(base, "/api/v1/messages?limit=500")) as {
+    messages?: unknown[];
+  };
+  return (data?.messages ?? []).map((raw) => {
+    const m = raw as Record<string, unknown>;
+    return {
+      id: (m.ID as string) ?? "",
+      from: (m.From as RawAddress)?.Address ?? "",
+      to: addresses(m.To),
+      subject: (m.Subject as string) ?? "",
+      snippet: (m.Snippet as string) ?? "",
+      date: (m.Created as string) ?? "",
+      attachments: (m.Attachments as number) ?? 0,
+    };
+  });
+}
+
+async function getMessage(base: string, id: string): Promise<EmailMessage> {
+  const m = (await api(base, `/api/v1/message/${encodeURIComponent(id)}`)) as Record<
+    string,
+    unknown
+  >;
+  return {
+    id: (m.ID as string) ?? "",
+    from: (m.From as RawAddress)?.Address ?? "",
+    to: addresses(m.To),
+    cc: addresses(m.Cc),
+    bcc: addresses(m.Bcc),
+    subject: (m.Subject as string) ?? "",
+    date: (m.Date as string) ?? "",
+    text: (m.Text as string) ?? "",
+    html: (m.HTML as string) ?? "",
+    attachments: (Array.isArray(m.Attachments) ? m.Attachments : []).map((raw) => {
+      const a = raw as Record<string, unknown>;
+      return {
+        filename: (a.FileName as string) ?? "",
+        contentType: (a.ContentType as string) ?? "",
+        size: (a.Size as number) ?? 0,
+      };
+    }),
+  };
+}
+
+function matches(s: EmailSummary, match?: EmailMatch): boolean {
+  if (!match) return true;
+  if (match.to !== undefined) {
+    const want = match.to.toLowerCase();
+    if (!s.to.some((a) => a.toLowerCase() === want)) return false;
+  }
+  if (match.from !== undefined && s.from.toLowerCase() !== match.from.toLowerCase()) {
+    return false;
+  }
+  if (match.subject !== undefined) {
+    if (typeof match.subject === "string") {
+      if (!s.subject.includes(match.subject)) return false;
+    } else if (!match.subject.test(s.subject)) {
+      return false;
+    }
+  }
+  return true;
+}
+
+function describeMatch(match?: EmailMatch): string | undefined {
+  if (!match) return undefined;
+  const parts: string[] = [];
+  if (match.to !== undefined) parts.push(`to ${match.to}`);
+  if (match.from !== undefined) parts.push(`from ${match.from}`);
+  if (match.subject !== undefined) parts.push(`subject ${String(match.subject)}`);
+  return parts.length > 0 ? parts.join(", ") : undefined;
+}
+
+function toEventSummary(s: EmailSummary): EmailEventSummary {
+  return {
+    from: s.from,
+    to: s.to,
+    subject: s.subject,
+    snippet: s.snippet,
+    date: s.date,
+  };
+}
+
+function toEventMessage(m: EmailMessage): EmailEventMessage {
+  const html = truncateUtf8(m.html);
+  const text = truncateUtf8(m.text);
+  return {
+    from: m.from,
+    to: m.to,
+    ...(m.cc.length > 0 ? { cc: m.cc } : {}),
+    ...(m.bcc.length > 0 ? { bcc: m.bcc } : {}),
+    subject: m.subject,
+    date: m.date,
+    ...(m.html !== ""
+      ? { html: html.value, ...(html.truncated ? { htmlTruncated: true } : {}) }
+      : {}),
+    ...(m.text !== ""
+      ? { text: text.value, ...(text.truncated ? { textTruncated: true } : {}) }
+      : {}),
+    ...(m.attachments.length > 0 ? { attachments: m.attachments } : {}),
+  };
+}

package/src/components/index.ts

@@ -37,6 +37,15 @@ export {
   type SupabaseHelpers,
   type SupabaseStack,
 } from "./supabase.js";
+export {
+  email,
+  type EmailOptions,
+  type EmailHelpers,
+  type EmailMessage,
+  type EmailSummary,
+  type EmailMatch,
+  type EmailAttachment,
+} from "./email.js";
 export {
   replayFake,
   type ReplayFakeOptions,