slicetest 0.6.1 → 0.8.0

package/dist/recording.d.ts

@@ -40,4 +40,4 @@ export declare class Recorder {
 }
 export declare function readRecordings(file: string): Promise<Recording[]>;
 /** Append new recordings to `file`, skipping exact duplicates, keeping the order they were made in. */
-export declare function mergeRecordings(file: string, upstream: string, added: Recording[]): Promise<void>;
+export declare function mergeRecordings(file: string, upstream: string, added: Recording[], source?: string): Promise<void>;

package/dist/recording.js

@@ -137,12 +137,12 @@ export async function readRecordings(file) {
     return doc;
 }
 /** Append new recordings to `file`, skipping exact duplicates, keeping the order they were made in. */
-export async function mergeRecordings(file, upstream, added) {
+export async function mergeRecordings(file, upstream, added, source = `Recorded by slicetest from ${upstream}`) {
     const entries = await readRecordings(file);
     for (const e of added)
         if (!entries.some((x) => isDeepStrictEqual(x, e)))
             entries.push(e);
     await mkdir(path.dirname(file), { recursive: true });
-    const header = `# Recorded by slicetest from ${upstream}. Review before committing: request bodies are stored as sent.\n`;
+    const header = `# ${source}. Review before committing: request bodies are stored as sent.\n`;
     await writeFile(file, header + YAML.stringify(entries, { lineWidth: 0 }));
 }

package/dist/runtime.d.ts

@@ -2,6 +2,7 @@ import { App } from "./app.js";
 import { Issuer } from "./auth.js";
 import type { ResolvedOptions } from "./config.js";
 import { Dependency } from "./containers.js";
+import { connectionVars } from "./connection.js";
 import { Db } from "./db.js";
 import { HttpClient } from "./http.js";
 import { Interceptor } from "./intercept.js";
@@ -24,6 +25,8 @@ export interface ScenarioContext {
      * with timestamps and UUIDs masked. `expect(await trace()).toMatchSnapshot()`.
      */
     trace: (opts?: MaskOptions) => Promise<Trace>;
+    /** The scenario so far as a Mermaid sequence diagram: requests, stub calls, mail and changed tables. */
+    diagram: () => Promise<string>;
     /** Mail the app sent during the scenario. Needs `mail: true` in the config. */
     mail: Mailbox;
     /** The OpenID Connect issuer the app trusts: `auth.token(claims)`. Needs `auth` in the config. */
@@ -56,20 +59,24 @@ export declare class Runtime {
         prefix: string;
         coverageDir?: string;
         recordDir?: string;
+        usageDir?: string;
     }): Promise<Runtime>;
     context(): ScenarioContext;
     beforeScenario(): Promise<void>;
     /** Failures that the scenario body can't see on its own. */
     afterScenario(): Promise<void>;
+    /** The current scenario as a Mermaid sequence diagram. */
+    diagram(): Promise<string>;
+    /**
+     * 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.
+     */
+    reportDiagram(file: string, scenario: string, failed: boolean, env?: NodeJS.ProcessEnv): Promise<void>;
     /** What happened during the current scenario, printed when it fails. */
     diagnostics(): Promise<string>;
     /** Hand the coverage and recordings gathered so far to the run (merged when it ends). */
     flush(): Promise<void>;
     stop(): Promise<void>;
 }
-/**
- * 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 declare function connectionVars(engine: string, url: string, sqlitePath?: string): Record<string, string>;
 export declare function blockedHint(hosts: string[]): string;
+export { connectionVars };

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;
@@ -119,6 +124,7 @@ export class Runtime {
                 ? await Db.connect(await engine.driver(url), url, {
                     schemas: opts.db.schemas,
                     keep: opts.db.keep,
+                    ignoreChanges: opts.db.ignoreChanges,
                     seedFile: opts.db.seed && path.resolve(opts.root, opts.db.seed),
                 })
                 : noDatabase();
@@ -182,7 +188,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 +235,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 +252,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 +310,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 +354,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 +404,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 +443,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 +513,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 +538,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.d.ts

@@ -1,15 +1,25 @@
 import type { Runtime, ScenarioContext } from "./runtime.js";
 export declare function setRuntime(runtime: Runtime | undefined): void;
 type Body = (ctx: ScenarioContext) => Promise<void> | void;
+export interface ScenarioOptions {
+    timeout?: number;
+    /** Labels to select scenarios by: `npx slicetest --tag smoke`, or `SLICETEST_TAGS=smoke,!slow` with Vitest. */
+    tags?: string[];
+}
+/**
+ * Whether a scenario with `tags` runs under `filter` (`SLICETEST_TAGS`): comma- or space-separated tags,
+ * any of which it must have, and `!tag`s it must not have. No filter runs everything.
+ */
+export declare function tagsSelected(tags?: readonly string[], filter?: string | undefined): boolean;
 /**
  * A test that runs against the real app. The database is reset to the
  * migrated schema (plus seed) and stubs are cleared before each scenario.
  */
-export declare const scenario: ((name: string, body: Body, timeout?: number) => void) & {
-    only: (name: string, body: Body, timeout?: number) => void;
-    skip: (name: string, body: Body, timeout?: number) => void;
+export declare const scenario: ((name: string, body: Body, options?: number | ScenarioOptions) => void) & {
+    only: (name: string, body: Body, options?: number | ScenarioOptions) => void;
+    skip: (name: string, body: Body, options?: number | ScenarioOptions) => void;
     todo: (name: string) => void;
     /** Same scenario for each row: `scenario.each(rows)("name %s", async (row, ctx) => ...)`. */
-    each<T>(rows: readonly T[]): (name: string, body: (row: T, ctx: ScenarioContext) => Promise<void> | void, timeout?: number) => void;
+    each<T>(rows: readonly T[]): (name: string, body: (row: T, ctx: ScenarioContext) => Promise<void> | void, options?: number | ScenarioOptions) => void;
 };
 export {};

package/dist/scenario.js

@@ -6,22 +6,41 @@ const slot = globalThis;
 export function setRuntime(runtime) {
     slot[KEY] = runtime;
 }
+/**
+ * Whether a scenario with `tags` runs under `filter` (`SLICETEST_TAGS`): comma- or space-separated tags,
+ * any of which it must have, and `!tag`s it must not have. No filter runs everything.
+ */
+export function tagsSelected(tags = [], filter = process.env.SLICETEST_TAGS) {
+    const terms = (filter ?? "").split(/[\s,]+/).filter(Boolean);
+    const excluded = terms.filter((t) => t.startsWith("!")).map((t) => t.slice(1));
+    const wanted = terms.filter((t) => !t.startsWith("!"));
+    if (tags.some((t) => excluded.includes(t)))
+        return false;
+    return wanted.length === 0 || tags.some((t) => wanted.includes(t));
+}
 function define(register) {
-    return (name, body, timeout) => register(name, async ({ onTestFailed, task }) => {
-        const runtime = slot[KEY];
-        if (!runtime) {
-            throw new Error("slicetest: runtime not started. Add the slicetest() plugin to your vitest config.");
-        }
-        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.");
-        }
-        onTestFailed(async () => {
-            console.error(`--- slicetest ---\n${await runtime.diagnostics()}\n-----------------`);
-        });
-        await runtime.beforeScenario();
-        await body(runtime.context());
-        await runtime.afterScenario();
-    }, timeout);
+    return (name, body, options) => {
+        const { timeout, tags } = typeof options === "number" ? { timeout: options, tags: undefined } : (options ?? {});
+        // Scenarios the tag filter leaves out show as skipped, so the filter is visible in the summary.
+        return (tagsSelected(tags) ? register : test.skip)(name, async ({ onTestFailed, task }) => {
+            const runtime = slot[KEY];
+            if (!runtime) {
+                throw new Error("slicetest: runtime not started. Add the slicetest() plugin to your vitest config.");
+            }
+            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);
+    };
 }
 /**
  * A test that runs against the real app. The database is reset to the
@@ -33,10 +52,10 @@ export const scenario = Object.assign(define(test), {
     todo: (name) => test.todo(name),
     /** Same scenario for each row: `scenario.each(rows)("name %s", async (row, ctx) => ...)`. */
     each(rows) {
-        return (name, body, timeout) => {
+        return (name, body, options) => {
             rows.forEach((row, i) => {
                 const title = format(name, row, i);
-                define(test)(title, (ctx) => body(row, ctx), timeout);
+                define(test)(title, (ctx) => body(row, ctx), options);
             });
         };
     },

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;
@@ -7,6 +8,13 @@ export interface RecordedCall {
     body: string;
     /** Parsed JSON body, or undefined when the body isn't JSON. */
     json: any;
+    /**
+     * Fields of an `application/x-www-form-urlencoded` body (Stripe, Twilio, OAuth token requests),
+     * with bracket keys nested as the providers read them: `metadata[order]=7&items[0][price]=p_1`
+     * is `{ metadata: { order: "7" }, items: [{ price: "p_1" }] }`. For `multipart/form-data`, the
+     * fields with files as `{ filename, type, size, text }`. Undefined for other bodies.
+     */
+    form?: Record<string, unknown>;
     /** Values captured by `:name` segments of the matching route's path. */
     params: Record<string, string>;
     /** Whether a registered route answered this call. */
@@ -21,6 +29,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
@@ -68,7 +78,14 @@ export interface MatchOptions {
     query?: Record<string, Matcher>;
     headers?: Record<string, Matcher>;
     json?: unknown;
+    /** Subset of a form-encoded body's fields (`call.form`). Numbers and booleans compare as the strings sent. */
+    form?: Record<string, 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 +97,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 +106,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 +139,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 +162,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.
@@ -132,4 +182,17 @@ export declare class Stub {
 }
 /** `expected` is contained in `actual`: objects compare key by key, arrays element-wise. */
 export declare function subset(expected: unknown, actual: unknown): boolean;
+/**
+ * A form body as nested fields, the way Rack, PHP and Stripe read bracket keys: `a[b]=1` is
+ * `{ a: { b: "1" } }`, `a[]=1&a[]=2` and `a[0]=1&a[1]=2` are arrays, and a plain key sent
+ * twice (`to=1&to=2`) becomes an array too.
+ */
+export declare function parseForm(body: string): Record<string, unknown>;
+/** A file in a multipart body, as `call.form` shows it. `text` only for text, JSON, XML and CSV files. */
+export interface UploadedFile {
+    filename: string;
+    type: string;
+    size: number;
+    text?: string;
+}
 export {};