slicetest 0.6.0 → 0.7.0

package/dist/runtime.js

@@ -1,11 +1,14 @@
 import { randomUUID } from "node:crypto";
-import { writeFile } from "node:fs/promises";
+import { mkdir, writeFile } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import { App } from "./app.js";
 import { Issuer } from "./auth.js";
 import { Dependency } from "./containers.js";
+import { connectionVars } from "./connection.js";
 import { Db, formatChanges, noDatabase } from "./db.js";
+import { diagramPage, failureDiagram, sequenceDiagram } from "./diagram.js";
+import { appendSummary } from "./ci.js";
 import { engineFor } from "./drivers/index.js";
 import { formatHistory, HttpClient } from "./http.js";
 import { Interceptor } from "./intercept.js";
@@ -39,6 +42,8 @@ export class Runtime {
     #contract = [];
     /** Documented responses seen in this file, for the run's coverage report. */
     #covered = new Set();
+    /** Operations of stubbed providers (with an `openapi` spec) the app called, per stub, for the usage report. */
+    #used = new Map();
     constructor(app, services, db, stubs, opts, vars, specs, coverageDir, recorders = new Map(), recordDir, containers = new Map(), mailbox, issuer, queryLog, interceptor, neon) {
         this.app = app;
         this.services = services;
@@ -182,7 +187,9 @@ export class Runtime {
             const app = await App.start(opts.app, opts.root, vars);
             if (opts.openapi.fromApp)
                 specs.app = await fetchAppSpec(app.url, opts.openapi.fromApp, shared.coverageDir);
-            return new Runtime(app, services, db, stubs, opts, vars, specs, shared.coverageDir, recorders, shared.recordDir, containers, mailbox, issuer, queryLog, interceptor, neon);
+            const runtime = new Runtime(app, services, db, stubs, opts, vars, specs, shared.coverageDir, recorders, shared.recordDir, containers, mailbox, issuer, queryLog, interceptor, neon);
+            runtime.#usageDir = shared.usageDir;
+            return runtime;
         }
         catch (e) {
             await Promise.all([...services.values()].map((s) => s.stop()));
@@ -227,6 +234,7 @@ export class Runtime {
                 return c;
             },
             trace: async (opts) => mask(buildTrace(this.http.history, this.stubs.values(), await this.db.changesSinceStart(), this.mailbox), opts),
+            diagram: () => this.diagram(),
             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}}.");
@@ -243,7 +251,22 @@ export class Runtime {
     #processes() {
         return [this.app, ...this.services.values()];
     }
+    #usageDir;
+    /** Note which provider operations the stubs were called for, before their calls are cleared. */
+    #collectUsage() {
+        for (const [name, spec] of this.specs.stubs) {
+            const used = this.#used.get(name) ?? new Set();
+            for (const call of this.stubs.get(name).calls()) {
+                const op = spec.operationOf(call.method, call.path);
+                if (op)
+                    used.add(op.key);
+            }
+            if (used.size)
+                this.#used.set(name, used);
+        }
+    }
     async beforeScenario() {
+        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)
@@ -286,6 +309,14 @@ export class Runtime {
         if (contract.length > 0) {
             throw new Error(`slicetest: traffic doesn't match the OpenAPI spec:\n${contract.map((c) => `  ${c}`).join("\n")}`);
         }
+        const unused = this.#unusedRoutes();
+        if (this.opts.strictStubs && unused.length > 0) {
+            throw new Error(`slicetest: stub routes the app never called (strictStubs):\n${unused.join("\n")}\n` +
+                "Remove them, check that the scenario reaches the code that calls them, or mark them .optional() (YAML: optional: true).");
+        }
+    }
+    #unusedRoutes() {
+        return [...this.stubs.values()].flatMap((s) => s.unusedRoutes().map((r) => `  ${s.name}: ${r}`));
     }
     /** The app's responses against its spec, and its calls to stubs (and the stubs' replies) against theirs. */
     #contractViolations() {
@@ -322,12 +353,45 @@ export class Runtime {
                 return [];
             const routes = s.describeRoutes();
             return [
-                ...calls.map((c) => `  ${s.name}: ${c.method} ${c.path}${c.query.size ? `?${c.query}` : ""}`),
+                ...calls.flatMap((c) => {
+                    const why = s.explain(c);
+                    return [`  ${s.name}: ${c.method} ${c.path}${c.query.size ? `?${c.query}` : ""}`, ...(why ? [`    ${why}`] : [])];
+                }),
                 `    registered on ${s.name}: ${routes.length ? routes.join(", ") : "(none)"}`,
                 ...(this.recorders.has(s.name) ? [`    ${this.recorders.get(s.name).hint()}`] : []),
             ];
         });
     }
+    /** 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);
+    }
+    /**
+     * After a scenario: its diagram goes to the `SLICETEST_DIAGRAMS` directory (one Markdown page
+     * per test file) and, when it failed on GitHub Actions, to the job summary.
+     */
+    async reportDiagram(file, scenario, failed, env = process.env) {
+        const dir = env.SLICETEST_DIAGRAMS;
+        const summary = failed && env.GITHUB_STEP_SUMMARY;
+        if (!dir && !summary)
+            return;
+        let diagram;
+        try {
+            diagram = await this.diagram();
+        }
+        catch {
+            return;
+        }
+        const rel = path.relative(this.opts.root, file).replace(/\\/g, "/");
+        if (summary)
+            await appendSummary(failureDiagram(rel, scenario, diagram), env);
+        if (dir) {
+            const out = path.resolve(this.opts.root, dir, `${rel.replace(/^(\.\.\/)+/, "")}.md`);
+            await mkdir(path.dirname(out), { recursive: true });
+            await writeFile(out, diagramPage(out, rel, scenario, diagram, failed)).catch(() => { });
+        }
+    }
     /** What happened during the current scenario, printed when it fails. */
     async diagnostics() {
         const sections = [];
@@ -339,6 +403,9 @@ export class Runtime {
         const unmatched = this.#unmatched();
         if (unmatched.length > 0)
             sections.push(`stub calls with no matching route:\n${unmatched.join("\n")}`);
+        const unused = this.#unusedRoutes();
+        if (unused.length > 0)
+            sections.push(`stub routes the app never called:\n${unused.join("\n")}`);
         const chaos = [...this.stubs.values()].map((s) => s.describeChaos()).filter((c) => c !== undefined);
         if (chaos.length > 0)
             sections.push(chaos.join("\n"));
@@ -375,6 +442,12 @@ export class Runtime {
     }
     /** Hand the coverage and recordings gathered so far to the run (merged when it ends). */
     async flush() {
+        this.#collectUsage();
+        if (this.#usageDir && this.#used.size > 0) {
+            const data = Object.fromEntries([...this.#used].map(([k, v]) => [k, [...v]]));
+            await writeFile(path.join(this.#usageDir, `${process.pid}-${randomUUID()}.json`), JSON.stringify(data)).catch(() => { });
+            this.#used.clear();
+        }
         if (this.coverageDir && this.#covered.size > 0) {
             await writeFile(path.join(this.coverageDir, `${process.pid}-${randomUUID()}.json`), JSON.stringify([...this.#covered])).catch(() => { });
             this.#covered.clear();
@@ -439,25 +512,6 @@ function parseJson(text) {
         return undefined;
     }
 }
-/**
- * The parts of the database URL, for apps that don't take one URL: JDBC (Spring's
- * `spring.datasource.url` plus username / password), or separate host / port / name settings.
- */
-export function connectionVars(engine, url, sqlitePath) {
-    if (engine === "sqlite")
-        return { "db.jdbcUrl": `jdbc:sqlite:${sqlitePath}` };
-    const u = new URL(url);
-    const port = u.port || (engine === "mysql" ? "3306" : "5432");
-    const name = decodeURIComponent(u.pathname.replace(/^\//, ""));
-    return {
-        "db.host": u.hostname,
-        "db.port": port,
-        "db.name": name,
-        "db.user": decodeURIComponent(u.username),
-        "db.password": decodeURIComponent(u.password),
-        "db.jdbcUrl": `jdbc:${engine === "mysql" ? "mysql" : "postgresql"}://${u.hostname}:${port}/${encodeURIComponent(name)}`,
-    };
-}
 /** The app's own spec, served at `route` (springdoc's /v3/api-docs, FastAPI's /openapi.json, …). */
 async function fetchAppSpec(appUrl, route, coverageDir) {
     let text;
@@ -483,3 +537,4 @@ export function blockedHint(hosts) {
         return message;
     return `${message}\n${registries.join(", ")} ${registries.length > 1 ? "are package registries" : "is a package registry"}: the command that starts the app (gradle bootRun, mvn spring-boot:run, go run, …) is downloading dependencies, through slicetest's proxy. Download them in \`app.build\` (./gradlew bootJar, mvn package), or start a built artifact (java -jar).`;
 }
+export { connectionVars };

package/dist/scenario.js

@@ -15,12 +15,15 @@ function define(register) {
         if (task.concurrent) {
             throw new Error("slicetest: scenarios share one app and database per file, so they can't run concurrently. Remove .concurrent / sequence.concurrent.");
         }
+        const file = task.file?.filepath ?? task.file?.name ?? "";
         onTestFailed(async () => {
             console.error(`--- slicetest ---\n${await runtime.diagnostics()}\n-----------------`);
+            await runtime.reportDiagram(file, task.name, true);
         });
         await runtime.beforeScenario();
         await body(runtime.context());
         await runtime.afterScenario();
+        await runtime.reportDiagram(file, task.name, false);
     }, timeout);
 }
 /**

package/dist/schema.d.ts

@@ -0,0 +1,5 @@
+import { type ValidateFunction } from "ajv";
+/** A schema file and pointer, `schemas/poll.json` or `openapi.yaml#/components/schemas/Poll`, resolved against `base`. */
+export declare function validatorFor(ref: string, base?: string): ValidateFunction;
+/** Problems with `value` against `schema` (an object, or a reference as for `validatorFor`); empty when it matches. */
+export declare function schemaProblems(schema: object | string, value: unknown, base?: string): string[];

package/dist/schema.js

@@ -0,0 +1,73 @@
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { Ajv } from "ajv";
+import { Ajv2020 } from "ajv/dist/2020.js";
+import addFormatsModule from "ajv-formats";
+import { parse } from "yaml";
+import { nullableToType } from "./openapi.js";
+/**
+ * JSON Schema checks for `toMatchSchema()` and YAML `expect.schema`: an inline
+ * schema, or a file with an optional JSON pointer, such as an OpenAPI component
+ * (`openapi.yaml#/components/schemas/Poll`), whose `$ref`s resolve within that file.
+ */
+const addFormats = (addFormatsModule.default ?? addFormatsModule);
+const cache = new Map();
+function ajvFor(draft2020) {
+    const ajv = draft2020 ? new Ajv2020({ strict: false, allErrors: true }) : new Ajv({ strict: false, allErrors: true });
+    addFormats(ajv);
+    // OpenAPI's own formats, which JSON Schema doesn't define.
+    for (const f of ["int32", "int64", "float", "double", "byte", "binary", "password"])
+        ajv.addFormat(f, true);
+    return ajv;
+}
+/** A schema file and pointer, `schemas/poll.json` or `openapi.yaml#/components/schemas/Poll`, resolved against `base`. */
+export function validatorFor(ref, base = process.cwd()) {
+    const [file, pointer = ""] = ref.split("#");
+    const abs = path.resolve(base, file);
+    const key = `${abs}#${pointer}`;
+    const hit = cache.get(key);
+    if (hit)
+        return hit;
+    let doc;
+    try {
+        doc = parse(readFileSync(abs, "utf8"));
+    }
+    catch (e) {
+        throw new Error(`slicetest: can't read schema ${file}: ${e.message}`);
+    }
+    if (!doc || typeof doc !== "object")
+        throw new Error(`slicetest: schema ${file} is not a JSON or YAML document`);
+    const openapi = typeof doc.openapi === "string";
+    if (openapi && !pointer)
+        throw new Error(`slicetest: ${file} is an OpenAPI document; point at a schema in it, e.g. ${file}#/components/schemas/Poll`);
+    // OpenAPI 3.0 schemas are a dialect of draft-04/07 with `nullable`; 3.1 and plain files are 2020-12 unless they say otherwise.
+    const draft2020 = openapi ? doc.openapi.startsWith("3.1") : !/draft-0[4-7]/.test(String(doc.$schema ?? ""));
+    const ajv = ajvFor(draft2020);
+    ajv.addSchema(openapi && !draft2020 ? nullableToType(structuredClone(doc)) : doc, "doc");
+    let validate;
+    try {
+        validate = ajv.compile({ $ref: `doc#${pointer}` });
+    }
+    catch (e) {
+        throw new Error(`slicetest: no schema at ${ref}: ${e.message}`);
+    }
+    cache.set(key, validate);
+    return validate;
+}
+const inline = new WeakMap();
+/** Problems with `value` against `schema` (an object, or a reference as for `validatorFor`); empty when it matches. */
+export function schemaProblems(schema, value, base) {
+    let validate;
+    if (typeof schema === "string")
+        validate = validatorFor(schema, base);
+    else {
+        validate = inline.get(schema) ?? ajvFor(!/draft-0[4-7]/.test(String(schema.$schema ?? ""))).compile(schema);
+        inline.set(schema, validate);
+    }
+    if (validate(value))
+        return [];
+    return (validate.errors ?? []).map((e) => {
+        const extra = e.keyword === "additionalProperties" ? ` (${e.params.additionalProperty})` : e.keyword === "enum" ? ` (${e.params.allowedValues?.map((v) => JSON.stringify(v)).join(", ")})` : "";
+        return `${e.instancePath || "(root)"} ${e.message}${extra}`;
+    });
+}

package/dist/stub.d.ts

@@ -1,4 +1,5 @@
 import http from "node:http";
+import { type GraphQLCall } from "./graphql.js";
 export interface RecordedCall {
     method: string;
     path: string;
@@ -21,6 +22,8 @@ export interface RecordedCall {
     fallback?: boolean;
     /** The fault `chaos()` injected instead of the normal answer: `503`, `reset`. */
     fault?: string;
+    /** The GraphQL operation, when the call is a GraphQL request. */
+    graphql?: GraphQLCall;
 }
 /**
  * Faults injected into a stub's answers, to test the app's retries, timeouts and
@@ -69,6 +72,11 @@ export interface MatchOptions {
     headers?: Record<string, Matcher>;
     json?: unknown;
     body?: Matcher;
+    /** A GraphQL request for this operation (its name, or a RegExp), with `variables` as a subset. */
+    graphql?: {
+        operation?: string | RegExp;
+        variables?: unknown;
+    };
 }
 type Matcher = string | number | boolean | RegExp | ((value: any) => boolean) | {
     asymmetricMatch(value: unknown): boolean;
@@ -80,6 +88,8 @@ export interface RouteBuilder {
     once(): RouteBuilder;
     /** Wait before answering, e.g. to exercise the app's timeouts. */
     delay(ms: number): RouteBuilder;
+    /** The app may or may not call this route: it isn't reported as unused (`strictStubs`). */
+    optional(): RouteBuilder;
     reply(status: number, body?: unknown, headers?: Record<string, string>): Stub;
     reply(response: Responder): Stub;
     /** Answer each matching call with the next response in the list; the last one repeats. */
@@ -87,6 +97,21 @@ export interface RouteBuilder {
     /** Drop the connection without answering. */
     networkError(): Stub;
 }
+/** Builder returned by `stub.graphql()`: `reply()` as usual, or `data()` / `errors()` for a GraphQL answer. */
+export interface GraphQLRouteBuilder extends RouteBuilder {
+    times(n: number): GraphQLRouteBuilder;
+    once(): GraphQLRouteBuilder;
+    delay(ms: number): GraphQLRouteBuilder;
+    optional(): GraphQLRouteBuilder;
+    /** Answer `{ data }` (a function receives the call, with `call.graphql.variables`). */
+    data(data: (call: RecordedCall) => unknown): Stub;
+    data(data: unknown): Stub;
+    /** Answer `{ errors, data }` with status 200, as GraphQL servers report resolver errors. */
+    errors(errors: (string | {
+        message: string;
+        [k: string]: unknown;
+    })[], data?: unknown): Stub;
+}
 /**
  * A fake outbound service. The app is pointed at `url`; tests register routes
  * with `on()` and inspect what the app sent with `calls()`.
@@ -105,6 +130,15 @@ export declare class Stub {
      * `call.params`) or be a RegExp; `method` may be `*`. Later routes win.
      */
     on(method: string, path: string | RegExp, match?: MatchOptions): RouteBuilder;
+    /**
+     * Answer a GraphQL operation, whatever path the app posts it to:
+     * `stub("github").graphql("CreateIssue", { variables: { title: "Bug" } }).data({ createIssue: { issue: { number: 1 } } })`.
+     * The operation is `operationName`, or the name in the document when the client sends none.
+     */
+    graphql(operation: string | RegExp, match?: Omit<MatchOptions, "graphql"> & {
+        variables?: unknown;
+        path?: string | RegExp;
+    }): GraphQLRouteBuilder;
     /**
      * Inject faults into this stub's answers for the rest of the scenario:
      * `stub("payments").chaos({ failFirst: 2 })` to test a retry,
@@ -119,8 +153,15 @@ export declare class Stub {
     /** Calls received so far, optionally filtered by method, path and conditions (same syntax as `on()`). */
     calls(method?: string, path?: string | RegExp, match?: MatchOptions): RecordedCall[];
     unmatched(): RecordedCall[];
+    /** Routes registered in this scenario that no call reached, except `optional()` ones. */
+    unusedRoutes(): string[];
     /** Human-readable list of registered routes, for diagnostics. */
     describeRoutes(): string[];
+    /**
+     * Why `call` wasn't answered, measured against the registered route it came closest to:
+     * `closest route POST /v1/charges: json.amount: expected 100, got "100"`. Undefined without routes.
+     */
+    explain(call: RecordedCall): string | undefined;
     reset(): void;
     /**
      * Answer calls that no registered route matches, instead of failing with 501.

package/dist/stub.js

@@ -1,5 +1,7 @@
 import http from "node:http";
 import { isDeepStrictEqual } from "node:util";
+import { describeGraphQL, graphqlErrors, graphqlOf } from "./graphql.js";
+import { timeline } from "./timeline.js";
 /**
  * A streaming reply in Server-Sent Events format, as LLM APIs stream (Anthropic, OpenAI):
  * `stub("anthropic").on("POST", "/v1/messages").reply(sse([["message_start", {...}], ...]))`.
@@ -54,6 +56,28 @@ export class Stub {
      * `call.params`) or be a RegExp; `method` may be `*`. Later routes win.
      */
     on(method, path, match = {}) {
+        return this.#on(method, path, match);
+    }
+    /**
+     * Answer a GraphQL operation, whatever path the app posts it to:
+     * `stub("github").graphql("CreateIssue", { variables: { title: "Bug" } }).data({ createIssue: { issue: { number: 1 } } })`.
+     * The operation is `operationName`, or the name in the document when the client sends none.
+     */
+    graphql(operation, match = {}) {
+        const { variables, path, ...rest } = match;
+        const builder = this.#on("*", path ?? /.*/, { ...rest, graphql: { operation, variables } }, `GraphQL ${operation}${path ? ` at ${path}` : ""}`);
+        const gql = {
+            ...builder,
+            times: (n) => (builder.times(n), gql),
+            once: () => (builder.once(), gql),
+            delay: (ms) => (builder.delay(ms), gql),
+            optional: () => (builder.optional(), gql),
+            data: (data) => builder.reply(async (call) => ({ status: 200, body: { data: typeof data === "function" ? await data(call) : data } })),
+            errors: (errors, data) => builder.reply({ status: 200, body: { errors: graphqlErrors(errors), ...(data === undefined ? {} : { data }) } }),
+        };
+        return gql;
+    }
+    #on(method, path, match, label) {
         const { pattern, paramNames } = compilePath(path);
         const route = {
             method: method.toUpperCase(),
@@ -64,6 +88,7 @@ export class Stub {
             remaining: Infinity,
             delayMs: 0,
             hits: 0,
+            label,
         };
         const add = (respond, extra = {}) => {
             this.#routes.unshift({ ...route, ...extra, respond });
@@ -73,6 +98,7 @@ export class Stub {
             times: (n) => ((route.remaining = n), builder),
             once: () => builder.times(1),
             delay: (ms) => ((route.delayMs = ms), builder),
+            optional: () => ((route.optional = true), builder),
             reply: (statusOrResponse, body, headers) => add(typeof statusOrResponse === "number" ? { status: statusOrResponse, body, headers } : statusOrResponse),
             replySequence: (responses) => {
                 if (responses.length === 0)
@@ -162,14 +188,53 @@ export class Stub {
     unmatched() {
         return this.#calls.filter((c) => !c.matched);
     }
+    /** Routes registered in this scenario that no call reached, except `optional()` ones. */
+    unusedRoutes() {
+        return this.#routes.filter((r) => r.hits === 0 && !r.optional).map((r) => r.label ?? `${r.method} ${r.path}`).reverse();
+    }
     /** Human-readable list of registered routes, for diagnostics. */
     describeRoutes() {
         return this.#routes.map((r) => {
             const limit = Number.isFinite(r.remaining + r.hits) ? ` (${r.hits}/${r.remaining + r.hits} used)` : "";
-            const cond = Object.keys(r.match).length ? ` + ${Object.keys(r.match).join("/")} conditions` : "";
-            return `${r.method} ${r.path}${cond}${limit}`;
+            const keys = Object.keys(r.match).filter((k) => !(k === "graphql" && r.label));
+            const cond = keys.length ? ` + ${keys.join("/")} conditions` : "";
+            return `${r.label ?? `${r.method} ${r.path}`}${cond}${limit}`;
         });
     }
+    /**
+     * Why `call` wasn't answered, measured against the registered route it came closest to:
+     * `closest route POST /v1/charges: json.amount: expected 100, got "100"`. Undefined without routes.
+     */
+    explain(call) {
+        let best;
+        for (const route of this.#routes) {
+            const reasons = [];
+            let score = 0;
+            if (route.method !== "*" && route.method !== call.method) {
+                reasons.push(`method is ${call.method}, the route takes ${route.method}`);
+                score += 1;
+            }
+            if (!matchPath(route.path, route.pattern, call.path, route.paramNames)) {
+                reasons.push(pathHint(route.path, call.path));
+                score += 2 + (typeof route.path === "string" ? Math.min(distance(route.path, call.path) / 4, 3) : 1);
+            }
+            const why = conditionMismatch(route.match, call);
+            if (why) {
+                reasons.push(why);
+                score += 1;
+            }
+            if (reasons.length === 0 && route.remaining <= 0) {
+                reasons.push(`the route already answered its ${route.hits} call(s) (once() / times())`);
+                score += 0.5;
+            }
+            if (!best || score < best.score)
+                best = { route, reasons, score };
+        }
+        if (!best)
+            return undefined;
+        const label = best.route.label ?? `${best.route.method} ${best.route.path}`;
+        return `closest route ${label}: ${best.reasons.join("; ") || "matches now (registered after the call arrived?)"}`;
+    }
     reset() {
         this.#routes = [];
         this.#calls = [];
@@ -190,6 +255,7 @@ export class Stub {
         await new Promise((resolve) => this.#server.close(resolve));
     }
     async #handle(req, res) {
+        const start = performance.now();
         const chunks = [];
         for await (const chunk of req)
             chunks.push(chunk);
@@ -205,6 +271,9 @@ export class Stub {
             params: {},
             matched: false,
         };
+        call.graphql = graphqlOf(call);
+        timeline.set(call, { start });
+        res.once("close", () => (timeline.get(call).end = performance.now()));
         this.#calls.push(call);
         let route;
         for (const r of this.#routes) {
@@ -236,7 +305,8 @@ export class Stub {
             }
             if (!out) {
                 const hint = this.#hint ? ` (${this.#hint})` : "";
-                res.writeHead(501, { "content-type": "text/plain" }).end(`slicetest: no stub for ${call.method} ${call.path}${hint}`);
+                const what = call.graphql ? `${describeGraphQL(call.graphql)} (${call.method} ${call.path})` : `${call.method} ${call.path}`;
+                res.writeHead(501, { "content-type": "text/plain" }).end(`slicetest: no stub for ${what}${hint}`);
                 return;
             }
             call.matched = true;
@@ -318,8 +388,122 @@ function matchConditions(match, call) {
         return false;
     if (match.json !== undefined && !subset(match.json, call.json))
         return false;
+    if (match.graphql) {
+        const g = call.graphql;
+        if (!g)
+            return false;
+        const { operation, variables } = match.graphql;
+        if (operation !== undefined && !(operation instanceof RegExp ? g.operation !== undefined && operation.test(g.operation) : g.operation === operation))
+            return false;
+        if (variables !== undefined && !subset(variables, g.variables))
+            return false;
+    }
     return true;
 }
+/** The first condition of `match` that `call` fails, described; undefined when it meets them all. */
+function conditionMismatch(match, call) {
+    for (const [k, m] of Object.entries(match.query ?? {})) {
+        const v = call.query.get(k) ?? undefined;
+        if (!test(m, v))
+            return `query ${k}: expected ${show(m)}, got ${v === undefined ? "nothing" : JSON.stringify(v)}`;
+    }
+    for (const [k, m] of Object.entries(match.headers ?? {})) {
+        const raw = call.headers[k.toLowerCase()];
+        const v = Array.isArray(raw) ? raw.join(", ") : raw;
+        if (!test(m, v))
+            return `header ${k.toLowerCase()}: expected ${show(m)}, got ${v === undefined ? "nothing" : JSON.stringify(v)}`;
+    }
+    if (match.body !== undefined && !test(match.body, call.body))
+        return `body: expected ${show(match.body)}, got ${JSON.stringify(call.body.slice(0, 100))}`;
+    if (match.json !== undefined) {
+        if (call.json === undefined)
+            return `json: expected a JSON body, got ${call.body ? JSON.stringify(call.body.slice(0, 100)) : "an empty body"}`;
+        const diff = difference(match.json, call.json, "json");
+        if (diff)
+            return diff;
+    }
+    if (match.graphql) {
+        const g = call.graphql;
+        if (!g)
+            return "graphql: the call isn't a GraphQL request";
+        const { operation, variables } = match.graphql;
+        if (operation !== undefined && !(operation instanceof RegExp ? g.operation !== undefined && operation.test(g.operation) : g.operation === operation)) {
+            return `graphql operation: expected ${show(operation)}, got ${g.operation ?? "an anonymous operation"}`;
+        }
+        if (variables !== undefined) {
+            const diff = difference(variables, g.variables, "variables");
+            if (diff)
+                return diff;
+        }
+    }
+    return undefined;
+}
+/** Where `actual` first stops containing `expected` (the rules of `subset`), as `json.items.0.sku: expected "a", got "b"`. */
+function difference(expected, actual, at) {
+    if (subset(expected, actual))
+        return undefined;
+    if (Array.isArray(expected) && Array.isArray(actual)) {
+        if (expected.length !== actual.length)
+            return `${at}: expected ${expected.length} item(s), got ${actual.length}`;
+        for (const [i, e] of expected.entries()) {
+            const d = difference(e, actual[i], `${at}.${i}`);
+            if (d)
+                return d;
+        }
+    }
+    if (expected && typeof expected === "object" && !Array.isArray(expected) && !isAsymmetric(expected) && !(expected instanceof RegExp) && actual && typeof actual === "object" && !Array.isArray(actual)) {
+        for (const [k, v] of Object.entries(expected)) {
+            if (!(k in actual))
+                return `${at}.${k}: expected ${show(v)}, got nothing`;
+            const d = difference(v, actual[k], `${at}.${k}`);
+            if (d)
+                return d;
+        }
+    }
+    return `${at}: expected ${show(expected)}, got ${short(actual)}`;
+}
+function show(m) {
+    if (isAsymmetric(m))
+        return m.toAsymmetricMatcher?.() ?? String(m);
+    if (m instanceof RegExp)
+        return String(m);
+    if (typeof m === "function")
+        return "a value the given function accepts";
+    return short(m);
+}
+function short(v) {
+    const s = v === undefined ? "nothing" : JSON.stringify(v);
+    return s.length > 80 ? `${s.slice(0, 79)}…` : s;
+}
+/** What is off about the path: a trailing slash, letter case, a prefix, or just a different path. */
+function pathHint(expected, actual) {
+    if (typeof expected !== "string")
+        return `path ${actual} doesn't match ${expected}`;
+    const trim = (p) => (p.length > 1 ? p.replace(/\/+$/, "") : p);
+    if (trim(expected) === trim(actual))
+        return `path is ${actual}, the route is ${expected} (trailing slash)`;
+    if (expected.toLowerCase() === actual.toLowerCase())
+        return `path is ${actual}, the route is ${expected} (letter case)`;
+    if (actual.endsWith(expected))
+        return `path is ${actual}, the route is ${expected}: is the base URL's path (${actual.slice(0, -expected.length)}) in the env value?`;
+    if (expected.endsWith(actual))
+        return `path is ${actual}, the route is ${expected}: the base URL the app was given may lack ${expected.slice(0, -actual.length)}`;
+    return `path is ${actual}, the route is ${expected}`;
+}
+/** Levenshtein distance, to find the route whose path is nearest. */
+function distance(a, b) {
+    const row = Array.from({ length: b.length + 1 }, (_, i) => i);
+    for (let i = 1; i <= a.length; i++) {
+        let prev = row[0];
+        row[0] = i;
+        for (let j = 1; j <= b.length; j++) {
+            const tmp = row[j];
+            row[j] = Math.min(row[j] + 1, row[j - 1] + 1, prev + (a[i - 1] === b[j - 1] ? 0 : 1));
+            prev = tmp;
+        }
+    }
+    return row[b.length];
+}
 function test(m, value) {
     if (isAsymmetric(m))
         return m.asymmetricMatch(value);

package/dist/timeline.d.ts

@@ -0,0 +1,9 @@
+/**
+ * When requests to the app and calls to stubs started and ended (`performance.now()`),
+ * kept beside the objects rather than on them, so that the public shapes (and snapshots
+ * of them) don't change. Used to put a scenario's events in order for `diagram()`.
+ */
+export declare const timeline: WeakMap<object, {
+    start: number;
+    end?: number;
+}>;

package/dist/timeline.js

@@ -0,0 +1,6 @@
+/**
+ * When requests to the app and calls to stubs started and ended (`performance.now()`),
+ * kept beside the objects rather than on them, so that the public shapes (and snapshots
+ * of them) don't change. Used to put a scenario's events in order for `diagram()`.
+ */
+export const timeline = new WeakMap();