slicetest 0.9.0 → 0.10.0

package/dist/openapi.js

@@ -112,7 +112,8 @@ export class OpenApiSpec {
         if (!key)
             return [`${method} ${template} responded ${status}, which ${this.file} doesn't document (documented: ${Object.keys(responses).join(", ") || "none"})`];
         const [response, at] = this.#resolve(responses[key], ["paths", template, found.method, "responses", key]);
-        return this.#checkContent(response?.content, res, [...at, "content"], `${method} ${template} → ${status}`);
+        const label = `${method} ${template} → ${status}`;
+        return [...this.#checkHeaders(label, response?.headers, [...at, "headers"], res.headers), ...this.#checkContent(response?.content, res, [...at, "content"], label)];
     }
     /**
      * A response the real service could send to `method path`: the lowest
@@ -133,8 +134,13 @@ export class OpenApiSpec {
         const response = this.#deref(responses[key]);
         const content = response?.content ?? {};
         const media = Object.keys(content).find(isJson) ?? Object.keys(content)[0];
+        // The headers the spec requires, so the example passes the same check the stub's replies are held to.
+        const required = Object.fromEntries(Object.entries(response?.headers ?? {})
+            .map(([name, def]) => [name, this.#deref(def)])
+            .filter(([name, h]) => h?.required && !["content-type", "accept", "authorization"].includes(name.toLowerCase()))
+            .map(([name, h]) => [name, String(h.example !== undefined ? h.example : this.#sample(h.schema))]));
         if (!media)
-            return { status };
+            return { status, ...(Object.keys(required).length ? { headers: required } : {}) };
         const m = content[media] ?? {};
         const named = m.examples && Object.values(m.examples)[0];
         const body = m.example !== undefined
@@ -142,7 +148,7 @@ export class OpenApiSpec {
             : named !== undefined
                 ? (this.#deref(named)?.value ?? null)
                 : this.#sample(m.schema);
-        return { status, headers: { "content-type": media === "*/*" ? "application/json" : media }, body: isJson(media) ? body : String(body ?? "") };
+        return { status, headers: { "content-type": media === "*/*" ? "application/json" : media, ...required }, body: isJson(media) ? body : String(body ?? "") };
     }
     /**
      * Every operation with what it takes to call it: sample values for its
@@ -220,10 +226,14 @@ export class OpenApiSpec {
             case "object":
                 return Object.fromEntries(Object.entries(s.properties ?? {}).map(([k, v]) => [k, this.#sample(v, depth + 1)]));
             case "array":
-                return Array.from({ length: Math.max(1, s.minItems ?? 1) }, () => this.#sample(s.items, depth + 1));
+                return Array.from({ length: Math.max(1, s.minItems ?? 1) }, (_, i) => {
+                    const items = this.#deref(s.items);
+                    // Equal items would break `uniqueItems`.
+                    return s.uniqueItems && Array.isArray(items?.enum) && items.enum.length ? items.enum[i % items.enum.length] : this.#sample(s.items, depth + 1);
+                });
             case "integer":
             case "number":
-                return typeof s.minimum === "number" ? s.minimum : typeof s.exclusiveMinimum === "number" ? s.exclusiveMinimum + 1 : 0;
+                return sampleNumber(s, type === "integer");
             case "boolean":
                 return true;
             case "string":
@@ -239,10 +249,23 @@ export class OpenApiSpec {
             return [`${method} ${path} is not in ${this.file}`];
         const { template, op } = found;
         const errors = [];
-        const params = [...(this.doc.paths[template].parameters ?? []), ...(op.parameters ?? [])].map((p) => this.#deref(p));
-        for (const p of params) {
-            if (p?.in === "query" && p.required && !req.query?.has(p.name))
-                errors.push(`${method} ${template}: required query parameter "${p.name}" is missing`);
+        const listed = [
+            ...(this.doc.paths[template].parameters ?? []).map((p, i) => this.#resolve(p, ["paths", template, "parameters", String(i)])),
+            ...(op.parameters ?? []).map((p, i) => this.#resolve(p, ["paths", template, found.method, "parameters", String(i)])),
+        ];
+        for (const [p, at] of listed) {
+            if (p?.in === "query") {
+                if (p.required && !this.#sentQuery(p, req.query))
+                    errors.push(`${method} ${template}: required query parameter "${p.name}" is missing`);
+                const values = req.query?.getAll(p.name) ?? [];
+                if (values.length && p.schema)
+                    errors.push(...this.#checkValues(`${method} ${template}`, `query parameter "${p.name}"`, values, p.schema, [...at, "schema"]));
+            }
+            // Authorization, Accept and Content-Type are the transport's business, whatever the spec lists.
+            const skipped = ["authorization", "accept", "content-type"];
+            if (p?.in === "header" && p.required && req.headers && !skipped.includes(p.name.toLowerCase()) && req.headers[p.name.toLowerCase()] === undefined) {
+                errors.push(`${method} ${template}: required header "${p.name}" is missing`);
+            }
         }
         const [body, at] = this.#resolve(op.requestBody, ["paths", template, found.method, "requestBody"]);
         if (!body)
@@ -254,6 +277,59 @@ export class OpenApiSpec {
         }
         return [...errors, ...this.#checkContent(body.content, req, [...at, "content"], `${method} ${template} request`)];
     }
+    /** Whether the request carries query parameter `p`, also as `name[key]` (deepObject) or as its properties (an exploded form object). */
+    #sentQuery(p, query) {
+        if (!query)
+            return false;
+        if (query.has(p.name))
+            return true;
+        const keys = [...query.keys()];
+        if (p.style === "deepObject")
+            return keys.some((k) => k.startsWith(`${p.name}[`));
+        const schema = this.#deref(p.schema);
+        const props = schema?.type === "object" && (p.style ?? "form") === "form" && p.explode !== false ? Object.keys(schema.properties ?? {}) : [];
+        return props.some((k) => query.has(k));
+    }
+    /** A query parameter's or header's values as strings, held to its schema after reading them as the type it declares. */
+    #checkValues(label, subject, values, schema, pointer) {
+        const [node, at] = this.#resolve(schema, pointer);
+        const one = (raw, node, at, where) => {
+            if (!["string", "integer", "number", "boolean"].includes(node?.type) && !node?.enum)
+                return [];
+            const validate = this.#validator(at);
+            const value = (node.type === "integer" || node.type === "number") && raw.trim() !== "" && Number.isFinite(Number(raw)) ? Number(raw) : node.type === "boolean" && (raw === "true" || raw === "false") ? raw === "true" : raw;
+            if (validate(value))
+                return [];
+            return [`${label}: ${subject}${where} ${validate.errors[0].message} (got ${JSON.stringify(raw)})`];
+        };
+        if (node?.type !== "array")
+            return one(values[0], node, at, "");
+        const [items, itemsAt] = this.#resolve(node.items, [...at, "items"]);
+        // One value may carry the whole list (`?ids=1,2`, explode: false). Many servers accept it for the exploded default too, so it isn't held against the spec.
+        const list = values.length > 1 ? values : values.flatMap((v) => v.split(","));
+        return list.flatMap((raw, i) => one(raw, items, itemsAt, ` item ${i + 1}`));
+    }
+    /** The headers a response documents: the required ones must be there, and what is there must fit its schema. */
+    #checkHeaders(label, documented, at, actual) {
+        if (!documented || !actual)
+            return [];
+        const errors = [];
+        for (const [name, def] of Object.entries(documented)) {
+            // The spec says to ignore these three when they are listed.
+            if (["content-type", "accept", "authorization"].includes(name.toLowerCase()))
+                continue;
+            const [h, hat] = this.#resolve(def, [...at, name]);
+            const raw = actual[name.toLowerCase()];
+            if (raw === undefined) {
+                if (h?.required)
+                    errors.push(`${label}: required header "${name}" is missing`);
+            }
+            else if (h?.schema) {
+                errors.push(...this.#checkValues(label, `header "${name}"`, [Array.isArray(raw) ? raw.join(", ") : raw], h.schema, [...hat, "schema"]));
+            }
+        }
+        return errors;
+    }
     #checkContent(content, msg, pointer, label) {
         if (!content || Object.keys(content).length === 0)
             return [];
@@ -261,9 +337,11 @@ export class OpenApiSpec {
         // Without a content-type (e.g. a stub replying with a bare string) there's nothing to hold the body to.
         if (!type)
             return [];
-        const media = Object.keys(content).find((k) => k.toLowerCase() === type) ??
-            Object.keys(content).find((k) => k.endsWith("/*") && type.startsWith(k.slice(0, -1))) ??
-            Object.keys(content).find((k) => k === "*/*");
+        // A spec may write the key with parameters (`application/json; charset=utf-8`); the type alone decides.
+        const bare = (k) => k.split(";")[0].trim().toLowerCase();
+        const media = Object.keys(content).find((k) => bare(k) === type) ??
+            Object.keys(content).find((k) => bare(k).endsWith("/*") && type.startsWith(bare(k).slice(0, -1))) ??
+            Object.keys(content).find((k) => bare(k) === "*/*");
         if (!media)
             return [`${label}: content-type "${type || "(none)"}" is not one of ${Object.keys(content).join(", ")}`];
         if (!content[media]?.schema || !isJson(media))
@@ -313,9 +391,38 @@ const FORMATS = {
     ipv6: "2001:db8::1",
 };
 function sampleString(s) {
-    const base = (s.format && FORMATS[s.format]) ?? "string";
+    let base = (s.format && FORMATS[s.format]) ?? "string";
+    // A cut-off date or address would break its format as much as the length, so only plain strings are shortened.
+    if (!s.format && s.maxLength !== undefined && base.length > s.maxLength)
+        base = base.slice(0, s.maxLength);
     return base.length >= (s.minLength ?? 0) ? base : base.padEnd(s.minLength, "x");
 }
+/** A number inside the schema's bounds (3.0's `exclusiveMinimum: true` and 3.1's numeric form), on its `multipleOf` step. */
+function sampleNumber(s, integer) {
+    const bound = (value, exclusive) => {
+        if (typeof s[exclusive] === "number")
+            return { at: s[exclusive], open: true };
+        if (typeof s[value] === "number")
+            return { at: s[value], open: s[exclusive] === true };
+        return undefined;
+    };
+    const lo = bound("minimum", "exclusiveMinimum");
+    const hi = bound("maximum", "exclusiveMaximum");
+    let n = 0;
+    if (lo)
+        n = lo.open ? lo.at + 1 : lo.at;
+    else if (hi)
+        n = hi.open ? hi.at - 1 : Math.min(0, hi.at);
+    // The step past an open lower bound can overshoot a close upper one.
+    if (lo && hi && (hi.open ? n >= hi.at : n > hi.at))
+        n = lo.open ? (lo.at + hi.at) / 2 : lo.at;
+    if (typeof s.multipleOf === "number" && s.multipleOf > 0) {
+        n = Math.ceil(n / s.multipleOf) * s.multipleOf;
+        if (lo?.open && n <= lo.at)
+            n += s.multipleOf;
+    }
+    return integer ? Math.ceil(n) : n;
+}
 function pickResponse(responses, status) {
     const s = String(status);
     return [s, `${s[0]}XX`, `${s[0]}xx`, "default"].find((k) => k in responses);
@@ -353,7 +460,8 @@ export function formatCoverage(spec, hits) {
     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 === "*/*";
+    const type = media.split(";")[0].trim();
+    return /[/+]json$/i.test(type) || type === "*/*";
 }
 function escape(s) {
     return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
@@ -366,6 +474,17 @@ export function nullableToType(node) {
         return node;
     for (const [k, v] of Object.entries(node))
         node[k] = nullableToType(v);
+    // 3.0 writes `minimum: 0, exclusiveMinimum: true`; JSON Schema (and Ajv) want `exclusiveMinimum: 0`.
+    for (const [flag, bound] of [["exclusiveMinimum", "minimum"], ["exclusiveMaximum", "maximum"]]) {
+        if (typeof node[flag] !== "boolean")
+            continue;
+        if (node[flag] && typeof node[bound] === "number") {
+            node[flag] = node[bound];
+            delete node[bound];
+        }
+        else
+            delete node[flag];
+    }
     if (node.nullable === true) {
         if (node.enum && !node.enum.includes(null))
             node.enum = [...node.enum, null];

package/dist/record-cli.js

@@ -4,6 +4,7 @@ import os from "node:os";
 import path from "node:path";
 import { createInterface } from "node:readline";
 import { fileURLToPath } from "node:url";
+import { compatStart } from "./cli-run.js";
 import { resolveOptions } from "./config.js";
 import { SESSION_ENV } from "./record.js";
 const ext = path.extname(fileURLToPath(import.meta.url));
@@ -29,7 +30,7 @@ export async function record(configPath, options, { out, port = 0 }) {
     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 startVitest = compatStart(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` +

package/dist/record.js

@@ -5,6 +5,7 @@ import path from "node:path";
 import { stringify } from "yaml";
 import { parseForm } from "./stub.js";
 import { mask } from "./trace.js";
+import { requestUrl } from "./request-url.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;
@@ -27,7 +28,7 @@ export async function runSession(ctx, session) {
                 headers.append(k, value);
         }
         try {
-            const upstream = await fetch(new URL(req.url ?? "/", target), {
+            const upstream = await fetch(requestUrl(req.url, target), {
                 method: req.method,
                 headers,
                 body: body.length && req.method !== "GET" && req.method !== "HEAD" ? body : undefined,

package/dist/recording.d.ts

@@ -1,10 +1,11 @@
 import type { RecordedCall, StubResponse } from "./stub.js";
 /** One recorded exchange with the real service, as stored in the recordings file. */
 export interface Recording {
+    /** A parameter sent more than once (`?ids=1&ids=2`) is a list of its values, in order. */
     request: {
         method: string;
         path: string;
-        query?: Record<string, string>;
+        query?: Record<string, string | string[]>;
         json?: unknown;
         body?: string;
     };
@@ -38,6 +39,8 @@ export declare class Recorder {
     /** Recordings made by this worker, to be merged into the file when the run ends. */
     added(): Recording[];
 }
+/** Query parameters by name, sorted; a repeated one as the list of its values. */
+export declare function queryOf(params: URLSearchParams): Record<string, string | string[]>;
 export declare const REDACTED = "[redacted]";
 /**
  * A request with credential values replaced by `[redacted]`, so recordings can be committed and

package/dist/recording.js

@@ -88,8 +88,15 @@ export class Recorder {
         };
     }
 }
+/** Query parameters by name, sorted; a repeated one as the list of its values. */
+export function queryOf(params) {
+    return Object.fromEntries([...new Set(params.keys())].sort((a, b) => a.localeCompare(b)).map((k) => {
+        const all = params.getAll(k);
+        return [k, all.length > 1 ? all : all[0]];
+    }));
+}
 function requestOf(call) {
-    const query = Object.fromEntries([...call.query.entries()].sort(([a], [b]) => a.localeCompare(b)));
+    const query = queryOf(call.query);
     return redactRequest({
         method: call.method,
         path: call.path,
@@ -111,7 +118,7 @@ const FORM_BODY = /^[^\s=&]+=[^\s&]*(&[^\s=&]+=[^\s&]*)*$/;
 export function redactRequest(r) {
     const out = { ...r };
     if (r.query)
-        out.query = Object.fromEntries(Object.entries(r.query).map(([k, v]) => [k, SECRET.test(k) ? REDACTED : v]));
+        out.query = Object.fromEntries(Object.entries(r.query).map(([k, v]) => [k, !SECRET.test(k) ? v : Array.isArray(v) ? v.map(() => REDACTED) : REDACTED]));
     if (r.json !== undefined)
         out.json = redactJson(r.json);
     if (r.body && FORM_BODY.test(r.body)) {
@@ -142,7 +149,11 @@ function sortKeys(v) {
     return v;
 }
 function toResponse(e) {
-    return { status: e.response.status, headers: e.response.headers, body: e.response.json !== undefined ? e.response.json : (e.response.body ?? "") };
+    const { status, headers, json, body } = e.response;
+    // A string is sent as it is; a JSON string reply (`"ok"`) needs its quotes back.
+    if (typeof json === "string")
+        return { status, headers: { "content-type": "application/json", ...headers }, body: JSON.stringify(json) };
+    return { status, headers, body: json !== undefined ? json : (body ?? "") };
 }
 function parse(text) {
     if (!text)

package/dist/request-url.d.ts

@@ -0,0 +1 @@
+export declare function requestUrl(target: string | undefined, base: string | URL): URL;

package/dist/request-url.js

@@ -0,0 +1,5 @@
+// Not `new URL(target, base)`: for `//users/42` that reads `users` as a host, and the path is lost.
+export function requestUrl(target, base) {
+    const raw = target ?? "/";
+    return raw.startsWith("/") ? new URL(new URL(base).origin + raw) : new URL(raw, base);
+}

package/dist/runtime.d.ts

@@ -1,6 +1,6 @@
 import { App } from "./app.js";
 import { Issuer } from "./auth.js";
-import type { ResolvedOptions } from "./config.js";
+import { type ResolvedOptions } from "./config.js";
 import { Dependency } from "./containers.js";
 import { connectionVars } from "./connection.js";
 import { Db } from "./db.js";
@@ -63,8 +63,8 @@ export declare class Runtime {
     }): Promise<Runtime>;
     context(): ScenarioContext;
     beforeScenario(): Promise<void>;
-    /** Failures that the scenario body can't see on its own. */
-    afterScenario(): Promise<void>;
+    /** `deadline`: when the test's own timeout is about to end, so `idle` reports before Vitest does. */
+    afterScenario(deadline?: number): Promise<void>;
     /** The current scenario as a Mermaid sequence diagram. */
     diagram(): Promise<string>;
     /**

package/dist/runtime.js

@@ -4,6 +4,7 @@ import os from "node:os";
 import path from "node:path";
 import { App } from "./app.js";
 import { Issuer } from "./auth.js";
+import { seedFiles } from "./config.js";
 import { Dependency } from "./containers.js";
 import { connectionVars } from "./connection.js";
 import { Db, formatChanges, noDatabase } from "./db.js";
@@ -125,7 +126,7 @@ export class Runtime {
                     schemas: opts.db.schemas,
                     keep: opts.db.keep,
                     ignoreChanges: opts.db.ignoreChanges,
-                    seedFile: opts.db.seed && path.resolve(opts.root, opts.db.seed),
+                    seedFiles: seedFiles(opts.db.seed).map((f) => path.resolve(opts.root, f)),
                 })
                 : noDatabase();
             const started = await Promise.allSettled(Object.entries(opts.containers).map(async ([name, c]) => containers.set(name, await Dependency.start(name, c))));
@@ -234,7 +235,7 @@ 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(), this.mailbox), opts),
+            trace: async (opts) => mask(buildTrace(this.http.requests, this.stubs.values(), await this.db.changesSinceStart(), this.mailbox), opts),
             diagram: () => this.diagram(),
             get mail() {
                 if (!mailbox)
@@ -252,6 +253,34 @@ export class Runtime {
     #processes() {
         return [this.app, ...this.services.values()];
     }
+    // Marked busy until afterScenario() sees `idle` answer 2xx, so a scenario that failed, or that Vitest
+    // timed out mid-wait, leaves its processes flagged and the next scenario restarts them.
+    #busy = new Set();
+    #queue = Promise.resolve();
+    /** Not concurrent: a scenario Vitest timed out leaves its beforeScenario() running, and a second would race it for `this.app`. */
+    #serial(fn) {
+        const run = this.#queue.then(fn);
+        this.#queue = run.catch(() => { });
+        return run;
+    }
+    #hooked(hook) {
+        const all = [
+            { name: "app", proc: this.app, options: this.opts.app },
+            ...[...this.services].map(([n, proc]) => ({ name: `services.${n}`, proc, options: this.opts.services[n] })),
+        ];
+        return all.filter((p) => p.options[hook] && !p.proc.exited);
+    }
+    /** Every busy process fails the scenario, not only the first, and each is flagged for a restart. */
+    async #waitIdle(deadline) {
+        const hooked = this.#hooked("idle");
+        const results = await Promise.allSettled(hooked.map(async ({ name, proc, options }) => {
+            await pollIdle(proc, options.idle, `${name}.idle`, deadline);
+            this.#busy.delete(proc);
+        }));
+        const failed = results.flatMap((r) => (r.status === "rejected" ? [r.reason.message] : []));
+        if (failed.length > 0)
+            throw new Error(failed.join("\n"));
+    }
     #usageDir;
     /** Note which provider operations the stubs were called for, before their calls are cleared. */
     #collectUsage() {
@@ -266,20 +295,30 @@ export class Runtime {
                 this.#used.set(name, used);
         }
     }
-    async beforeScenario() {
+    beforeScenario() {
+        return this.#serial(() => this.#before());
+    }
+    /** `deadline`: when the test's own timeout is about to end, so `idle` reports before Vitest does. */
+    afterScenario(deadline) {
+        return this.#serial(() => this.#after(deadline));
+    }
+    async #before() {
         this.#collectUsage();
-        // A crash already failed the scenario that caused it; give the next one a fresh process.
-        for (const [name, service] of this.services) {
-            if (!service.exited)
-                continue;
-            await service.stop();
-            this.services.set(name, await App.start(this.opts.services[name], this.opts.root, this.vars, `service.${name}`, service.port));
+        // A failed scenario skipped afterScenario(). One look, not a wait: it already failed, and a restart ends the work.
+        for (const { proc, options } of this.#hooked("idle")) {
+            if (this.#busy.has(proc) && (await probeIdle(proc, options.idle)))
+                this.#busy.delete(proc);
         }
-        if (this.app.exited) {
+        // Stop before the reset, start after. Not start-then-reset: the old process could still write into the
+        // fresh database, and the new one would boot against stale rows.
+        const restartService = (name, service) => service.exited || this.#busy.has(service) || this.opts.services[name].restart === "scenario";
+        const services = [...this.services].filter(([name, service]) => restartService(name, service));
+        const restartApp = !!this.app.exited || this.#busy.has(this.app) || this.opts.app.restart === "scenario";
+        if (restartApp)
             await this.app.stop();
-            this.app = await App.start(this.opts.app, this.opts.root, this.vars);
-            this.#http = this.#client();
-        }
+        for (const [, service] of [...services].reverse())
+            await service.stop();
+        this.#busy.clear();
         this.#contract = [];
         await this.db.reset();
         for (const stub of this.stubs.values())
@@ -293,13 +332,27 @@ export class Runtime {
         this.interceptor?.blocked.clear();
         await Promise.all([...this.containers.values()].map((c) => c.reset()));
         this.http.reset();
+        for (const [name, old] of services) {
+            this.services.set(name, await App.start(this.opts.services[name], this.opts.root, this.vars, `service.${name}`, old.port));
+        }
+        if (restartApp) {
+            this.app = await App.start(this.opts.app, this.opts.root, this.vars);
+            this.#http = this.#client();
+        }
         for (const p of this.#processes())
             p.beginScenario();
+        // Not before the start: a cache filled at boot would hold the pre-reset rows.
+        for (const { name, proc, options } of this.#hooked("reset")) {
+            await callHook(proc, options.reset, `${name}.reset`);
+        }
+        for (const { proc } of this.#hooked("idle"))
+            this.#busy.add(proc);
     }
     /** Failures that the scenario body can't see on its own. */
-    async afterScenario() {
+    async #after(deadline) {
         await Promise.all(this.#processes().map((p) => p.settle()));
         this.#assertAlive();
+        await this.#waitIdle(deadline);
         if (this.interceptor?.blocked.size)
             throw new Error(blockedHint([...this.interceptor.blocked]));
         const thrown = this.#handlerErrors();
@@ -340,12 +393,12 @@ export class Runtime {
     #checkStubCall(name, spec, call) {
         if (!call.matched)
             return []; // already reported as an unmatched call
-        const req = { contentType: header(call.headers["content-type"]), body: call.json ?? call.body, query: call.query };
+        const req = { contentType: header(call.headers["content-type"]), body: call.json ?? call.body, query: call.query, headers: call.headers };
         const out = spec.checkRequest(call.method, call.path, req).map((c) => `app → ${name}: ${c}`);
         const res = call.response;
         if (res) {
             const body = res.body ? (parseJson(res.body) ?? res.body) : "";
-            const problems = spec.checkResponse(call.method, call.path, { status: res.status, contentType: res.headers["content-type"], body });
+            const problems = spec.checkResponse(call.method, call.path, { status: res.status, contentType: res.headers["content-type"], body, headers: Object.fromEntries(Object.entries(res.headers).map(([k, v]) => [k.toLowerCase(), v])) });
             out.push(...problems.map((c) => `stub ${name} reply (the real service wouldn't answer this way): ${c}`));
         }
         return out;
@@ -375,7 +428,7 @@ export class Runtime {
     /** The current scenario as a Mermaid sequence diagram. */
     async diagram() {
         const changes = this.opts.db.none ? undefined : await this.db.changesSinceStart().catch(() => undefined);
-        return sequenceDiagram(this.http.history, this.stubs.values(), changes, this.mailbox);
+        return sequenceDiagram(this.http.requests, this.stubs.values(), changes, this.mailbox);
     }
     /**
      * After a scenario: its diagram goes to the `SLICETEST_DIAGRAMS` directory (one Markdown page
@@ -511,8 +564,69 @@ async function ensureWorkerDatabase(engine, adminUrl, template, prefix) {
         await admin.close();
     }
 }
+const HOOK_TIMEOUT = 5000;
+/** Not `new URL(path, base)` alone: `//host/x` and `/\host` would send the request to another host. */
+function hookUrl(proc, hook) {
+    const url = new URL(hook.path, proc.url);
+    if (url.origin !== new URL(proc.url).origin)
+        throw new Error(`slicetest: hook path ${JSON.stringify(hook.path)} leaves the ${proc.label} (${url.origin}); use a path on the app`);
+    return url;
+}
+async function callHook(proc, hook, where) {
+    const method = (hook.method ?? "POST").toUpperCase();
+    const what = `${method} ${hook.path}`;
+    let res;
+    try {
+        // Not following redirects: a 3xx must not move the request off the app.
+        res = await fetch(hookUrl(proc, hook), { method, redirect: "manual", signal: AbortSignal.timeout(hook.timeout ?? HOOK_TIMEOUT) });
+    }
+    catch (e) {
+        throw new Error(`slicetest: ${where}: ${what} failed: ${e.message}. The ${proc.label}'s in-process state wasn't reset, so this scenario could see the previous one's. Check that the ${proc.label} serves ${hook.path}.`);
+    }
+    const body = (await res.text().catch(() => "")).slice(0, 300);
+    if (res.status >= 300) {
+        throw new Error(`slicetest: ${where}: ${what} answered ${res.status}${body ? `: ${body}` : ""}. The ${proc.label}'s in-process state wasn't reset, so this scenario could see the previous one's.`);
+    }
+}
+/** One request: is the process idle right now. */
+async function probeIdle(proc, hook) {
+    try {
+        const res = await fetch(hookUrl(proc, hook), { method: (hook.method ?? "GET").toUpperCase(), redirect: "manual", signal: AbortSignal.timeout(1000) });
+        await res.body?.cancel();
+        return res.ok;
+    }
+    catch {
+        return false;
+    }
+}
+/** Poll `app.idle` until it answers 2xx, for `timeout` or until `deadline` (epoch ms), whichever is first. */
+async function pollIdle(proc, hook, where, deadline) {
+    const timeout = hook.timeout ?? HOOK_TIMEOUT;
+    const start = Date.now();
+    const limit = Math.min(start + timeout, deadline ?? Infinity);
+    const method = (hook.method ?? "GET").toUpperCase();
+    let last = "no answer";
+    for (;;) {
+        try {
+            const res = await fetch(hookUrl(proc, hook), { method, redirect: "manual", signal: AbortSignal.timeout(Math.max(100, Math.min(1000, limit - Date.now()))) });
+            const body = (await res.text().catch(() => "")).trim().slice(0, 200);
+            if (res.ok)
+                return;
+            last = `${res.status}${body ? ` ${body}` : ""}`;
+        }
+        catch (e) {
+            last = e.message;
+        }
+        if (Date.now() >= limit)
+            break;
+        await new Promise((r) => setTimeout(r, 50));
+    }
+    const cut = limit < start + timeout ? `; the test's own timeout left no more (raise it, or lower ${where}.timeout)` : "";
+    throw new Error(`slicetest: ${where}: the ${proc.label} still had background work after ${Date.now() - start}ms (${method} ${hook.path} last answered: ${last})${cut}. ` +
+        `Left running, it would write into a later scenario, so the ${proc.label} is restarted before the next one. Finish the work before the scenario ends, wait for it in the scenario, or raise the timeout.`);
+}
 function message(res) {
-    return { status: res.status, contentType: res.headers.get("content-type") ?? undefined, body: res.json ?? res.text };
+    return { status: res.status, contentType: res.headers.get("content-type") ?? undefined, body: res.json ?? res.text, headers: Object.fromEntries(res.headers) };
 }
 function header(v) {
     return Array.isArray(v) ? v[0] : v;

package/dist/scenario.js

@@ -1,3 +1,4 @@
+import { clearScenarioDeadline, setScenarioDeadline } from "./deadline.js";
 import { test } from "vitest";
 // Kept on globalThis so it survives the setup file and the test file loading
 // separate copies of this module (e.g. one from dist, one through an alias).
@@ -35,9 +36,17 @@ function define(register) {
                 console.error(`--- slicetest ---\n${await runtime.diagnostics()}\n-----------------`);
                 await runtime.reportDiagram(file, task.name, true);
             });
+            const started = Date.now();
             await runtime.beforeScenario();
-            await body(runtime.context());
-            await runtime.afterScenario();
+            setScenarioDeadline(started, task.timeout);
+            try {
+                await body(runtime.context());
+            }
+            finally {
+                clearScenarioDeadline();
+            }
+            // Leaves a margin for the checks after the wait, so `idle` reports before Vitest's timeout does.
+            await runtime.afterScenario(task.timeout ? started + task.timeout - 500 : undefined);
             await runtime.reportDiagram(file, task.name, false);
         }, timeout);
     };