slicetest 0.3.0 → 0.4.0

package/dist/record.js

@@ -0,0 +1,201 @@
+import { existsSync } from "node:fs";
+import { writeFile } from "node:fs/promises";
+import http from "node:http";
+import path from "node:path";
+import { stringify } from "yaml";
+import { mask } from "./trace.js";
+export const SESSION_ENV = "SLICETEST_RECORD_SESSION";
+/** Requests a browser makes on its own, not part of what the scenario is about. */
+const ASSET = /\.(ico|png|jpe?g|gif|webp|avif|svg|css|js|mjs|map|woff2?|ttf|eot)(\?|$)/i;
+/** Hop-by-hop headers, and the ones fetch rewrites. */
+const DROP_REQUEST = new Set(["host", "connection", "keep-alive", "transfer-encoding", "upgrade", "proxy-connection", "content-length", "accept-encoding"]);
+const DROP_RESPONSE = new Set(["connection", "keep-alive", "transfer-encoding", "content-encoding", "content-length"]);
+export async function runSession(ctx, session) {
+    const exchanges = [];
+    const target = ctx.app.url;
+    const proxy = http.createServer(async (req, res) => {
+        const chunks = [];
+        for await (const c of req)
+            chunks.push(c);
+        const body = Buffer.concat(chunks);
+        const headers = new Headers();
+        for (const [k, v] of Object.entries(req.headers)) {
+            if (v === undefined || DROP_REQUEST.has(k))
+                continue;
+            for (const value of Array.isArray(v) ? v : [v])
+                headers.append(k, value);
+        }
+        try {
+            const upstream = await fetch(new URL(req.url ?? "/", target), {
+                method: req.method,
+                headers,
+                body: body.length && req.method !== "GET" && req.method !== "HEAD" ? body : undefined,
+                redirect: "manual",
+            });
+            const payload = Buffer.from(await upstream.arrayBuffer());
+            const out = {};
+            upstream.headers.forEach((v, k) => {
+                if (!DROP_RESPONSE.has(k) && k !== "set-cookie")
+                    out[k] = v;
+            });
+            const cookies = upstream.headers.getSetCookie();
+            if (cookies.length)
+                out["set-cookie"] = cookies;
+            res.writeHead(upstream.status, out).end(payload);
+            exchanges.push({
+                method: req.method ?? "GET",
+                path: req.url ?? "/",
+                contentType: req.headers["content-type"],
+                body: body.toString("utf8"),
+                status: upstream.status,
+                responseType: upstream.headers.get("content-type") ?? undefined,
+                response: payload.toString("utf8"),
+            });
+        }
+        catch (e) {
+            res.writeHead(502, { "content-type": "text/plain" }).end(`slicetest record: the app didn't answer: ${e.message}\n`);
+        }
+    });
+    await new Promise((resolve, reject) => {
+        proxy.once("error", reject);
+        proxy.listen(session.port, "127.0.0.1", resolve);
+    });
+    const url = `http://127.0.0.1:${proxy.address().port}`;
+    await writeFile(session.stateFile, JSON.stringify({ url, app: target }));
+    while (!existsSync(session.stopFile))
+        await new Promise((r) => setTimeout(r, 200));
+    await new Promise((resolve) => proxy.close(() => resolve()));
+    proxy.closeAllConnections();
+    const calls = Object.fromEntries(session.stubs.map((name) => [name, ctx.stub(name).calls()]));
+    const changes = await ctx.db.changes();
+    const { yaml, summary } = buildScenario(exchanges, calls, changes, { name: path.basename(session.out).replace(/\.scenario\.ya?ml$/, "") });
+    await writeFile(session.out, yaml);
+    await writeFile(session.stateFile, JSON.stringify({ url, done: true, summary }));
+}
+/** The recorded session as a YAML scenario, with a comment header of what to review. */
+export function buildScenario(exchanges, calls, changes, { name = "recorded session", now = new Date() } = {}) {
+    const kept = exchanges.filter((x) => !ASSET.test(x.path));
+    const steps = [];
+    const notes = [];
+    // Stubs first: the answers the services gave, so the replay doesn't need them.
+    const unanswered = [];
+    let stubRoutes = 0;
+    for (const [stub, list] of Object.entries(calls)) {
+        const groups = new Map();
+        for (const c of list) {
+            if (!c.response || c.response.status === 501) {
+                unanswered.push(`${stub}: ${c.method} ${c.path}`);
+                continue;
+            }
+            const key = `${c.method} ${c.path}`;
+            groups.set(key, [...(groups.get(key) ?? []), c]);
+        }
+        for (const [on, group] of groups) {
+            const replies = group.map((c) => ({ status: c.response.status, ...(c.response.body ? { body: parse(c.response.body, c.response.headers["content-type"]) } : {}) }));
+            const same = replies.every((r) => JSON.stringify(r) === JSON.stringify(replies[0]));
+            steps.push({ stub, on, ...(same ? { reply: replies[0] } : { sequence: replies }) });
+            stubRoutes++;
+        }
+    }
+    if (unanswered.length)
+        notes.push(`These calls got no answer while recording (register a route, or give the stub an upstream / autoReply): ${unanswered.join(", ")}`);
+    // Values from earlier responses that later requests use (ids in paths, tokens in bodies) become captures.
+    const captured = new Map();
+    kept.forEach((x, i) => {
+        let reqPath = x.path;
+        let reqBody = x.body;
+        for (const [value, variable] of captured) {
+            reqPath = reqPath.split(value).join(`{{${variable}}}`);
+            reqBody = reqBody.split(value).join(`{{${variable}}}`);
+        }
+        const [method, pathOnly] = [x.method, reqPath];
+        const step = { request: `${method} ${pathOnly}` };
+        if (x.body) {
+            if (/json/i.test(x.contentType ?? ""))
+                step.json = parse(reqBody, "application/json");
+            else if (/x-www-form-urlencoded/i.test(x.contentType ?? ""))
+                step.form = Object.fromEntries(new URLSearchParams(reqBody));
+            else
+                step.body = reqBody;
+        }
+        const expectation = { status: x.status };
+        const json = /json/i.test(x.responseType ?? "") ? parse(x.response, "application/json") : undefined;
+        if (json !== undefined && typeof json === "object")
+            expectation.json = loosen(json);
+        else if (!/html/i.test(x.responseType ?? "") && x.response && x.response.length <= 200)
+            expectation.text = x.response;
+        step.expect = expectation;
+        // Capture top-level values that show up again later.
+        if (json && typeof json === "object" && !Array.isArray(json)) {
+            const later = kept.slice(i + 1).map((y) => `${y.path}\n${y.body}`).join("\n");
+            const capture = {};
+            for (const [key, value] of Object.entries(json)) {
+                if ((typeof value !== "string" && typeof value !== "number") || String(value).length < 3 || !later.includes(String(value)))
+                    continue;
+                let variable = key.replace(/\W/g, "_");
+                while ([...captured.values()].includes(variable))
+                    variable += "_";
+                capture[variable] = `json.${key}`;
+                captured.set(String(value), variable);
+            }
+            if (Object.keys(capture).length)
+                step.capture = capture;
+        }
+        steps.push(step);
+    });
+    for (const [stub, list] of Object.entries(calls)) {
+        const byCall = new Map();
+        for (const c of list)
+            if (c.response && c.response.status !== 501)
+                byCall.set(`${c.method} ${c.path}`, (byCall.get(`${c.method} ${c.path}`) ?? 0) + 1);
+        for (const [call, times] of byCall)
+            steps.push({ received: stub, call, times });
+    }
+    const tables = Object.keys(changes);
+    const counts = Object.fromEntries(Object.entries(changes).map(([table, c]) => [
+        table,
+        Object.fromEntries(Object.entries({ inserted: c.inserted.length, updated: c.updated.length, deleted: c.deleted.length }).filter(([, n]) => n > 0)),
+    ]));
+    steps.push({ changes: counts });
+    const skipped = exchanges.length - kept.length;
+    if (skipped)
+        notes.push(`${skipped} request(s) for static files (scripts, styles, images) were left out.`);
+    if (kept.length === 0)
+        notes.push("No requests to the app were recorded; send them to the proxy URL printed when recording started.");
+    const header = [
+        `# Recorded with \`npx slicetest record\` on ${now.toISOString().slice(0, 10)}. Review it before committing:`,
+        "# - give the scenario a name that says what it checks, and split it if it checks several things;",
+        "# - dates and UUIDs in responses are matched by type only, and `changes` only counts rows;",
+        "#   tighten what matters (see https://github.com/revo1290/slicetest#yaml-scenarios).",
+        ...notes.map((n) => `# - ${n}`),
+        "# yaml-language-server: $schema=https://unpkg.com/slicetest/schema/scenario.schema.json",
+        "",
+    ].join("\n");
+    const yaml = header + stringify({ scenarios: [{ name, steps }] }, { lineWidth: 0 });
+    const summary = { requests: kept.length, skippedAssets: skipped, stubs: stubRoutes, tables, unanswered };
+    return { yaml, summary };
+}
+function parse(text, contentType) {
+    if (/json/i.test(contentType ?? "")) {
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            return text;
+        }
+    }
+    return text;
+}
+/** Dates and UUIDs change from run to run: expect their type instead of their value. */
+function loosen(value) {
+    const walk = (v) => {
+        if (v === "[date]" || v === "[uuid]")
+            return { $type: "string" };
+        if (Array.isArray(v))
+            return v.map(walk);
+        if (v && typeof v === "object")
+            return Object.fromEntries(Object.entries(v).map(([k, x]) => [k, walk(x)]));
+        return v;
+    };
+    return walk(mask(value));
+}

package/dist/runtime.d.ts

@@ -3,6 +3,7 @@ import type { ResolvedOptions } from "./config.js";
 import { Dependency } from "./containers.js";
 import { Db } from "./db.js";
 import { HttpClient } from "./http.js";
+import { Mailbox } from "./mail.js";
 import { Stub } from "./stub.js";
 import { type MaskOptions, type Trace } from "./trace.js";
 export interface ScenarioContext {
@@ -19,6 +20,8 @@ export interface ScenarioContext {
      * with timestamps and UUIDs masked. `expect(await trace()).toMatchSnapshot()`.
      */
     trace: (opts?: MaskOptions) => Promise<Trace>;
+    /** Mail the app sent during the scenario. Needs `mail: true` in the config. */
+    mail: Mailbox;
 }
 /** Everything one test file needs: its own database, stub servers and app process. */
 export declare class Runtime {
@@ -34,6 +37,7 @@ export declare class Runtime {
     private readonly recorders;
     private readonly recordDir?;
     readonly containers: Map<string, Dependency>;
+    readonly mailbox?: Mailbox | undefined;
     private constructor();
     get http(): HttpClient;
     static start(opts: ResolvedOptions, shared: {

package/dist/runtime.js

@@ -6,6 +6,7 @@ import { Dependency } from "./containers.js";
 import { Db, formatChanges } from "./db.js";
 import { engineFor } from "./drivers/index.js";
 import { formatHistory, HttpClient } from "./http.js";
+import { Mailbox } from "./mail.js";
 import { OpenApiSpec } from "./openapi.js";
 import { Recorder } from "./recording.js";
 import { Stub } from "./stub.js";
@@ -23,12 +24,13 @@ export class Runtime {
     recorders;
     recordDir;
     containers;
+    mailbox;
     #http;
     /** Responses from the app that don't match its OpenAPI spec, this scenario. */
     #contract = [];
     /** Documented responses seen in this file, for the run's coverage report. */
     #covered = new Set();
-    constructor(app, services, db, stubs, opts, vars, specs, coverageDir, recorders = new Map(), recordDir, containers = new Map()) {
+    constructor(app, services, db, stubs, opts, vars, specs, coverageDir, recorders = new Map(), recordDir, containers = new Map(), mailbox) {
         this.app = app;
         this.services = services;
         this.db = db;
@@ -40,6 +42,7 @@ export class Runtime {
         this.recorders = recorders;
         this.recordDir = recordDir;
         this.containers = containers;
+        this.mailbox = mailbox;
         this.#http = this.#client();
     }
     #client() {
@@ -72,6 +75,7 @@ export class Runtime {
         const containers = new Map();
         const services = new Map();
         let db;
+        let mailbox;
         try {
             // Loaded first: a broken spec should fail before anything is started.
             const specs = {
@@ -102,6 +106,12 @@ export class Runtime {
             if (failed)
                 throw failed.reason;
             const vars = { "db.url": url };
+            if (engine.name === "sqlite")
+                vars["db.path"] = (await import("./drivers/sqlite.js")).sqlitePath(url);
+            if (opts.mail) {
+                mailbox = await Mailbox.start();
+                Object.assign(vars, { "mail.host": mailbox.host, "mail.port": String(mailbox.port), "mail.url": mailbox.url });
+            }
             for (const [name, c] of containers) {
                 vars[`container.${name}`] = c.address;
                 vars[`container.${name}.host`] = c.host;
@@ -116,17 +126,19 @@ export class Runtime {
                 vars[`service.${name}.port`] = String(started.port);
             }
             const app = await App.start(opts.app, opts.root, vars);
-            return new Runtime(app, services, db, stubs, opts, vars, specs, shared.coverageDir, recorders, shared.recordDir, containers);
+            return new Runtime(app, services, db, stubs, opts, vars, specs, shared.coverageDir, recorders, shared.recordDir, containers, mailbox);
         }
         catch (e) {
             await Promise.all([...services.values()].map((s) => s.stop()));
             await db?.close();
             await Promise.all([...stubs.values()].map((s) => s.close()));
             await Promise.allSettled([...containers.values()].map((c) => c.stop()));
+            await mailbox?.close();
             throw e;
         }
     }
     context() {
+        const mailbox = this.mailbox;
         return {
             http: this.http,
             db: this.db,
@@ -151,7 +163,12 @@ export class Runtime {
                     throw new Error(`slicetest: unknown container "${name}". Declared containers: ${[...this.containers.keys()].join(", ") || "(none)"}`);
                 return c;
             },
-            trace: async (opts) => mask(buildTrace(this.http.history, this.stubs.values(), await this.db.changesSinceStart()), opts),
+            trace: async (opts) => mask(buildTrace(this.http.history, this.stubs.values(), await this.db.changesSinceStart(), this.mailbox), opts),
+            get mail() {
+                if (!mailbox)
+                    throw new Error("slicetest: mail is off. Add `mail: true` to the config and point the app's SMTP settings at {{mail.host}} / {{mail.port}}.");
+                return mailbox;
+            },
         };
     }
     /** The app and every service, for checks that apply to all of them. */
@@ -177,6 +194,7 @@ export class Runtime {
             stub.reset();
         for (const recorder of this.recorders.values())
             recorder.reset();
+        this.mailbox?.reset();
         await Promise.all([...this.containers.values()].map((c) => c.reset()));
         this.http.reset();
         for (const p of this.#processes())
@@ -259,6 +277,8 @@ export class Runtime {
         catch (e) {
             sections.push(`database changes during this scenario: unavailable (${e.message})`);
         }
+        if (this.mailbox)
+            sections.push(this.mailbox.describe());
         const logs = this.app.scenarioLogs();
         sections.push(logs ? `app output during this scenario:\n${logs}` : "app output during this scenario: (none)");
         for (const [name, service] of this.services) {
@@ -282,6 +302,7 @@ export class Runtime {
             this.db.close(),
             ...[...this.stubs.values()].map((s) => s.close()),
             ...[...this.containers.values()].map((c) => c.stop()),
+            this.mailbox?.close(),
         ]);
         const failed = results.find((r) => r.status === "rejected");
         if (failed)

package/dist/trace.d.ts

@@ -1,5 +1,6 @@
 import type { Changes } from "./db.js";
 import type { HttpResponse } from "./http.js";
+import type { Mailbox } from "./mail.js";
 import type { Stub } from "./stub.js";
 /**
  * Everything one scenario did at the three boundaries: the requests it made to
@@ -19,6 +20,13 @@ export interface Trace {
         status?: number;
     }[]>;
     db: Changes;
+    /** Mail the app sent, when the `mail` option is on. */
+    mail?: {
+        from: string;
+        to: string[];
+        subject: string;
+        text: string;
+    }[];
 }
 export interface MaskOptions {
     /** Keys whose values are always replaced, e.g. `["token", "password_hash"]`. Matched at any depth. */
@@ -32,4 +40,4 @@ export interface MaskOptions {
  * `[uuid]`, and the values of `keys` / strings matching `patterns` by `[masked]`.
  */
 export declare function mask<T>(value: T, opts?: MaskOptions): T;
-export declare function buildTrace(history: readonly HttpResponse[], stubs: Iterable<Stub>, db: Changes): Trace;
+export declare function buildTrace(history: readonly HttpResponse[], stubs: Iterable<Stub>, db: Changes, mailbox?: Mailbox): Trace;

package/dist/trace.js

@@ -30,7 +30,7 @@ export function mask(value, opts = {}) {
     };
     return walk(value);
 }
-export function buildTrace(history, stubs, db) {
+export function buildTrace(history, stubs, db, mailbox) {
     const trace = {
         http: history.map((r) => {
             const url = new URL(r.url, "http://app");
@@ -53,5 +53,7 @@ export function buildTrace(history, stubs, db) {
             };
         });
     }
+    if (mailbox)
+        trace.mail = mailbox.messages().map((m) => ({ from: m.from, to: m.to, subject: m.subject, text: m.text }));
     return trace;
 }

package/dist/vitest.js

@@ -2,6 +2,7 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { configDefaults } from "vitest/config";
 import { resolveOptions } from "./config.js";
+import { SESSION_ENV } from "./record.js";
 import { parseScenarioFile } from "./yaml.js";
 /** YAML scenario files are picked up next to the regular test files. */
 export const YAML_SCENARIOS = "**/*.scenario.{yaml,yml}";
@@ -17,7 +18,9 @@ export function slicetest(options) {
             const root = path.resolve(config.root ?? process.cwd());
             // Mutated rather than returned: a returned list would replace Vitest's default include instead of extending it.
             const test = (config.test ??= {});
-            test.include = [...(test.include ?? configDefaults.include), YAML_SCENARIOS];
+            // `slicetest record` runs only its session file.
+            if (!process.env[SESSION_ENV])
+                test.include = [...(test.include ?? configDefaults.include), YAML_SCENARIOS];
             return {
                 test: {
                     globalSetup: [path.join(here, `global-setup${ext}`)],
@@ -31,7 +34,7 @@ export function slicetest(options) {
             const file = id.split("?")[0];
             if (!YAML_ID.test(file))
                 return;
-            const doc = parseScenarioFile(code, path.relative(root ?? process.cwd(), file) || file);
+            const doc = { ...parseScenarioFile(code, path.relative(root ?? process.cwd(), file) || file), path: file };
             const runtime = JSON.stringify(path.join(here, `yaml-runtime${ext}`));
             return { code: `import { defineYamlScenarios } from ${runtime};\ndefineYamlScenarios(${JSON.stringify(doc)});\n`, map: null };
         },

package/dist/yaml-runtime.d.ts

@@ -1,3 +1,4 @@
+import "./provided.js";
 import "./matchers.js";
 import type { YamlFile } from "./yaml.js";
 type Vars = Record<string, unknown>;

package/dist/yaml-runtime.js

@@ -1,4 +1,6 @@
-import { expect } from "vitest";
+import { expect, inject } from "vitest";
+import { recordYamlFailure } from "./ci.js";
+import "./provided.js";
 import { formatChanges } from "./db.js";
 import "./matchers.js";
 import { scenario } from "./scenario.js";
@@ -17,11 +19,17 @@ async function runSteps(doc, sc, steps, ctx, vars) {
     for (const [i, step] of steps.entries()) {
         try {
             // A log step waits by itself; `within` is its timeout.
-            await retry("within" in step && !("log" in step) ? step.within : undefined, () => runStep(step, ctx, vars));
+            // Log and mail steps wait by themselves; `within` is their timeout.
+            await retry("within" in step && !("log" in step) && !("mail" in step) ? step.within : undefined, () => runStep(step, ctx, vars));
         }
         catch (e) {
             const label = step.name ?? describeStep(step);
             const where = `${doc.file}:${step.line} (${sc.name}, step ${i + 1}: ${label})`;
+            const ciDir = inject("slicetestDb")?.ciDir;
+            if (ciDir && doc.path) {
+                const message = (e instanceof Error ? e.message : String(e)).replace(/\x1b\[[0-9;]*m/g, "");
+                await recordYamlFailure(ciDir, { file: doc.path, line: step.line, scenario: sc.name, step: `step ${i + 1}: ${label}`, message }).catch(() => { });
+            }
             if (e instanceof Error) {
                 e.message = `${where}\n${e.message}`;
                 throw e;
@@ -32,7 +40,7 @@ async function runSteps(doc, sc, steps, ctx, vars) {
 }
 function describeStep(step) {
     if ("request" in step)
-        return step.request;
+        return step.concurrency ? `${step.request} ×${step.concurrency}` : step.request;
     if ("stub" in step)
         return `stub ${step.stub} ${step.on}`;
     if ("received" in step)
@@ -47,6 +55,8 @@ function describeStep(step) {
         return "checkpoint";
     if ("snapshot" in step)
         return "snapshot";
+    if ("mail" in step)
+        return `mail${Object.entries(step.mail).map(([k, v]) => ` ${k}: ${JSON.stringify(v)}`).join(",")}`;
     if ("log" in step)
         return `log ${step.from ? `from ${step.from} ` : ""}/${step.log}/`;
     return "sql";
@@ -84,6 +94,24 @@ async function runStep(step, ctx, vars) {
         await target.waitForLog(new RegExp(interpolate(step.log, vars)), step.within ?? 5000);
         return;
     }
+    if ("mail" in step) {
+        const filter = Object.fromEntries(Object.entries(interpolate(step.mail, vars)).map(([k, v]) => {
+            const re = v && typeof v === "object" && "$regex" in v ? new RegExp(String(v.$regex)) : undefined;
+            return [k, re ?? String(v)];
+        }));
+        const box = ctx.mail;
+        await retry(step.within ?? 5000, async () => {
+            const found = box.messages(filter);
+            if (step.times === undefined ? found.length === 0 : found.length !== step.times) {
+                const want = step.times === undefined ? "at least one message" : `${step.times} message(s)`;
+                throw new Error(`expected ${want} matching ${JSON.stringify(step.mail)}, got ${found.length}\n${box.describe()}`);
+            }
+        });
+        const last = box.last(filter);
+        if (last)
+            capture(step.capture, last, vars);
+        return;
+    }
     if ("changes" in step) {
         const actual = await ctx.db.changes();
         const expected = interpolate(step.changes, vars);
@@ -141,18 +169,29 @@ async function runStep(step, ctx, vars) {
             : step.form !== undefined
                 ? ctx.http.form(interpolate(step.form, vars))
                 : interpolate(step.body, vars);
-        const res = await ctx.http.request(method, path, body, opts);
         const e = step.expect;
-        if (e?.status !== undefined)
-            expect(res).toHaveStatus(interpolate(e.status, vars));
-        if (e?.headers !== undefined) {
-            const expected = Object.fromEntries(Object.entries(e.headers).map(([k, v]) => [k.toLowerCase(), v]));
-            check(Object.fromEntries(res.headers), expected, vars, "response headers");
+        const verify = (res) => {
+            if (e?.status !== undefined)
+                expect(res).toHaveStatus(interpolate(e.status, vars));
+            if (e?.headers !== undefined) {
+                const expected = Object.fromEntries(Object.entries(e.headers).map(([k, v]) => [k.toLowerCase(), v]));
+                check(Object.fromEntries(res.headers), expected, vars, "response headers");
+            }
+            if (e?.json !== undefined)
+                check(res.json, e.json, vars, "response JSON");
+            if (e?.text !== undefined)
+                check(res.text, e.text, vars, "response text");
+        };
+        if (step.concurrency !== undefined) {
+            // Each request gets its own body: a URLSearchParams body can only be read once.
+            const all = await ctx.http.concurrently(step.concurrency, () => ctx.http.request(method, path, body instanceof URLSearchParams ? new URLSearchParams(body) : body, opts));
+            if (e?.statuses !== undefined)
+                expect(all).toHaveStatuses(interpolate(e.statuses, vars));
+            all.forEach(verify);
+            return;
         }
-        if (e?.json !== undefined)
-            check(res.json, e.json, vars, "response JSON");
-        if (e?.text !== undefined)
-            check(res.text, e.text, vars, "response text");
+        const res = await ctx.http.request(method, path, body, opts);
+        verify(res);
         capture(step.capture, { status: res.status, json: res.json, text: res.text, headers: Object.fromEntries(res.headers) }, vars);
         return;
     }

package/dist/yaml.d.ts

@@ -6,6 +6,8 @@
  */
 export interface YamlFile {
     file: string;
+    /** Absolute path, for CI annotations. */
+    path?: string;
     /** Steps run at the start of every scenario in the file. */
     setup: Step[];
     scenarios: YamlScenario[];
@@ -19,7 +21,7 @@ export interface YamlScenario {
     timeout?: number;
     steps: Step[];
 }
-export type Step = (StubStep | RequestStep | InsertStep | SqlStep | DbStep | ReceivedStep | ChangesStep | CheckpointStep | LogStep | SnapshotStep) & {
+export type Step = (StubStep | RequestStep | InsertStep | SqlStep | DbStep | ReceivedStep | ChangesStep | CheckpointStep | LogStep | SnapshotStep | MailStep) & {
     line: number;
     name?: string;
 };
@@ -55,8 +57,11 @@ export interface RequestStep {
     form?: Record<string, unknown>;
     body?: string;
     follow?: boolean;
+    /** Send the request this many times at once. `expect` applies to every response; `statuses` counts them. */
+    concurrency?: number;
     expect?: {
         status?: number;
+        statuses?: Record<string, number>;
         headers?: Record<string, unknown>;
         json?: unknown;
         text?: unknown;
@@ -129,6 +134,24 @@ export interface SnapshotStep {
     /** Keys whose values are masked in addition to dates and UUIDs. */
     mask?: string[];
 }
+/**
+ * The app sent mail matching `mail:` (strings are exact addresses for to/from and substrings
+ * otherwise; `{ $regex }` also works). Waits up to `within` ms (default 5000). `capture` reads
+ * the last match: `subject`, `text`, `links.0`.
+ */
+export interface MailStep {
+    mail: {
+        to?: unknown;
+        from?: unknown;
+        subject?: unknown;
+        text?: unknown;
+        html?: unknown;
+    };
+    /** Exact number of matching messages. Default: at least one. */
+    times?: number;
+    within?: number;
+    capture?: Record<string, string>;
+}
 export declare class YamlScenarioError extends Error {
 }
 export declare function parseScenarioFile(text: string, file: string): YamlFile;