slicetest 0.2.0 → 0.4.0

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

@@ -4,6 +4,18 @@ interface Operation {
     method: string;
     op: Record<string, any>;
 }
+export interface OperationSketch {
+    method: string;
+    template: string;
+    summary?: string;
+    pathParams: Record<string, unknown>;
+    query: Record<string, unknown>;
+    json?: unknown;
+    /** Documented response keys, e.g. `201`, `4XX`, `default`. */
+    responses: string[];
+    /** Top-level properties of the first 2xx JSON response. */
+    createdFields: string[];
+}
 export interface Message {
     status?: number;
     contentType?: string;
@@ -40,6 +52,12 @@ export declare class OpenApiSpec {
         headers?: Record<string, string>;
         body?: unknown;
     } | undefined;
+    /**
+     * Every operation with what it takes to call it: sample values for its
+     * required path and query parameters and for its JSON request body, and the
+     * properties of its first 2xx JSON response. Used by `slicetest gen`.
+     */
+    operations(): OperationSketch[];
     /** Problems with a request the app sent to `method path`. */
     checkRequest(method: string, path: string, req: Message): string[];
 }
@@ -51,6 +69,7 @@ export declare function formatCoverage(spec: OpenApiSpec, hits: Set<string>): {
     covered: number;
     total: number;
     percent: number;
+    markdown: string;
     text: string;
 };
 export {};

package/dist/openapi.js

@@ -128,6 +128,38 @@ export class OpenApiSpec {
                 : this.#sample(m.schema);
         return { status, headers: { "content-type": media === "*/*" ? "application/json" : media }, body: isJson(media) ? body : String(body ?? "") };
     }
+    /**
+     * Every operation with what it takes to call it: sample values for its
+     * required path and query parameters and for its JSON request body, and the
+     * properties of its first 2xx JSON response. Used by `slicetest gen`.
+     */
+    operations() {
+        return this.#documentOrder.map(({ template, method, op }) => {
+            const params = [...(this.doc.paths[template].parameters ?? []), ...(op.parameters ?? [])].map((p) => this.#deref(p)).filter(Boolean);
+            const sample = (p) => (p.example !== undefined ? p.example : p.schema ? this.#sample(p.schema) : "1");
+            const pathParams = Object.fromEntries(params.filter((p) => p.in === "path").map((p) => [p.name, sample(p)]));
+            const query = Object.fromEntries(params.filter((p) => p.in === "query" && p.required).map((p) => [p.name, sample(p)]));
+            const body = this.#deref(op.requestBody);
+            const media = body?.content && Object.keys(body.content).find(isJson);
+            const m = media ? body.content[media] : undefined;
+            const json = m ? (m.example !== undefined ? m.example : this.#sample(m.schema)) : undefined;
+            const responses = Object.keys(op.responses ?? {});
+            const ok = responses.filter((k) => /^2/.test(k)).sort()[0];
+            const okContent = ok ? this.#deref(op.responses[ok])?.content : undefined;
+            const okMedia = okContent && Object.keys(okContent).find(isJson);
+            const okSchema = okMedia ? this.#deref(okContent[okMedia]?.schema) : undefined;
+            return {
+                method: method.toUpperCase(),
+                template,
+                summary: op.summary ?? op.operationId,
+                pathParams,
+                query,
+                json: json ?? undefined,
+                responses,
+                createdFields: okSchema?.properties ? Object.keys(okSchema.properties) : [],
+            };
+        });
+    }
     /** A value that satisfies `schema` (as far as a simple walk can): examples, defaults, enums, then types. */
     #sample(schema, depth = 0) {
         const s = this.#deref(schema);
@@ -274,7 +306,17 @@ export function formatCoverage(spec, hits) {
     });
     const covered = keys.filter((k) => hits.has(k)).length;
     const percent = keys.length ? Math.round((covered / keys.length) * 100) : 100;
-    return { covered, total: keys.length, percent, text: `slicetest: OpenAPI coverage (${spec.file}): ${covered}/${keys.length} documented responses (${percent}%)\n${lines.join("\n")}` };
+    const markdown = [
+        `### slicetest: OpenAPI coverage ${percent}%`,
+        "",
+        `${covered} of ${keys.length} documented responses in \`${spec.file}\` were produced by a scenario.`,
+        "",
+        "| Operation | Responses |",
+        "|---|---|",
+        ...[...byOp].map(([op, statuses]) => `| \`${op}\` | ${statuses.map((s) => `${hits.has(`${op} ${s}`) ? "✅" : "❌"} ${s}`).join(" ")} |`),
+        "",
+    ].join("\n");
+    return { covered, total: keys.length, percent, markdown, text: `slicetest: OpenAPI coverage (${spec.file}): ${covered}/${keys.length} documented responses (${percent}%)\n${lines.join("\n")}` };
 }
 function isJson(media) {
     return /[/+]json$/i.test(media) || media === "*/*";

package/dist/provided.d.ts

@@ -7,6 +7,8 @@ declare module "vitest" {
             template: string;
             prefix: string;
             coverageDir?: string;
+            recordDir?: string;
+            ciDir?: string;
         };
     }
 }

package/dist/record-cli.d.ts

@@ -0,0 +1,6 @@
+import { type SlicetestOptions } from "./config.js";
+/** The main-process side of `npx slicetest record`: run the session, tell the user where to send requests, stop on Enter. */
+export declare function record(configPath: string, options: SlicetestOptions, { out, port }: {
+    out?: string;
+    port?: number;
+}): Promise<void>;

package/dist/record-cli.js

@@ -0,0 +1,93 @@
+import { existsSync } from "node:fs";
+import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { createInterface } from "node:readline";
+import { fileURLToPath } from "node:url";
+import { resolveOptions } from "./config.js";
+import { SESSION_ENV } from "./record.js";
+const ext = path.extname(fileURLToPath(import.meta.url));
+const sessionFile = fileURLToPath(new URL(`./record-session${ext}`, import.meta.url));
+/** The main-process side of `npx slicetest record`: run the session, tell the user where to send requests, stop on Enter. */
+export async function record(configPath, options, { out, port = 0 }) {
+    const root = path.dirname(configPath);
+    const stamp = new Date().toISOString().replace(/[-:]/g, "").replace("T", "-").slice(0, 15);
+    const file = path.resolve(root, out ?? path.join("scenarios", `recorded-${stamp}.scenario.yaml`));
+    if (existsSync(file))
+        throw new Error(`slicetest record: ${path.relative(process.cwd(), file)} already exists. Pass --out <file>.`);
+    if (!Number.isInteger(port) || port < 0 || port > 65535)
+        throw new Error(`slicetest record: --port must be a port number, got ${port}`);
+    await mkdir(path.dirname(file), { recursive: true });
+    const dir = await mkdtemp(path.join(os.tmpdir(), "slicetest-record-"));
+    const session = {
+        stateFile: path.join(dir, "state.json"),
+        stopFile: path.join(dir, "stop"),
+        out: file,
+        port,
+        stubs: resolveOptions(options, root).stubs,
+    };
+    process.env[SESSION_ENV] = JSON.stringify(session);
+    const stop = () => void writeFile(session.stopFile, "").catch(() => { });
+    process.once("SIGINT", stop);
+    const { startVitest } = await import("vitest/node");
+    const { slicetest } = await import("./vitest.js");
+    const announce = watchState(session.stateFile, (state) => {
+        process.stdout.write(`\nRecording. Use the app through ${state.url} (it forwards to ${state.app}).\n` +
+            "Everything it does is captured: responses, calls to stubs, database changes.\n" +
+            "Press Enter (or Ctrl+C) to finish and write the scenario.\n\n");
+        const rl = createInterface({ input: process.stdin });
+        rl.once("line", () => {
+            rl.close();
+            stop();
+        });
+        process.stdin.once("end", stop);
+    });
+    try {
+        const vitest = await startVitest([], { config: false, root, include: [sessionFile.replace(/\\/g, "/")], exclude: [], watch: false, run: true, reporters: ["dot"] }, { plugins: [slicetest(options)] });
+        await vitest?.close();
+        const state = existsSync(session.stateFile) ? JSON.parse(await readFile(session.stateFile, "utf8")) : {};
+        if (!state.done || !state.summary) {
+            process.stderr.write("slicetest record: the session ended before anything was written (see the output above).\n");
+            process.exitCode = 1;
+            return;
+        }
+        // The session is written; a failure after it (e.g. an unmatched stub call) is reported in the file's header.
+        process.exitCode = 0;
+        const s = state.summary;
+        process.stdout.write(`\nWrote ${path.relative(process.cwd(), file)}: ${s.requests} request(s), ${s.stubs} stub route(s), changes in ${s.tables.length ? s.tables.join(", ") : "no tables"}.\n` +
+            (s.skippedAssets ? `Left out ${s.skippedAssets} request(s) for static files.\n` : "") +
+            (s.unanswered.length ? `Calls no stub answered (see the file's header): ${s.unanswered.join(", ")}\n` : "") +
+            `Replay it with: npx slicetest ${path.relative(root, file).replace(/\\/g, "/")}\n`);
+    }
+    finally {
+        announce.cancel();
+        process.off("SIGINT", stop);
+        // The Enter listener would otherwise keep the process alive.
+        process.stdin.destroy();
+        delete process.env[SESSION_ENV];
+        await rm(dir, { recursive: true, force: true });
+    }
+}
+function watchState(file, onReady) {
+    let cancelled = false;
+    void (async () => {
+        while (!cancelled) {
+            if (existsSync(file)) {
+                try {
+                    const state = JSON.parse(await readFile(file, "utf8"));
+                    if (state.url)
+                        return onReady(state);
+                }
+                catch {
+                    // Partly written; read it again.
+                }
+            }
+            await new Promise((r) => setTimeout(r, 100));
+        }
+    })();
+    return {
+        cancel: () => {
+            cancelled = true;
+        },
+    };
+}

package/dist/record-session.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/record-session.js

@@ -0,0 +1,10 @@
+/**
+ * The test file `npx slicetest record` runs: one scenario that lasts until the
+ * user is done, so the session gets the same app, database and stubs as tests.
+ */
+import { SESSION_ENV, runSession } from "./record.js";
+import { scenario } from "./scenario.js";
+const session = JSON.parse(process.env[SESSION_ENV] ?? "null");
+if (!session)
+    throw new Error("slicetest: this file is run by `npx slicetest record`");
+scenario("slicetest record", (ctx) => runSession(ctx, session), 24 * 60 * 60 * 1000);

package/dist/record.d.ts

@@ -0,0 +1,46 @@
+import type { Changes } from "./db.js";
+import type { ScenarioContext } from "./runtime.js";
+import type { RecordedCall } from "./stub.js";
+/**
+ * `npx slicetest record`: use the app for real (a browser, curl, a mobile
+ * client) through a proxy, and get the session back as a YAML scenario: the
+ * requests, the responses to expect, the stubbed services' replies and the
+ * database changes. The session runs as one long scenario, so the app, the
+ * database and the stubs are the same ones the tests use.
+ */
+/** Passed from the CLI to the session through the environment. */
+export interface RecordSession {
+    /** Written by the session: `{ "url": … }` once the proxy listens, `{ "done": … }` at the end. */
+    stateFile: string;
+    /** Created by the CLI when the user is done. */
+    stopFile: string;
+    out: string;
+    port: number;
+    stubs: string[];
+}
+export declare const SESSION_ENV = "SLICETEST_RECORD_SESSION";
+export interface Exchange {
+    method: string;
+    path: string;
+    contentType?: string;
+    body: string;
+    status: number;
+    responseType?: string;
+    response: string;
+}
+export declare function runSession(ctx: ScenarioContext, session: RecordSession): Promise<void>;
+export interface Summary {
+    requests: number;
+    skippedAssets: number;
+    stubs: number;
+    tables: string[];
+    unanswered: string[];
+}
+/** The recorded session as a YAML scenario, with a comment header of what to review. */
+export declare function buildScenario(exchanges: Exchange[], calls: Record<string, RecordedCall[]>, changes: Changes, { name, now }?: {
+    name?: string | undefined;
+    now?: Date | undefined;
+}): {
+    yaml: string;
+    summary: Summary;
+};