slicetest 0.3.0 → 0.5.0

package/dist/index.d.ts

@@ -3,9 +3,13 @@ export { mask } from "./trace.js";
 export type { Trace, MaskOptions } from "./trace.js";
 export type { ScenarioContext } from "./runtime.js";
 export type { Db, Row, Where, RowsOptions, Changes, TableChanges } from "./db.js";
-export type { Stub, RecordedCall, StubResponse, Responder, MatchOptions, RouteBuilder } from "./stub.js";
+export type { Stub, RecordedCall, StubResponse, Responder, MatchOptions, RouteBuilder, ChaosOptions } from "./stub.js";
 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 { Issuer, TokenOptions, AuthOptions } from "./auth.js";
+export { normalizeSql, type Query, type QueryList } from "./query-log.js";
+export { signWebhook, type WebhookOptions, type WebhookProvider, type HmacScheme } from "./webhook.js";
 export type { SlicetestOptions, ContainerOptions } from "./config.js";
 export type {} from "./matchers.js";

package/dist/index.js

@@ -1,2 +1,4 @@
 export { scenario } from "./scenario.js";
 export { mask } from "./trace.js";
+export { normalizeSql } from "./query-log.js";
+export { signWebhook } from "./webhook.js";

package/dist/init.js

@@ -93,8 +93,27 @@ 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 auth = await authFromEnvExample(root, read, env, notes);
+    const jwtDeps = ["jose", "jsonwebtoken", "passport-jwt", "express-oauth2-jwt-bearer", "express-jwt", "jwks-rsa", "@fastify/jwt", "next-auth"].filter((d) => deps[d]);
+    const jwtPython = /\b(pyjwt|python-jose|authlib|fastapi-azure-auth|djangorestframework-simplejwt)\b/i.exec(python)?.[1];
+    if (!auth && (jwtDeps.length || jwtPython)) {
+        notes.push(`auth: ${jwtDeps[0] ?? jwtPython} is a dependency, so the app may verify JWTs. To test with real tokens, add \`auth: true\` and pass {{auth.issuer}} / {{auth.jwks}} / {{auth.audience}} to the variables the app reads`);
+    }
+    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 +127,101 @@ 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 } : {}),
+        ...(auth ? { auth: 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;
+}
+/** Variables that tell the app which token issuer to trust, and what slicetest passes instead. */
+const AUTH_VARS = [
+    [/JWKS(_URL|_URI|_ENDPOINT)?$/, "{{auth.jwks}}"],
+    [/(ISSUER|ISSUER_URL|ISSUER_BASE_URL|AUTHORITY)$/, "{{auth.issuer}}"],
+    [/^(AUTH0|OKTA|KEYCLOAK|COGNITO|OIDC|OAUTH2?|AUTH|JWT)_?(DOMAIN|URL|BASE_URL)$/, "{{auth.issuer}}"],
+    [/(AUDIENCE|_AUD)$/, "{{auth.audience}}"],
+];
+/**
+ * `.env.example` variables naming a token issuer (`OIDC_ISSUER`, `AUTH0_DOMAIN`,
+ * `JWKS_URL`, `JWT_AUDIENCE`) turn on `auth`, with the variables pointed at
+ * slicetest's issuer. Returns whether any was found.
+ */
+async function authFromEnvExample(root, read, env, notes) {
+    const file = [".env.example", ".env.sample", ".env.template", ".env.dist"].find((f) => existsSync(path.join(root, f)));
+    if (!file)
+        return false;
+    const found = [];
+    for (const line of (await read(file)).split(/\r?\n/)) {
+        const name = /^\s*(?:export\s+)?([A-Z][A-Z0-9_]*)\s*=/.exec(line)?.[1];
+        if (!name || name in env)
+            continue;
+        const match = AUTH_VARS.find(([re]) => re.test(name));
+        // AUDIENCE alone doesn't say the app verifies tokens; it comes along with an issuer or JWKS.
+        if (!match)
+            continue;
+        env[name] = match[1];
+        found.push(name);
+    }
+    if (!found.some((n) => env[n] !== "{{auth.audience}}")) {
+        for (const n of found)
+            delete env[n];
+        return false;
+    }
+    notes.push(`auth: ${found.join(", ")} in ${file} point at slicetest's OpenID issuer; scenarios mint tokens with auth.token({ sub, ... }) or \`auth:\` on a YAML request. An issuer the app expects as a bare domain (Auth0) may need the variable reshaped`);
+    return true;
+}
+/** 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 || m[1] in env || !/(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 +251,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 +276,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 +306,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 +332,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;

package/dist/mail.js

@@ -0,0 +1,299 @@
+import net from "node:net";
+export class Mailbox {
+    server;
+    #messages = [];
+    #waiters = new Set();
+    #sockets = new Set();
+    constructor(server) {
+        this.server = server;
+    }
+    static async start() {
+        const box = new Mailbox(net.createServer((socket) => box.#session(socket)));
+        await new Promise((resolve, reject) => {
+            box.server.once("error", reject);
+            box.server.listen(0, "127.0.0.1", resolve);
+        });
+        return box;
+    }
+    get host() {
+        return "127.0.0.1";
+    }
+    get port() {
+        return this.server.address().port;
+    }
+    /** `smtp://127.0.0.1:<port>`, for libraries configured with a URL. */
+    get url() {
+        return `smtp://${this.host}:${this.port}`;
+    }
+    /** Messages received during this scenario, oldest first. */
+    messages(filter = {}) {
+        return this.#messages.filter((m) => matches(m, filter));
+    }
+    /** The most recent message matching `filter`, or undefined. */
+    last(filter = {}) {
+        return this.messages(filter).at(-1);
+    }
+    /**
+     * The first message matching `filter`, waiting up to `within` ms for the app
+     * to send it. Fails with the messages that did arrive.
+     */
+    async waitFor(filter = {}, { within = 5000 } = {}) {
+        const deadline = Date.now() + within;
+        for (;;) {
+            const found = this.messages(filter)[0];
+            if (found)
+                return found;
+            const left = deadline - Date.now();
+            if (left <= 0)
+                throw new Error(`slicetest: no mail matching ${describeFilter(filter)} within ${within}ms\n${this.describe()}`);
+            await new Promise((resolve) => {
+                const done = () => {
+                    clearTimeout(timer);
+                    this.#waiters.delete(done);
+                    resolve();
+                };
+                const timer = setTimeout(done, left);
+                this.#waiters.add(done);
+            });
+        }
+    }
+    /** One line per message received this scenario, for failure output. */
+    describe() {
+        if (this.#messages.length === 0)
+            return "mail sent during this scenario: (none)";
+        return `mail sent during this scenario:\n${this.#messages.map((m) => `  ${m.from} → ${m.to.join(", ")}: ${JSON.stringify(m.subject)}`).join("\n")}`;
+    }
+    reset() {
+        this.#messages = [];
+    }
+    async close() {
+        for (const s of this.#sockets)
+            s.destroy();
+        await new Promise((resolve) => this.server.close(() => resolve()));
+    }
+    #receive(mail) {
+        this.#messages.push(mail);
+        for (const w of [...this.#waiters])
+            w();
+    }
+    /** A minimal SMTP (RFC 5321) session: no TLS, AUTH accepted, one message per MAIL … DATA. */
+    #session(socket) {
+        this.#sockets.add(socket);
+        socket.on("close", () => this.#sockets.delete(socket));
+        socket.on("error", () => { });
+        const reply = (line) => socket.write(`${line}\r\n`);
+        let buffer = "";
+        let from = "";
+        let to = [];
+        let data;
+        let auth;
+        reply("220 slicetest ESMTP");
+        socket.setEncoding("utf8");
+        socket.on("data", (chunk) => {
+            buffer += chunk;
+            let i;
+            while ((i = buffer.indexOf("\n")) >= 0) {
+                const line = buffer.slice(0, i).replace(/\r$/, "");
+                buffer = buffer.slice(i + 1);
+                if (data) {
+                    if (line === ".") {
+                        this.#receive(parseMail(data.join("\r\n"), from, to));
+                        data = undefined;
+                        reply("250 OK: queued");
+                    }
+                    else
+                        data.push(line.startsWith(".") ? line.slice(1) : line);
+                    continue;
+                }
+                if (auth) {
+                    auth = auth === "login-user" ? "login-pass" : undefined;
+                    reply(auth ? "334 UGFzc3dvcmQ6" : "235 Authentication successful");
+                    continue;
+                }
+                const [verb = "", ...rest] = line.split(" ");
+                const arg = rest.join(" ");
+                switch (verb.toUpperCase()) {
+                    case "EHLO":
+                        reply("250-slicetest");
+                        reply("250-AUTH PLAIN LOGIN");
+                        reply("250-8BITMIME");
+                        reply("250-SMTPUTF8");
+                        reply("250 SIZE 52428800");
+                        break;
+                    case "HELO":
+                        reply("250 slicetest");
+                        break;
+                    case "AUTH": {
+                        const [mech = "", initial] = arg.split(" ");
+                        if (mech.toUpperCase() === "LOGIN") {
+                            auth = initial ? "login-pass" : "login-user";
+                            reply(initial ? "334 UGFzc3dvcmQ6" : "334 VXNlcm5hbWU6");
+                        }
+                        else if (initial)
+                            reply("235 Authentication successful");
+                        else {
+                            auth = "plain";
+                            reply("334 ");
+                        }
+                        break;
+                    }
+                    case "MAIL":
+                        from = address(arg);
+                        to = [];
+                        reply("250 OK");
+                        break;
+                    case "RCPT":
+                        to.push(address(arg));
+                        reply("250 OK");
+                        break;
+                    case "DATA":
+                        if (to.length === 0)
+                            reply("503 RCPT first");
+                        else {
+                            data = [];
+                            reply("354 End data with <CR><LF>.<CR><LF>");
+                        }
+                        break;
+                    case "RSET":
+                        from = "";
+                        to = [];
+                        reply("250 OK");
+                        break;
+                    case "NOOP":
+                        reply("250 OK");
+                        break;
+                    case "QUIT":
+                        reply("221 Bye");
+                        socket.end();
+                        break;
+                    default:
+                        reply(`502 ${verb} not implemented`);
+                }
+            }
+        });
+    }
+}
+function address(arg) {
+    const m = /<([^>]*)>/.exec(arg) ?? /:\s*(\S+)/.exec(arg);
+    return (m?.[1] ?? "").trim();
+}
+function matches(mail, f) {
+    const addr = (want, values) => want === undefined || values.some((v) => (typeof want === "string" ? v.toLowerCase() === want.toLowerCase() : test(want, v)));
+    const text = (want, value) => want === undefined || (value !== undefined && (typeof want === "string" ? value.includes(want) : test(want, value)));
+    return addr(f.to, mail.to) && addr(f.from, [mail.from]) && text(f.subject, mail.subject) && text(f.text, mail.text) && text(f.html, mail.html);
+}
+function test(re, s) {
+    re.lastIndex = 0;
+    return re.test(s);
+}
+function describeFilter(f) {
+    const parts = Object.entries(f).map(([k, v]) => `${k}: ${v instanceof RegExp ? String(v) : JSON.stringify(v)}`);
+    return parts.length ? `{ ${parts.join(", ")} }` : "(any)";
+}
+/** Headers are unfolded and lower-cased; the body is everything after the blank line. */
+function splitPart(raw) {
+    const end = raw.search(/\r?\n\r?\n/);
+    const head = end < 0 ? raw : raw.slice(0, end);
+    const body = end < 0 ? "" : raw.slice(end).replace(/^\r?\n\r?\n/, "");
+    const headers = {};
+    for (const line of head.replace(/\r?\n[ \t]+/g, " ").split(/\r?\n/)) {
+        const i = line.indexOf(":");
+        if (i <= 0)
+            continue;
+        const name = line.slice(0, i).trim().toLowerCase();
+        const value = line.slice(i + 1).trim();
+        headers[name] = headers[name] ? `${headers[name]}, ${value}` : value;
+    }
+    return { headers, body };
+}
+export function parseMail(raw, from, to) {
+    const top = splitPart(raw);
+    const texts = [];
+    const walk = (part) => {
+        const type = (part.headers["content-type"] ?? "text/plain").toLowerCase();
+        const boundary = /boundary="?([^";]+)"?/i.exec(part.headers["content-type"] ?? "")?.[1];
+        if (type.startsWith("multipart/") && boundary) {
+            const pieces = part.body.split(new RegExp(`\\r?\\n?--${escape(boundary)}(?:--)?[ \\t]*\\r?\\n?`));
+            for (const piece of pieces.slice(1))
+                if (piece.trim())
+                    walk(splitPart(piece));
+            return;
+        }
+        if (!type.startsWith("text/") || /attachment/i.test(part.headers["content-disposition"] ?? ""))
+            return;
+        texts.push({ type, text: decodeBody(part) });
+    };
+    walk(top);
+    const text = texts.find((t) => t.type.startsWith("text/plain"))?.text;
+    const html = texts.find((t) => t.type.startsWith("text/html"))?.text;
+    const headerFrom = /<([^>]+)>/.exec(top.headers.from ?? "")?.[1] ?? top.headers.from;
+    return {
+        from: from || headerFrom || "",
+        to: to.length ? to : (top.headers.to ?? "").split(",").map((a) => (/<([^>]+)>/.exec(a)?.[1] ?? a).trim()).filter(Boolean),
+        subject: decodeWords(top.headers.subject ?? ""),
+        text: text ?? (html ? htmlToText(html) : ""),
+        html,
+        headers: Object.fromEntries(Object.entries(top.headers).map(([k, v]) => [k, decodeWords(v)])),
+        links: links([text ?? "", html ?? ""].join("\n")),
+        raw,
+    };
+}
+function charsetOf(part) {
+    return /charset="?([^";]+)"?/i.exec(part.headers["content-type"] ?? "")?.[1] ?? "utf-8";
+}
+function decodeBody(part) {
+    const enc = (part.headers["content-transfer-encoding"] ?? "").toLowerCase();
+    const bytes = enc === "base64" ? Buffer.from(part.body.replace(/\s+/g, ""), "base64")
+        : enc === "quoted-printable" ? quotedPrintable(part.body)
+            : Buffer.from(part.body, "utf8");
+    return decodeCharset(bytes, charsetOf(part)).replace(/\r\n/g, "\n").replace(/\n$/, "");
+}
+function quotedPrintable(s) {
+    const bytes = [];
+    const src = s.replace(/=\r?\n/g, "");
+    for (let i = 0; i < src.length; i++) {
+        if (src[i] === "=" && /^[0-9A-F]{2}$/i.test(src.slice(i + 1, i + 3))) {
+            bytes.push(parseInt(src.slice(i + 1, i + 3), 16));
+            i += 2;
+        }
+        else
+            bytes.push(...Buffer.from(src[i], "utf8"));
+    }
+    return Buffer.from(bytes);
+}
+function decodeCharset(bytes, charset) {
+    try {
+        return new TextDecoder(charset).decode(bytes);
+    }
+    catch {
+        return bytes.toString("utf8");
+    }
+}
+/** RFC 2047 encoded words: `=?UTF-8?B?...?=` and `=?ISO-2022-JP?Q?...?=`. */
+function decodeWords(s) {
+    return s
+        .replace(/\?=\s+=\?/g, "?==?")
+        .replace(/=\?([^?]+)\?([BbQq])\?([^?]*)\?=/g, (_, charset, enc, text) => {
+        const bytes = enc.toUpperCase() === "B" ? Buffer.from(text, "base64") : quotedPrintable(text.replace(/_/g, " "));
+        return decodeCharset(bytes, charset);
+    });
+}
+function htmlToText(html) {
+    return html
+        .replace(/<(script|style)[\s\S]*?<\/\1>/gi, "")
+        .replace(/<br\s*\/?>|<\/p>/gi, "\n")
+        .replace(/<[^>]+>/g, "")
+        .replace(/&amp;/g, "&")
+        .replace(/&lt;/g, "<")
+        .replace(/&gt;/g, ">")
+        .replace(/&quot;/g, '"')
+        .replace(/&#39;/g, "'")
+        .trim();
+}
+function links(s) {
+    const found = (s.match(/https?:\/\/[^\s"'<>)\]]+/g) ?? []).map((u) => u.replace(/&amp;/g, "&").replace(/[.,;:!?]+$/, ""));
+    return [...new Set(found)];
+}
+function escape(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}

package/dist/matchers.d.ts

@@ -1,4 +1,5 @@
 import { type Where } from "./db.js";
+import type { HttpResponse } from "./http.js";
 import { type MatchOptions } from "./stub.js";
 interface SlicetestMatchers<R = unknown> {
     /** The stub received at least one call matching `method path` (and `match`, if given). */
@@ -7,6 +8,8 @@ interface SlicetestMatchers<R = unknown> {
     toHaveReceivedTimes(n: number, method?: string, path?: string | RegExp, match?: MatchOptions): R;
     /** The response has this status; the failure message shows the response body. */
     toHaveStatus(status: number): R;
+    /** An array of responses has exactly these status counts, e.g. `{ 201: 1, 409: 9 }`. */
+    toHaveStatuses(counts: Record<number, number>): R;
     /** Async: the table has at least one row matching `where` (`count` for an exact number). */
     toHaveRow(table: string, where?: Where, count?: number): Promise<void>;
 }
@@ -14,4 +17,5 @@ declare module "vitest" {
     interface Matchers<R extends void | Promise<void> = void | Promise<void>, T = unknown> extends SlicetestMatchers<R> {
     }
 }
+export declare function statusCounts(responses: HttpResponse[]): Record<number, number>;
 export {};

package/dist/matchers.js

@@ -17,6 +17,25 @@ function assertStub(received) {
     if (!(received instanceof Stub))
         throw new TypeError("slicetest: expected a stub, e.g. expect(stub(\"slack\"))");
 }
+export function statusCounts(responses) {
+    const out = {};
+    for (const r of responses)
+        out[r.status] = (out[r.status] ?? 0) + 1;
+    return out;
+}
+function fmtCounts(c) {
+    return `{ ${Object.entries(c).map(([k, n]) => `${k}: ${n}`).join(", ")} }`;
+}
+/** One example response per status, which is usually what explains the odd one out. */
+function describeResponses(responses) {
+    const seen = new Map();
+    for (const r of responses)
+        if (!seen.has(r.status))
+            seen.set(r.status, r);
+    return [...seen.values()]
+        .map((r) => `  ${r.status || "failed"}: ${r.method} ${r.url}  ${(r.text.length > 200 ? `${r.text.slice(0, 200)}…` : r.text).replace(/\s+/g, " ") || "(empty)"}`)
+        .join("\n");
+}
 expect.extend({
     toHaveReceived(received, method, path, match) {
         assertStub(received);
@@ -53,6 +72,20 @@ expect.extend({
             expected: status,
         };
     },
+    toHaveStatuses(received, counts) {
+        if (!Array.isArray(received))
+            throw new TypeError("slicetest: toHaveStatuses expects an array of responses, e.g. from http.concurrently()");
+        const actual = statusCounts(received);
+        const expected = Object.fromEntries(Object.entries(counts).filter(([, n]) => n > 0).map(([k, n]) => [Number(k), n]));
+        const pass = this.equals(actual, expected);
+        return {
+            pass,
+            message: () => `expected ${received.length} responses ${this.isNot ? "not " : ""}to have statuses ${fmtCounts(expected)}, got ${fmtCounts(actual)}\n` +
+                describeResponses(received),
+            actual,
+            expected,
+        };
+    },
     async toHaveRow(received, table, where = {}, count) {
         if (!(received instanceof Db))
             throw new TypeError("slicetest: expected the db handle, e.g. expect(db)");

package/dist/openapi.d.ts

@@ -15,6 +15,14 @@ export interface OperationSketch {
     responses: string[];
     /** Top-level properties of the first 2xx JSON response. */
     createdFields: string[];
+    /**
+     * The operation requires a bearer token (an `http: bearer`, `oauth2` or
+     * `openIdConnect` security scheme), with the scopes it lists. Undefined when
+     * it needs no token or accepts other credentials only.
+     */
+    bearer?: {
+        scopes: string[];
+    };
 }
 export interface Message {
     status?: number;
@@ -69,6 +77,7 @@ export declare function formatCoverage(spec: OpenApiSpec, hits: Set<string>): {
     covered: number;
     total: number;
     percent: number;
+    markdown: string;
     text: string;
 };
 export {};