slicetest 0.3.0 → 0.4.0

package/dist/drivers/driver.d.ts

@@ -54,6 +54,8 @@ export interface Engine {
     name: string;
     /** Container image used when no `db.url` is given. */
     defaultImage: string;
+    /** Runs in-process (SQLite): no container runtime needed. */
+    local?: boolean;
     startContainer(image: string, reuse: boolean): Promise<{
         url: string;
         stop(): Promise<unknown>;

package/dist/drivers/index.js

@@ -10,5 +10,7 @@ export async function engineFor(opts) {
         });
         return mod.mysqlEngine;
     }
+    if (opts.db.engine === "sqlite")
+        return (await import("./sqlite.js")).sqliteEngine;
     return postgres;
 }

package/dist/drivers/sqlite.d.ts

@@ -0,0 +1,23 @@
+import type { Driver, Engine, Row, Table } from "./driver.js";
+/** `sqlite:///tmp/a.db` → `/tmp/a.db`; `sqlite:///C:/x/a.db` → `C:/x/a.db`. Plain paths pass through. */
+export declare function sqlitePath(url: string): string;
+export declare function sqliteUrl(file: string): string;
+export declare class SqliteDriver implements Driver {
+    private readonly db;
+    private constructor();
+    static connect(url: string): Promise<SqliteDriver>;
+    query<T extends Row = Row>(sql: string, params?: unknown[]): Promise<T[]>;
+    queryAll(sqls: string[]): Promise<Row[][]>;
+    exec(script: string): Promise<void>;
+    ident(name: string): string;
+    column(name: string): string;
+    param(n: number): string;
+    inList(column: string, values: unknown[], params: unknown[]): string;
+    /** SQLite has one schema per file (`main`), so `schemas` doesn't apply. */
+    listTables(_schemas: string[], keep: string[]): Promise<Table[]>;
+    /** DELETE, then forget AUTOINCREMENT counters. Foreign keys are off for this connection only. */
+    truncate(tables: Table[]): Promise<void>;
+    insert(table: string, row: Row): Promise<Row[]>;
+    close(): Promise<void>;
+}
+export declare const sqliteEngine: Engine;

package/dist/drivers/sqlite.js

@@ -0,0 +1,203 @@
+import { existsSync } from "node:fs";
+import { mkdir, mkdtemp, open, readdir, rm } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+let loaded;
+/** `node:sqlite` warns that it's experimental on every import; that's noise in test output. */
+function load() {
+    return (loaded ??= (async () => {
+        const emit = process.emitWarning;
+        process.emitWarning = ((warning, ...rest) => {
+            if (String(typeof warning === "string" ? warning : warning.message).includes("SQLite"))
+                return;
+            emit.call(process, warning, ...rest);
+        });
+        try {
+            return await import("node:sqlite");
+        }
+        catch {
+            throw new Error(`slicetest: db.engine "sqlite" needs Node.js 22.5 or later (node:sqlite); this is ${process.versions.node}`);
+        }
+        finally {
+            process.emitWarning = emit;
+        }
+    })());
+}
+/** `sqlite:///tmp/a.db` → `/tmp/a.db`; `sqlite:///C:/x/a.db` → `C:/x/a.db`. Plain paths pass through. */
+export function sqlitePath(url) {
+    if (!url.startsWith("sqlite:"))
+        return url;
+    const p = decodeURIComponent(url.replace(/^sqlite:(\/\/)?/, "").replace(/[?#].*$/, ""));
+    return /^\/[a-zA-Z]:[\\/]/.test(p) ? p.slice(1) : p;
+}
+export function sqliteUrl(file) {
+    const p = path.resolve(file).replace(/\\/g, "/");
+    return `sqlite://${p.startsWith("/") ? "" : "/"}${p}`;
+}
+/** Values node:sqlite can't bind are stored the way an app would store them. */
+function bind(v) {
+    if (typeof v === "boolean")
+        return v ? 1 : 0;
+    if (v instanceof Date)
+        return v.toISOString();
+    if (v !== null && typeof v === "object" && !(v instanceof Uint8Array))
+        return JSON.stringify(v);
+    return v === undefined ? null : v;
+}
+async function openDb(file) {
+    const { DatabaseSync } = await load();
+    const db = new DatabaseSync(file);
+    // The app may be writing; wait for its lock instead of failing with SQLITE_BUSY.
+    db.exec("PRAGMA busy_timeout = 5000");
+    return db;
+}
+export class SqliteDriver {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    static async connect(url) {
+        return new SqliteDriver(await openDb(sqlitePath(url)));
+    }
+    async query(sql, params = []) {
+        const stmt = this.db.prepare(sql);
+        const values = params.map(bind);
+        // Rows come with a null prototype; plain objects compare and print as expected.
+        return stmt.columns().length === 0 ? (stmt.run(...values), []) : stmt.all(...values).map((r) => ({ ...r }));
+    }
+    async queryAll(sqls) {
+        return Promise.all(sqls.map((s) => this.query(s)));
+    }
+    async exec(script) {
+        this.db.exec(script);
+    }
+    ident(name) {
+        return name
+            .split(".")
+            .map((part) => this.column(part))
+            .join(".");
+    }
+    column(name) {
+        return `"${name.replace(/"/g, '""')}"`;
+    }
+    param(n) {
+        return `?${n}`;
+    }
+    inList(column, values, params) {
+        if (values.length === 0)
+            return "0";
+        const start = params.length;
+        params.push(...values);
+        return `${this.ident(column)} IN (${values.map((_, i) => `?${start + i + 1}`).join(", ")})`;
+    }
+    /** SQLite has one schema per file (`main`), so `schemas` doesn't apply. */
+    async listTables(_schemas, keep) {
+        const rows = await this.query(`SELECT m.name AS name,
+              (SELECT group_concat(name, char(10)) FROM (SELECT name FROM pragma_table_info(m.name) WHERE pk > 0 ORDER BY pk)) AS key
+         FROM sqlite_master m
+        WHERE m.type = 'table' AND m.name NOT LIKE 'sqlite\\_%' ESCAPE '\\'
+        ORDER BY 1`);
+        return rows
+            .filter((r) => !keep.includes(r.name) && !keep.includes(`main.${r.name}`))
+            .map((r) => ({ name: r.name, quoted: this.ident(r.name), key: r.key ? r.key.split("\n") : [] }));
+    }
+    /** DELETE, then forget AUTOINCREMENT counters. Foreign keys are off for this connection only. */
+    async truncate(tables) {
+        if (tables.length === 0)
+            return;
+        const sequence = (await this.query("SELECT 1 FROM sqlite_master WHERE name = 'sqlite_sequence'")).length > 0;
+        const names = tables.map((t) => `'${t.name.replace(/'/g, "''")}'`).join(", ");
+        this.db.exec(`PRAGMA foreign_keys = OFF; BEGIN IMMEDIATE; ${tables.map((t) => `DELETE FROM ${t.quoted};`).join(" ")}` +
+            `${sequence ? ` DELETE FROM sqlite_sequence WHERE name IN (${names});` : ""} COMMIT; PRAGMA foreign_keys = ON;`);
+    }
+    async insert(table, row) {
+        const cols = Object.keys(row);
+        const sql = cols.length === 0
+            ? `INSERT INTO ${this.ident(table)} DEFAULT VALUES RETURNING *`
+            : `INSERT INTO ${this.ident(table)} (${cols.map((c) => this.column(c)).join(", ")}) VALUES (${cols.map((_, i) => `?${i + 1}`).join(", ")}) RETURNING *`;
+        return this.query(sql, Object.values(row));
+    }
+    async close() {
+        this.db.close();
+    }
+}
+class SqliteAdmin {
+    dir;
+    constructor(dir) {
+        this.dir = dir;
+    }
+    #file(name) {
+        return path.join(this.dir, `${name}.db`);
+    }
+    async databases(prefix) {
+        return (await readdir(this.dir)).filter((f) => f.endsWith(".db") && f.startsWith(prefix)).map((f) => f.slice(0, -3));
+    }
+    async create(name) {
+        const db = await openDb(this.#file(name));
+        // Persisted in the file: the app and slicetest can then read and write at the same time.
+        db.exec("PRAGMA journal_mode = WAL");
+        db.close();
+    }
+    async clone(template, name) {
+        const db = await openDb(this.#file(template));
+        try {
+            db.prepare("VACUUM INTO ?").run(this.#file(name));
+        }
+        finally {
+            db.close();
+        }
+        const copy = await openDb(this.#file(name));
+        copy.exec("PRAGMA journal_mode = WAL");
+        copy.close();
+    }
+    async drop(name) {
+        for (const suffix of ["", "-wal", "-shm", "-journal"])
+            await rm(this.#file(name) + suffix, { force: true });
+    }
+    /** A lock file, for runs sharing the directory (with `reuse`). */
+    async withLock(key, fn) {
+        const lock = path.join(this.dir, `${key}.lock`);
+        const deadline = Date.now() + 120_000;
+        for (;;) {
+            try {
+                await (await open(lock, "wx")).close();
+                break;
+            }
+            catch (e) {
+                if (e.code !== "EEXIST" || Date.now() > deadline)
+                    throw e;
+                await new Promise((r) => setTimeout(r, 100));
+            }
+        }
+        try {
+            return await fn();
+        }
+        finally {
+            await rm(lock, { force: true });
+        }
+    }
+    urlFor(name) {
+        return sqliteUrl(this.#file(name));
+    }
+    async close() { }
+}
+export const sqliteEngine = {
+    name: "sqlite",
+    defaultImage: "",
+    local: true,
+    /** No container: a directory of database files, kept between runs with `reuse`. */
+    async startContainer(_image, reuse) {
+        await load();
+        const dir = reuse ? path.join(os.tmpdir(), "slicetest-sqlite") : await mkdtemp(path.join(os.tmpdir(), "slicetest-sqlite-"));
+        await mkdir(dir, { recursive: true });
+        return { url: sqliteUrl(dir), stop: () => rm(dir, { recursive: true, force: true }) };
+    },
+    async admin(url) {
+        const dir = sqlitePath(url);
+        if (!existsSync(dir))
+            await mkdir(dir, { recursive: true });
+        return new SqliteAdmin(dir);
+    },
+    driver: (url) => SqliteDriver.connect(url),
+    atlasUrl: (url) => `sqlite://${sqlitePath(url)}`,
+};

package/dist/global-setup.js

@@ -4,6 +4,7 @@ import { mkdir, mkdtemp, readdir, readFile, rm, stat, writeFile } from "node:fs/
 import os from "node:os";
 import path from "node:path";
 import { promisify } from "node:util";
+import { annotation, appendSummary, failureAnnotations, failureSummary, onGitHub, repoPath, yamlFailures } from "./ci.js";
 import { configureContainerRuntime } from "./container-runtime.js";
 import { engineFor } from "./drivers/index.js";
 import { coverageCacheFile } from "./gen.js";
@@ -21,7 +22,8 @@ export default async function setup(project) {
         adminUrl = opts.db.url;
     }
     else {
-        configureContainerRuntime();
+        if (!engine.local)
+            configureContainerRuntime();
         const container = await engine.startContainer(opts.db.image, opts.db.reuse);
         adminUrl = container.url;
         if (!opts.db.reuse)
@@ -50,7 +52,9 @@ export default async function setup(project) {
     // Likewise for recordings made against real services, merged into the recordings files at the end.
     const recording = Object.values(opts.recordings).some((r) => r.record);
     const recordDir = recording ? await mkdtemp(path.join(os.tmpdir(), "slicetest-recordings-")) : undefined;
-    project.provide("slicetestDb", { adminUrl, template, prefix, coverageDir, recordDir });
+    // On GitHub Actions, failed YAML steps are collected here and turned into annotations at the end.
+    const ciDir = onGitHub() ? await mkdtemp(path.join(os.tmpdir(), "slicetest-ci-")) : undefined;
+    project.provide("slicetestDb", { adminUrl, template, prefix, coverageDir, recordDir, ciDir });
     return async () => {
         try {
             if (!stopContainer) {
@@ -66,6 +70,8 @@ export default async function setup(project) {
                 await reportCoverage(opts, coverageDir);
             if (recordDir)
                 await saveRecordings(opts, recordDir);
+            if (ciDir)
+                await reportToGitHub(ciDir);
         }
     };
 }
@@ -85,10 +91,14 @@ async function reportCoverage(opts, dir) {
         const cache = coverageCacheFile(opts.root);
         await mkdir(path.dirname(cache), { recursive: true }).then(() => writeFile(cache, JSON.stringify([...hits]))).catch(() => { });
         console.log(`\n${report.text}\n`);
+        await appendSummary(report.markdown);
         const min = opts.openapi.minCoverage;
         if (min !== undefined && report.percent < min) {
             // Not thrown: Vitest reports teardown errors as a crash. The failing exit code is what CI needs.
-            console.error(`slicetest: OpenAPI coverage ${report.percent}% is below openapi.minCoverage (${min}%)\n`);
+            const message = `OpenAPI coverage ${report.percent}% is below openapi.minCoverage (${min}%)`;
+            console.error(`slicetest: ${message}\n`);
+            if (onGitHub())
+                console.log(annotation("error", message, { file: repoPath(path.resolve(opts.root, opts.openapi.app)), title: "slicetest: OpenAPI coverage" }));
             process.exitCode = 1;
         }
     }
@@ -96,6 +106,17 @@ async function reportCoverage(opts, dir) {
         await rm(dir, { recursive: true, force: true });
     }
 }
+async function reportToGitHub(dir) {
+    try {
+        const failures = await yamlFailures(dir);
+        for (const line of failureAnnotations(failures))
+            console.log(line);
+        await appendSummary(failureSummary(failures));
+    }
+    finally {
+        await rm(dir, { recursive: true, force: true });
+    }
+}
 async function saveRecordings(opts, dir) {
     try {
         const files = await readdir(dir);

package/dist/http.d.ts

@@ -37,6 +37,12 @@ export declare class HttpClient {
     post(path: string, body?: unknown, opts?: RequestOptions): Promise<HttpResponse>;
     put(path: string, body?: unknown, opts?: RequestOptions): Promise<HttpResponse>;
     patch(path: string, body?: unknown, opts?: RequestOptions): Promise<HttpResponse>;
+    /**
+     * Run `send` `n` times at once and wait for every response, to provoke races
+     * (double bookings, lost updates). Pair with `toHaveStatuses({ 201: 1, 409: n - 1 })`
+     * and a check of the database. Requests are released together once all are prepared.
+     */
+    concurrently(n: number, send: (i: number) => Promise<HttpResponse>): Promise<HttpResponse[]>;
     /** Strings, URLSearchParams, FormData, Blob and byte arrays are sent as-is; anything else is sent as JSON. */
     request(method: string, path: string, body?: unknown, options?: RequestOptions): Promise<HttpResponse>;
     /** Call `fn` with every response this client (or one derived with `with()`) receives. */

package/dist/http.js

@@ -41,6 +41,20 @@ export class HttpClient {
     patch(path, body, opts) {
         return this.request("PATCH", path, body, opts);
     }
+    /**
+     * Run `send` `n` times at once and wait for every response, to provoke races
+     * (double bookings, lost updates). Pair with `toHaveStatuses({ 201: 1, 409: n - 1 })`
+     * and a check of the database. Requests are released together once all are prepared.
+     */
+    async concurrently(n, send) {
+        if (!Number.isInteger(n) || n < 1)
+            throw new Error(`slicetest: concurrently() needs a positive number of requests, got ${n}`);
+        let release;
+        const gate = new Promise((r) => (release = r));
+        const all = Promise.all(Array.from({ length: n }, (_, i) => gate.then(() => send(i))));
+        release();
+        return all;
+    }
     /** Strings, URLSearchParams, FormData, Blob and byte arrays are sent as-is; anything else is sent as JSON. */
     async request(method, path, body, options = {}) {
         const opts = merge(this.defaults, options);

package/dist/index.d.ts

@@ -7,5 +7,6 @@ export type { Stub, RecordedCall, StubResponse, Responder, MatchOptions, RouteBu
 export type { HttpClient, HttpResponse, RequestOptions } from "./http.js";
 export type { App } from "./app.js";
 export type { Dependency } from "./containers.js";
+export type { Mailbox, Mail, MailFilter } from "./mail.js";
 export type { SlicetestOptions, ContainerOptions } from "./config.js";
 export type {} from "./matchers.js";

package/dist/init.js

@@ -93,8 +93,21 @@ export async function detect(root) {
         notes.push("db: no migrations found; the database starts empty. Set db.migrate.");
     }
     // --- docker compose: the database image and other dependencies ---
-    const { db: composeDb, containers, appEnv } = await fromCompose(root, notes);
+    const { db: composeDb, containers, appEnv, mail: composeMail } = await fromCompose(root, notes);
     Object.assign(env, appEnv);
+    let mail = composeMail;
+    if (!mail && (deps.nodemailer || /\b(flask-mail|fastapi-mail|django-anymail)\b/.test(python) || (has("manage.py") && /EMAIL_HOST/.test(await read(await djangoSettings(root)))))) {
+        mail = true;
+        Object.assign(env, { SMTP_HOST: "{{mail.host}}", SMTP_PORT: "{{mail.port}}" });
+        notes.push("mail: the app sends mail; slicetest catches it over SMTP (SMTP_HOST / SMTP_PORT, rename them to what your app reads)");
+    }
+    const sqlite = await detectSqlite(root, read, deps, python, gemfile);
+    if (sqlite && !composeDb.engine) {
+        composeDb.engine = "sqlite";
+        env.DATABASE_URL = sqlite.url;
+        notes.push(`db: SQLite (${sqlite.why}), no container needed. The app gets DATABASE_URL=${sqlite.url}; {{db.path}} is the plain file path`);
+    }
+    const stubs = await stubsFromEnvExample(root, read, env, notes);
     const mysqlDeps = !!deps.mysql2 || !!deps.mysql || /\b(pymysql|mysqlclient|aiomysql)\b/.test(python) || /\bgem ['"]mysql2['"]/.test(gemfile);
     if (!composeDb.engine && mysqlDeps) {
         composeDb.engine = "mysql";
@@ -108,11 +121,64 @@ export async function detect(root) {
         app: { command, env, ready: { path: "/" } },
         ...(migrate || Object.keys(composeDb).length ? { db: { ...composeDb, ...(migrate ? { migrate } : {}) } } : {}),
         ...(Object.keys(containers).length ? { containers } : {}),
-        stubs: [],
+        ...(mail ? { mail: true } : {}),
+        stubs,
         ...(openapi ? { openapi } : {}),
     };
     return { config, notes };
 }
+async function djangoSettings(root) {
+    for (const dir of await readdir(root, { withFileTypes: true }).catch(() => [])) {
+        if (dir.isDirectory() && existsSync(path.join(root, dir.name, "settings.py")))
+            return path.join(dir.name, "settings.py");
+    }
+    return "settings.py";
+}
+/** Where the project says it uses SQLite, and the URL form its framework reads. */
+async function detectSqlite(root, read, deps, python, gemfile) {
+    if (/provider\s*=\s*"sqlite"/.test(await read("prisma/schema.prisma")))
+        return { why: "Prisma provider", url: "file:{{db.path}}" };
+    if (/adapter:\s*sqlite3/.test(await read("config/database.yml")))
+        return { why: "config/database.yml", url: "sqlite3:{{db.path}}" };
+    if (/\bgem ['"]sqlite3['"]/.test(gemfile) && !/\bgem ['"](pg|mysql2)['"]/.test(gemfile))
+        return { why: "sqlite3 gem", url: "sqlite3:{{db.path}}" };
+    if (existsSync(path.join(root, "manage.py")) && /django\.db\.backends\.sqlite3/.test(await read(await djangoSettings(root)))) {
+        return { why: "Django settings; make DATABASES read DATABASE_URL, e.g. with dj-database-url", url: "{{db.url}}" };
+    }
+    const pgOrMysql = deps.pg || deps.postgres || deps.mysql2 || /\b(psycopg|asyncpg|pymysql|mysqlclient)/.test(python);
+    if (!pgOrMysql && (deps["better-sqlite3"] || deps.sqlite3 || deps["@libsql/client"]))
+        return { why: "a SQLite driver is a dependency", url: "{{db.url}}" };
+    return undefined;
+}
+/** Hosts that are never third-party APIs to stub. */
+const LOCAL_HOST = /^(localhost|127\.|0\.0\.0\.0|\[::1\]|host\.docker\.internal|[\w-]+$)/;
+/**
+ * `.env.example` lines like `STRIPE_API_BASE=https://api.stripe.com` name the
+ * services the app calls: each becomes a stub recorded from that URL, and the
+ * variable points the app at the stub.
+ */
+async function stubsFromEnvExample(root, read, env, notes) {
+    const file = [".env.example", ".env.sample", ".env.template", ".env.dist"].find((f) => existsSync(path.join(root, f)));
+    if (!file)
+        return [];
+    const stubs = [];
+    for (const line of (await read(file)).split(/\r?\n/)) {
+        const m = /^\s*(?:export\s+)?([A-Z][A-Z0-9_]*)\s*=\s*["']?(https?:\/\/[^\s"'#]+)/.exec(line);
+        if (!m || !/(URL|URI|ENDPOINT|HOST|BASE)$/.test(m[1]) || /DATABASE|REDIS|MONGO|AMQP|SMTP|MAIL|CALLBACK|REDIRECT|FRONTEND|PUBLIC|APP_URL|SITE_URL|WEBHOOK_URL$/.test(m[1]))
+            continue;
+        const url = new URL(m[2]);
+        if (LOCAL_HOST.test(url.hostname))
+            continue;
+        const base = url.hostname.split(".").filter((p) => !["api", "www", "com", "io", "net", "org", "co", "dev", "app"].includes(p))[0] ?? url.hostname;
+        let name = base.replace(/[^\w-]/g, "-").toLowerCase();
+        while (stubs.some((s) => s.name === name))
+            name += "2";
+        stubs.push({ name, upstream: url.origin });
+        env[m[1]] = `{{stub.${name}}}${url.pathname.replace(/\/$/, "")}`;
+        notes.push(`stubs.${name}: ${m[1]} in ${file} points at ${url.origin}. Record it once with SLICETEST_RECORD=${name}, or register routes in scenarios`);
+    }
+    return stubs;
+}
 const SCENARIO = `# yaml-language-server: $schema=https://unpkg.com/slicetest/schema/scenario.schema.json
 # A first scenario. Run it with: npx slicetest
 scenarios:
@@ -142,6 +208,8 @@ export async function init(root, { force = false } = {}) {
     return { files: [configFile, scenarioFile].map((f) => path.relative(root, f)), notes };
 }
 const COMPOSE_FILES = ["compose.yaml", "compose.yml", "docker-compose.yml", "docker-compose.yaml"];
+/** Development mail servers; `mail: true` does their job in-process. */
+const MAIL_CATCHERS = /(^|\/)(mailpit|mailhog|maildev|smtp4dev|greenmail[\w-]*|mailcatcher|inbucket)(:|$)/;
 /** Known images: the port they listen on, how to empty them, and the variable apps usually read. */
 const KNOWN = [
     { match: /(^|\/)(redis|redis-stack|keydb)(:|$)/, port: 6379, reset: ["redis-cli", "FLUSHALL"], env: (n) => ["REDIS_URL", `redis://{{container.${n}}}`] },
@@ -165,16 +233,17 @@ async function fromCompose(root, notes) {
     const db = {};
     const containers = {};
     const appEnv = {};
+    let mail = false;
     const file = COMPOSE_FILES.find((f) => existsSync(path.join(root, f)));
     if (!file)
-        return { db, containers, appEnv };
+        return { db, containers, appEnv, mail };
     let doc;
     try {
         doc = (parse(await readFile(path.join(root, file), "utf8")) ?? {});
     }
     catch (e) {
         notes.push(`${file}: couldn't parse it (${e.message}); skipped`);
-        return { db, containers, appEnv };
+        return { db, containers, appEnv, mail };
     }
     for (const [name, svc] of Object.entries(doc.services ?? {})) {
         const image = typeof svc?.image === "string" ? svc.image : undefined;
@@ -194,6 +263,12 @@ async function fromCompose(root, notes) {
             notes.push(`db: MySQL image ${image} (${file} service "${name}"). Install mysql2 and @testcontainers/mysql next to slicetest.`);
             continue;
         }
+        if (MAIL_CATCHERS.test(image)) {
+            mail = true;
+            Object.assign(appEnv, { SMTP_HOST: "{{mail.host}}", SMTP_PORT: "{{mail.port}}" });
+            notes.push(`mail: ${image} (${file} service "${name}") is replaced by slicetest's own SMTP server, passed to the app as SMTP_HOST / SMTP_PORT. Rename them to what your app reads`);
+            continue;
+        }
         const known = KNOWN.find((k) => k.match.test(image));
         const port = known?.port ?? containerPort(svc.ports?.[0] ?? svc.expose?.[0]);
         if (!port) {
@@ -214,7 +289,7 @@ async function fromCompose(root, notes) {
             appEnv[key] = value;
         notes.push(`containers.${name}: ${image} (${file})${key ? `, passed to the app as ${key}` : `, at {{container.${name}}}`}${known?.reset ? "" : ". Add `reset` to empty it between scenarios"}`);
     }
-    return { db, containers, appEnv };
+    return { db, containers, appEnv, mail };
 }
 /** `"6379:6379"`, `"127.0.0.1:5432:5432/tcp"`, `9000`, `{ target: 6379 }` → the port inside the container. */
 export function containerPort(spec) {

package/dist/mail.d.ts

@@ -0,0 +1,58 @@
+/**
+ * An SMTP server that accepts every message and keeps it, so scenarios can
+ * check the mail an app sends (sign-up confirmations, password resets,
+ * receipts) without a real mail server. Apps in any language reach it at
+ * `{{mail.host}}:{{mail.port}}` with no TLS; any credentials are accepted.
+ */
+export interface Mail {
+    from: string;
+    /** Envelope recipients (RCPT TO), which include Cc and Bcc. */
+    to: string[];
+    subject: string;
+    /** The text/plain part, decoded. */
+    text: string;
+    /** The text/html part, decoded, if there is one. */
+    html?: string;
+    /** Header names are lower-case. Repeated headers are joined with ", ". */
+    headers: Record<string, string>;
+    /** Every http(s) URL in the text and HTML parts, in order, without duplicates. */
+    links: string[];
+    raw: string;
+}
+/**
+ * Which messages to look at. Strings match the address exactly (`to`, `from`,
+ * case-insensitive) or as a substring (`subject`, `text`, `html`); RegExps test the value.
+ */
+export interface MailFilter {
+    to?: string | RegExp;
+    from?: string | RegExp;
+    subject?: string | RegExp;
+    text?: string | RegExp;
+    html?: string | RegExp;
+}
+export declare class Mailbox {
+    #private;
+    private readonly server;
+    private constructor();
+    static start(): Promise<Mailbox>;
+    get host(): string;
+    get port(): number;
+    /** `smtp://127.0.0.1:<port>`, for libraries configured with a URL. */
+    get url(): string;
+    /** Messages received during this scenario, oldest first. */
+    messages(filter?: MailFilter): Mail[];
+    /** The most recent message matching `filter`, or undefined. */
+    last(filter?: MailFilter): Mail | undefined;
+    /**
+     * The first message matching `filter`, waiting up to `within` ms for the app
+     * to send it. Fails with the messages that did arrive.
+     */
+    waitFor(filter?: MailFilter, { within }?: {
+        within?: number | undefined;
+    }): Promise<Mail>;
+    /** One line per message received this scenario, for failure output. */
+    describe(): string;
+    reset(): void;
+    close(): Promise<void>;
+}
+export declare function parseMail(raw: string, from: string, to: string[]): Mail;