@specific.dev/spectest 0.38.0 → 0.41.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/expo.ts

@@ -0,0 +1,167 @@
+// `expo()` — a ready-to-use service for an Expo / React Native app rendered
+// to the web, built for `ctx.mobile(...)`.
+//
+// Serving model: STATIC EXPORT. The image runs `expo export -p web` at build
+// time (producing `dist/`) and the container just serves those static files
+// with a tiny Node server. No Metro at runtime — so the ready-check is fast
+// and deterministic and the bundle rides the image-layer cache, instead of
+// paying a non-deterministic first-request bundle on every boot.
+//
+// The service's `helpers` factory returns a `MobileApp` handle (the resolved
+// in-VM URL), so a test drives it with `ctx.mobile(ctx.svc.app)` — no URL, no
+// `navigate`.
+
+import type { ServiceDefinition } from "../index.js";
+import { mobileApp } from "../mobile.js";
+import type { MobileApp } from "../mobile.js";
+
+export interface ExpoOptions {
+  /** Port the static server listens on. Default `8081`. */
+  port?: number;
+  /**
+   * App directory inside the project, relative to the build context root.
+   * Default `"."` (the project root is the Expo app). Set this when the
+   * Expo app lives in a subdirectory of a larger repo.
+   */
+  appDir?: string;
+  /** Node base image tag. Default `"20-bookworm-slim"`. */
+  nodeVersion?: string;
+  /** Output dir `expo export` writes to (relative to the app dir). Default `"dist"`. */
+  outputDir?: string;
+  /**
+   * Extra environment variables. `EXPO_PUBLIC_*` keys are additionally baked
+   * into the image build so `expo export` inlines them into the bundle —
+   * Expo resolves them at export time, so runtime-only container env would be
+   * too late. Everything else applies to the static-server container only.
+   */
+  env?: Record<string, string>;
+  /**
+   * Script installed before each `ctx.mobile(ctx.svc.app)` session's first
+   * navigation, so it runs ahead of the app bundle on the very first document
+   * — no relaunch. Declare shims here once (reduced-motion, `Notification`, …)
+   * instead of calling them at the top of every test.
+   */
+  initScript?: string;
+}
+
+/** The handle `expo()` exposes on `ctx.svc.<name>` — a {@link MobileApp}. */
+export type ExpoHelpers = MobileApp;
+
+// A dependency-free static file server with SPA fallback. Bind-mounted into
+// the container (so it isn't baked into the image build) and run as the
+// container command. Serves `dist/`, falling back to index.html for client
+// routes. Embedded as a file rather than `npx serve` so the container needs
+// no extra install at runtime.
+const STATIC_SERVER = String.raw`import { createServer } from "node:http";
+import { stat, readFile } from "node:fs/promises";
+import { join, extname, normalize, resolve } from "node:path";
+
+const root = resolve(process.argv[2] || "dist");
+const port = Number(process.argv[3] || 8081);
+const TYPES = {
+  ".html": "text/html; charset=utf-8",
+  ".js": "text/javascript; charset=utf-8",
+  ".mjs": "text/javascript; charset=utf-8",
+  ".css": "text/css; charset=utf-8",
+  ".json": "application/json; charset=utf-8",
+  ".map": "application/json; charset=utf-8",
+  ".png": "image/png", ".jpg": "image/jpeg", ".jpeg": "image/jpeg",
+  ".gif": "image/gif", ".svg": "image/svg+xml", ".ico": "image/x-icon",
+  ".webp": "image/webp", ".woff": "font/woff", ".woff2": "font/woff2",
+  ".ttf": "font/ttf", ".otf": "font/otf", ".wasm": "application/wasm",
+};
+
+async function send(res, fp) {
+  const body = await readFile(fp);
+  res.writeHead(200, { "content-type": TYPES[extname(fp)] || "application/octet-stream" });
+  res.end(body);
+}
+
+createServer(async (req, res) => {
+  try {
+    let p = decodeURIComponent((req.url || "/").split("?")[0]);
+    if (p.endsWith("/")) p += "index.html";
+    let fp = normalize(join(root, p));
+    if (!fp.startsWith(root)) { res.writeHead(403); return res.end("forbidden"); }
+    try {
+      const s = await stat(fp);
+      if (s.isDirectory()) fp = join(fp, "index.html");
+      await send(res, fp);
+    } catch {
+      // SPA fallback: unknown path → index.html.
+      await send(res, join(root, "index.html"));
+    }
+  } catch (e) {
+    res.writeHead(500);
+    res.end(String(e));
+  }
+}).listen(port, "0.0.0.0", () => console.log("[expo-static] serving " + root + " on :" + port));
+`;
+
+/**
+ * A ready-to-use Expo (web) service. Drop into `environment.services` and
+ * drive it with `ctx.mobile`:
+ *
+ * ```ts
+ * services: { app: expo() }
+ * // in a test:
+ * const m = await ctx.mobile(ctx.svc.app);
+ * await m.getByText("Sign in").tap();
+ * ```
+ *
+ * The web build is produced once at image-build time; the container serves
+ * the static bundle. `ctx.svc.<key>` is the app's `MobileApp` handle.
+ */
+export function expo(opts: ExpoOptions = {}) {
+  const port = opts.port ?? 8081;
+  const appDir = opts.appDir ?? ".";
+  const nodeVersion = opts.nodeVersion ?? "20-bookworm-slim";
+  const outputDir = opts.outputDir ?? "dist";
+
+  // Expo inlines EXPO_PUBLIC_* variables into the bundle at `expo export`
+  // time, so they must exist during the image build — runtime container env
+  // is too late. Bake them as ENV lines placed after `npm install` (an env
+  // edit re-exports without re-installing) and before the export RUN. They
+  // remain in `env` too, so server-side reads in the container agree.
+  const publicEnv = Object.entries(opts.env ?? {}).filter(([k]) =>
+    k.startsWith("EXPO_PUBLIC_"),
+  );
+  for (const [k, v] of publicEnv) {
+    if (/[\r\n]/.test(v)) {
+      throw new Error(`expo(): env ${k} must not contain newlines (baked into the Dockerfile)`);
+    }
+  }
+  const publicEnvLines = publicEnv
+    .map(([k, v]) => `ENV ${k}="${v.replaceAll("\\", "\\\\").replaceAll('"', '\\"')}"`)
+    .join("\n");
+
+  // CI=1 keeps `expo export` non-interactive. Static export resolves the web
+  // bundle deterministically into `outputDir`.
+  const dockerfile = `FROM node:${nodeVersion}
+WORKDIR /app
+ENV CI=1
+COPY ${appDir}/ ./
+RUN npm install
+${publicEnvLines ? `${publicEnvLines}\n` : ""}RUN npx expo export --platform web --output-dir ${outputDir}
+`;
+
+  return {
+    image: { type: "dockerfile", content: dockerfile },
+    files: [
+      { path: "/spectest-expo-serve.mjs", content: STATIC_SERVER },
+    ],
+    command: `node /spectest-expo-serve.mjs /app/${outputDir} ${port}`,
+    env: { ...(opts.env ?? {}) },
+    ports: [port],
+    readyCheck: { type: "http" as const, port, path: "/", timeoutSecs: 60 },
+    helpers: ({ name }: { name: string }): ExpoHelpers => {
+      // Use the multi-label `<name>.internal` alias (the daemon registers it
+      // for every service) rather than the bare single-label `<name>`:
+      // headless Chromium mishandles a single-label http navigation (it tries
+      // TLS → net::ERR_SSL_PROTOCOL_ERROR), while a dotted host navigates as
+      // plain HTTP. Node-side `fetch` is unaffected, but the mobile session
+      // drives a real browser, so the URL must be browser-navigable.
+      return mobileApp(`http://${name}.internal:${port}`, opts.initScript);
+    },
+  } satisfies ServiceDefinition<ExpoHelpers>;
+}

package/src/components/index.ts

@@ -0,0 +1,81 @@
+// Reusable, pre-built service definitions for common dependencies.
+//
+// Each component returns a fully-formed `ServiceDefinition` ready to
+// drop into an environment's `services` map. Beyond the container
+// boilerplate (image, env vars, volumes, ready checks) a component may
+// also ship a `client` factory — that's what surfaces convenience
+// handles like `ctx.svc.db.client` (a Bun SQL pool for `postgres(...)`).
+
+export {
+  postgres,
+  type PostgresOptions,
+  type PostgresHelpers,
+} from "./postgres.js";
+export {
+  s3,
+  type S3Options,
+  type S3Helpers,
+} from "./s3.js";
+// `SQL` / `SqlClient` now live in the core SDK (`@specific.dev/spectest`),
+// next to `expect` and `fetch` — re-exported here so existing
+// `from ".../components"` imports keep resolving.
+export { SQL, type SqlClient, type SqlOptions } from "../sql.js";
+export {
+  k3s,
+  type K3sOptions,
+  type K3sHelpers,
+  type K3sClient,
+  type TaggedObjectApi,
+  type KubernetesObjectRef,
+  type ApplyOptions,
+  type RolloutTarget,
+  type WaitOptions,
+  type LogsOptions,
+  // Re-exported from `@kubernetes/client-node` so a project can type its
+  // custom resources (`interface Cluster extends KubernetesObject { … }`)
+  // without depending on the kubernetes client directly.
+  type KubernetesObject,
+  type KubernetesListObject,
+} from "./k3s.js";
+export {
+  expo,
+  type ExpoOptions,
+  type ExpoHelpers,
+} from "./expo.js";
+export {
+  supabase,
+  type SupabaseOptions,
+  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 {
+  aws,
+  type AwsOptions,
+  type LambdaOptions,
+} from "./aws.js";
+export {
+  replayFake,
+  type ReplayFakeOptions,
+  type ReplayMatch,
+  type InjectRule,
+  type InjectMatch,
+  type StringMatch,
+  type SignConfig,
+  type AwsSigV4Sign,
+  type ReplayHelpers,
+  type ReplaySummary,
+  type Cassette,
+  type CassetteInteraction,
+  type CassetteRequest,
+  type CassetteResponse,
+  type CassetteState,
+} from "./replayFake.js";