slicetest 0.6.1 → 0.8.0

package/dist/config.js

@@ -9,6 +9,7 @@ export function resolveOptions(opts, root) {
         containers: opts.containers ?? {},
         mail: opts.mail ?? false,
         offline: opts.offline ?? false,
+        strictStubs: opts.strictStubs ?? false,
         workers: opts.workers,
         auth: opts.auth === true ? {} : (opts.auth ?? false),
         db: opts.db === false ? { ...resolveDb({}), none: true } : resolveDb(opts.db ?? {}),
@@ -104,6 +105,8 @@ function validate(opts) {
         fail(`workers must be a positive whole number, got ${JSON.stringify(opts.workers)}`);
     if (opts.offline !== undefined && typeof opts.offline !== "boolean")
         fail(`offline must be true or false, got ${JSON.stringify(opts.offline)}`);
+    if (opts.strictStubs !== undefined && typeof opts.strictStubs !== "boolean")
+        fail(`strictStubs must be true or false, got ${JSON.stringify(opts.strictStubs)}`);
     if (opts.mail !== undefined && typeof opts.mail !== "boolean")
         fail(`mail must be true or false, got ${JSON.stringify(opts.mail)}`);
     if (opts.auth !== undefined && typeof opts.auth !== "boolean") {
@@ -121,6 +124,9 @@ function validate(opts) {
     const engine = dbOpts?.engine;
     if (engine !== undefined && engine !== "postgres" && engine !== "mysql" && engine !== "sqlite")
         fail(`db.engine must be "postgres", "mysql" or "sqlite", got ${JSON.stringify(engine)}`);
+    if (dbOpts?.ignoreChanges !== undefined && !(Array.isArray(dbOpts.ignoreChanges) && dbOpts.ignoreChanges.every((c) => typeof c === "string" && c && !c.startsWith(".")))) {
+        fail(`db.ignoreChanges must be a list of columns or tables, e.g. [updated_at, orders.synced_at, sessions.*], got ${JSON.stringify(dbOpts.ignoreChanges)}`);
+    }
     if (dbOpts?.queries !== undefined && typeof dbOpts.queries !== "boolean")
         fail(`db.queries must be true or false, got ${JSON.stringify(dbOpts.queries)}`);
     if (dbOpts?.neon !== undefined && typeof dbOpts.neon !== "boolean")
@@ -136,6 +142,13 @@ function validate(opts) {
         const keys = Object.keys(migrate).filter((k) => ["atlas", "sql", "command"].includes(k));
         if (keys.length !== 1)
             fail(`db.migrate takes exactly one of atlas / sql / command, got ${keys.join(", ") || "none"}`);
+        const menv = migrate.env;
+        if (menv !== undefined) {
+            if (!("command" in migrate))
+                fail("db.migrate.env is for a migration `command`; atlas and sql get the database URL themselves");
+            if (!menv || typeof menv !== "object" || Array.isArray(menv) || Object.values(menv).some((v) => typeof v !== "string"))
+                fail('db.migrate.env maps variable names to strings, e.g. { DB_HOST: "{{db.host}}" }');
+        }
     }
     const oas = opts.openapi;
     if (oas !== undefined) {

package/dist/connection.d.ts

@@ -0,0 +1,5 @@
+/**
+ * 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>;

package/dist/connection.js

@@ -0,0 +1,31 @@
+/**
+ * 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}`, "db.adoNet": `Data Source=${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)}`,
+        // ADO.NET (Npgsql, MySqlConnector), as .NET apps read `ConnectionStrings__Default`.
+        "db.adoNet": [
+            `${engine === "mysql" ? "Server" : "Host"}=${u.hostname}`,
+            `Port=${port}`,
+            `Database=${name}`,
+            `${engine === "mysql" ? "User ID" : "Username"}=${decodeURIComponent(u.username)}`,
+            `Password=${adoValue(decodeURIComponent(u.password))}`,
+        ].join(";"),
+    };
+}
+/** ADO.NET values with `;` or quotes are quoted. */
+function adoValue(v) {
+    return /[;'"]/.test(v) ? `"${v.replace(/"/g, '""')}"` : v;
+}

package/dist/db.d.ts

@@ -26,6 +26,10 @@ export interface TableChanges<T extends Row = Row> {
     }[];
     deleted: T[];
 }
+export interface ChangesOptions {
+    /** Columns or tables to leave out: `updated_at` (in every table), `orders.synced_at`, `sessions.*`. Added to `db.ignoreChanges`. */
+    ignore?: string[];
+}
 /** Changed tables only, keyed by table name (`schema.table` outside `public`). */
 export type Changes = Record<string, TableChanges>;
 /** Test-side handle to the database the app under test is using. */
@@ -37,6 +41,7 @@ export declare class Db {
     static connect(driver: Driver, url: string, opts: {
         schemas: string[];
         keep: string[];
+        ignoreChanges?: string[];
         seedFile?: string;
     }): Promise<Db>;
     query<T extends Row = Row>(sql: string, params?: unknown[]): Promise<T[]>;
@@ -86,13 +91,19 @@ export declare class Db {
      * expect(await db.changes()).toEqual({ polls: { inserted: [expect.objectContaining({ title: "x" })], updated: [], deleted: [] } });
      * ```
      */
-    changes(): Promise<Changes>;
+    changes(opts?: ChangesOptions): Promise<Changes>;
     /** Make `changes()` report only what happens from now on. */
     checkpoint(): Promise<void>;
     /** Changes since the scenario started, regardless of checkpoints. Used for failure output. */
     changesSinceStart(): Promise<Changes>;
     close(): Promise<void>;
 }
+/**
+ * What `ignore` leaves out of one table: `"*"` for the whole table, else the columns.
+ * `updated_at` is that column in every table, `orders.synced_at` in one, `sessions.*` the whole table
+ * (the last segment is the column, so `billing.invoices.*` works for other schemas).
+ */
+export declare function ignored(ignore: readonly string[], table: string): "*" | Set<string>;
 /** Short summary of `changes()` for failure output. */
 export declare function formatChanges(changes: Changes, maxRows?: number): string;
 /** The `db` of an app without a database (`db: false`): resetting is a no-op, anything else explains. */

package/dist/db.js

@@ -151,9 +151,9 @@ export class Db {
      * expect(await db.changes()).toEqual({ polls: { inserted: [expect.objectContaining({ title: "x" })], updated: [], deleted: [] } });
      * ```
      */
-    async changes() {
+    async changes(opts = {}) {
         const base = this.#checkpoint === undefined || this.#checkpoint === "start" ? this.#start : this.#checkpoint;
-        return diff(this.#tables ?? [], base, await this.#snapshot());
+        return diff(this.#tables ?? [], base, await this.#snapshot(), [...(this.opts.ignoreChanges ?? []), ...(opts.ignore ?? [])]);
     }
     /** Make `changes()` report only what happens from now on. */
     async checkpoint() {
@@ -161,7 +161,7 @@ export class Db {
     }
     /** Changes since the scenario started, regardless of checkpoints. Used for failure output. */
     async changesSinceStart() {
-        return diff(this.#tables ?? [], this.#start, await this.#snapshot());
+        return diff(this.#tables ?? [], this.#start, await this.#snapshot(), this.opts.ignoreChanges ?? []);
     }
     /** Every tracked table's rows, in one round trip. */
     async #snapshot() {
@@ -201,11 +201,38 @@ export class Db {
         await this.#driver.close();
     }
 }
-function diff(tables, before, after) {
+/**
+ * What `ignore` leaves out of one table: `"*"` for the whole table, else the columns.
+ * `updated_at` is that column in every table, `orders.synced_at` in one, `sessions.*` the whole table
+ * (the last segment is the column, so `billing.invoices.*` works for other schemas).
+ */
+export function ignored(ignore, table) {
+    const columns = new Set();
+    for (const entry of ignore) {
+        const dot = entry.lastIndexOf(".");
+        if (dot === -1) {
+            columns.add(entry);
+            continue;
+        }
+        const t = entry.slice(0, dot);
+        if (t !== table && !(t === table.split(".").pop() && !t.includes(".")))
+            continue;
+        const column = entry.slice(dot + 1);
+        if (column === "*")
+            return "*";
+        columns.add(column);
+    }
+    return columns;
+}
+function diff(tables, before, after, ignore = []) {
     const out = {};
     for (const table of tables) {
-        const a = before?.get(table.name) ?? [];
-        const b = after.get(table.name) ?? [];
+        const skip = ignored(ignore, table.name);
+        if (skip === "*")
+            continue;
+        const strip = (rows) => (skip.size ? rows.map((r) => Object.fromEntries(Object.entries(r).filter(([c]) => !skip.has(c)))) : rows);
+        const a = strip(before?.get(table.name) ?? []);
+        const b = strip(after.get(table.name) ?? []);
         const changes = table.key.length > 0 ? diffByKey(a, b, table.key) : diffAsBags(a, b);
         if (changes.inserted.length || changes.updated.length || changes.deleted.length)
             out[table.name] = changes;

package/dist/diagram.d.ts

@@ -0,0 +1,13 @@
+import type { Changes } from "./db.js";
+import type { HttpResponse } from "./http.js";
+import type { Mailbox } from "./mail.js";
+import type { Stub } from "./stub.js";
+/**
+ * A Mermaid sequence diagram of what a scenario did: each request to the app,
+ * the stub calls the app made while answering it, the mail it sent and the
+ * database tables it changed. GitHub, GitLab and most Markdown viewers render it.
+ */
+export declare function sequenceDiagram(history: readonly HttpResponse[], stubs: Iterable<Stub>, changes: Changes | undefined, mailbox?: Mailbox): string;
+export declare function diagramPage(file: string, title: string, scenario: string, diagram: string, failed: boolean): string;
+/** A collapsed section for the GitHub Actions job summary. */
+export declare function failureDiagram(where: string, scenario: string, diagram: string): string;

package/dist/diagram.js

@@ -0,0 +1,89 @@
+import { describeGraphQL } from "./graphql.js";
+import { timeline } from "./timeline.js";
+/**
+ * A Mermaid sequence diagram of what a scenario did: each request to the app,
+ * the stub calls the app made while answering it, the mail it sent and the
+ * database tables it changed. GitHub, GitLab and most Markdown viewers render it.
+ */
+export function sequenceDiagram(history, stubs, changes, mailbox) {
+    const events = [];
+    const participants = new Map();
+    const id = (name, label) => {
+        const key = `s_${name.replace(/[^A-Za-z0-9_]/g, "_")}`;
+        if (!participants.has(key))
+            participants.set(key, label);
+        return key;
+    };
+    let order = 0;
+    const add = (at, line) => events.push({ at, order: order++, line });
+    for (const res of history) {
+        const t = timeline.get(res) ?? { start: Infinity, end: Infinity };
+        const external = /^https?:/.test(res.url);
+        const target = external ? id(`ext_${new URL(res.url).host}`, new URL(res.url).host) : "app";
+        const path = external ? new URL(res.url).pathname : res.url;
+        add(t.start, `test->>+${target}: ${text(`${res.method} ${path}`)}`);
+        add(t.end ?? t.start, `${target}-->>-test: ${res.status || "failed"}${summary(res)}`);
+    }
+    for (const stub of stubs) {
+        for (const call of stub.calls()) {
+            const t = timeline.get(call) ?? { start: Infinity };
+            const s = id(stub.name, `${stub.name} (stub)`);
+            add(t.start, `app->>+${s}: ${text(describeCall(call))}`);
+            const reply = call.fault === "reset" ? "connection dropped" : call.response ? `${call.response.status}${call.fault ? " (chaos)" : ""}` : call.matched ? "no answer" : "501 no stub";
+            add(t.end ?? t.start, `${s}-->>-app: ${reply}`);
+        }
+    }
+    events.sort((a, b) => a.at - b.at || a.order - b.order);
+    const lines = ["sequenceDiagram", "  participant test as scenario", "  participant app"];
+    for (const [key, label] of participants)
+        lines.push(`  participant ${key} as ${text(label)}`);
+    if (mailbox && mailbox.messages().length)
+        lines.push("  participant mail");
+    const tables = Object.entries(changes ?? {}).filter(([, c]) => c.inserted.length || c.updated.length || c.deleted.length);
+    if (tables.length)
+        lines.push("  participant db as database");
+    for (const e of events)
+        lines.push(`  ${e.line}`);
+    for (const m of mailbox?.messages() ?? [])
+        lines.push(`  app->>mail: ${text(`${m.subject} to ${m.to.join(", ")}`)}`);
+    if (tables.length) {
+        const counts = tables.map(([table, c]) => `${table} ${[c.inserted.length && `+${c.inserted.length}`, c.updated.length && `~${c.updated.length}`, c.deleted.length && `-${c.deleted.length}`].filter(Boolean).join(" ")}`);
+        lines.push(`  Note over app,db: ${text(counts.join(", "))}`);
+    }
+    return lines.join("\n");
+}
+function describeCall(call) {
+    if (call.graphql)
+        return describeGraphQL(call.graphql);
+    return `${call.method} ${call.path}`;
+}
+/** A short hint of the response: a JSON error message or the id it created. */
+function summary(res) {
+    const j = res.json;
+    if (j && typeof j === "object" && !Array.isArray(j)) {
+        for (const key of ["error", "message", "id"]) {
+            const v = j[key];
+            if (typeof v === "string" || typeof v === "number")
+                return ` ${text(`${key}: ${v}`)}`;
+        }
+    }
+    return "";
+}
+/** Mermaid ends a message at `;` and reads `#…;` as an entity, so both are escaped; long text is cut. */
+function text(s, max = 70) {
+    const cut = s.length > max ? `${s.slice(0, max - 1)}…` : s;
+    return cut.replace(/[\r\n]+/g, " ").replace(/[#;]/g, (c) => (c === "#" ? "#35;" : "#59;"));
+}
+/** Scenario diagrams per test file, for `SLICETEST_DIAGRAMS` / `--diagrams`: one Markdown page per file, in run order. */
+const pages = new Map();
+export function diagramPage(file, title, scenario, diagram, failed) {
+    const page = pages.get(file) ?? { title, sections: new Map() };
+    pages.set(file, page);
+    page.sections.set(scenario, [`## ${scenario}${failed ? " (failed)" : ""}`, "", "```mermaid", diagram, "```", ""].join("\n"));
+    return [`# ${page.title}`, "", `Sequence diagrams of the scenarios in \`${page.title}\`, written by slicetest. Regenerated on every run.`, "", ...page.sections.values()].join("\n");
+}
+/** A collapsed section for the GitHub Actions job summary. */
+export function failureDiagram(where, scenario, diagram) {
+    const name = scenario.replace(/[<>&]/g, (c) => ({ "<": "&lt;", ">": "&gt;", "&": "&amp;" })[c]);
+    return [`<details><summary>✗ ${name} <code>${where}</code>: what happened</summary>`, "", "```mermaid", diagram, "```", "", "</details>", ""].join("\n");
+}

package/dist/form.d.ts

@@ -13,8 +13,11 @@ export interface SubmitOptions {
     button?: string;
     /** The form, by `id`, `name` or position (0-based), when the page has several and no `button` picks one. */
     form?: string | number;
-    /** Values typed into the form, by field name. A name the form doesn't have is an error (a typo, usually). */
-    fields?: Record<string, string | number | boolean | (string | number)[]>;
+    /**
+     * Values typed into the form, by field name. A name the form doesn't have is an error (a typo, usually).
+     * A file input takes a `Blob` / `File` (its name is the file name sent), and the form must be multipart.
+     */
+    fields?: Record<string, string | number | boolean | (string | number)[] | Blob>;
 }
 export interface FormRequest {
     method: "GET" | "POST";
@@ -42,4 +45,6 @@ export declare function decodeEntities(s: string): string;
 export declare function parseForms(html: string): ParsedForm[];
 /** Works out the request a browser would send for this page's form. */
 export declare function formRequest(html: string, opts?: SubmitOptions): FormRequest;
+/** Fields as `application/x-www-form-urlencoded`: lists repeat the key, nested objects use bracket keys (`metadata[order]`). */
+export declare function encodeForm(fields: Record<string, unknown>): URLSearchParams;
 export {};

package/dist/form.js

@@ -37,7 +37,11 @@ export function parseForms(html) {
     let open;
     let select;
     let option;
+    // Controls inside a disabled <fieldset> are disabled too (and not submitted).
+    const fieldsets = [];
     const add = (control) => {
+        if (fieldsets.includes(true))
+            control.attrs.disabled ??= "";
         const formId = control.attrs.form;
         if (formId !== undefined)
             orphans.push({ formId, control });
@@ -62,6 +66,13 @@ export function parseForms(html) {
             TAG.lastIndex = end < 0 ? html.length : end;
             continue;
         }
+        if (tag === "fieldset") {
+            if (closing)
+                fieldsets.pop();
+            else
+                fieldsets.push("disabled" in parseAttrs(m[3] ?? ""));
+            continue;
+        }
         if (tag === "form") {
             if (closing)
                 current = undefined;
@@ -162,12 +173,22 @@ export function formRequest(html, opts = {}) {
         throw new Error(`slicetest: submit: the button ${JSON.stringify(label(button))} is disabled`);
     const names = new Set(form.controls.filter((c) => c.attrs.name !== undefined && !isSubmit(c) && c.tag !== "button").map((c) => c.attrs.name));
     const typed = new Map();
+    const files = new Map();
+    const fileInputs = new Set(form.controls.filter((c) => c.tag === "input" && c.attrs.type?.toLowerCase() === "file").map((c) => c.attrs.name));
     for (const [name, value] of Object.entries(opts.fields ?? {})) {
         if (!names.has(name)) {
             const shown = [...names].filter((n) => !n.startsWith("$ACTION_"));
             throw new Error(`slicetest: submit: the form has no field "${name}". Fields: ${shown.join(", ") || "(none)"}`);
         }
-        typed.set(name, typeof value === "boolean" ? value : (Array.isArray(value) ? value : [value]).map(String));
+        if (fileInputs.has(name) !== value instanceof Blob) {
+            throw new Error(fileInputs.has(name)
+                ? `slicetest: submit: "${name}" is a file input; give it a file (a Blob or File, or { file: path } in YAML)`
+                : `slicetest: submit: "${name}" isn't a file input, so it can't take a file`);
+        }
+        if (value instanceof Blob)
+            files.set(name, value);
+        else
+            typed.set(name, typeof value === "boolean" ? value : (Array.isArray(value) ? value : [value]).map(String));
     }
     // The successful controls, in document order (HTML's "constructing the entry list").
     // A typed value replaces what the page had: text for a field, the checked state for
@@ -176,6 +197,12 @@ export function formRequest(html, opts = {}) {
     const done = new Set();
     for (const c of form.controls) {
         const name = c.attrs.name;
+        if (c === button && c.attrs.type?.toLowerCase() === "image") {
+            // An image button sends the click position, as name.x / name.y (x / y without a name).
+            const prefix = name ? `${name}.` : "";
+            entries.push([`${prefix}x`, "0"], [`${prefix}y`, "0"]);
+            continue;
+        }
         if (name === undefined || "disabled" in c.attrs)
             continue;
         if (c.tag === "button" || isSubmit(c)) {
@@ -184,8 +211,16 @@ export function formRequest(html, opts = {}) {
             continue;
         }
         const type = c.tag === "input" ? (c.attrs.type ?? "text").toLowerCase() : c.tag;
-        if (type === "reset" || type === "button" || type === "file")
+        if (type === "reset" || type === "button")
+            continue;
+        if (type === "file") {
+            // With no file chosen, browsers still send the field: an empty file without a name.
+            const file = files.get(name);
+            if (!done.has(name))
+                entries.push([name, file ?? new File([], "", { type: "application/octet-stream" })]);
+            done.add(name);
             continue;
+        }
         const want = typed.get(name);
         if (type === "checkbox" || type === "radio") {
             const value = c.attrs.value ?? "on";
@@ -214,13 +249,43 @@ export function formRequest(html, opts = {}) {
     const pick = (attr) => (button && button.attrs[`form${attr}`] !== undefined ? button.attrs[`form${attr}`] : form.attrs[attr]);
     const method = (pick("method") ?? "get").toUpperCase() === "POST" ? "POST" : "GET";
     const action = pick("action") ?? "";
+    const multipart = method === "POST" && (pick("enctype") ?? "").toLowerCase() === "multipart/form-data";
+    if (files.size && !multipart) {
+        throw new Error(`slicetest: submit: the form sends ${method === "GET" ? "a GET" : "urlencoded"} data, which can't carry files; a browser would send only the file name. Upload forms need method="post" enctype="multipart/form-data"`);
+    }
+    // Outside multipart, a file field is sent as its file name (empty when none was chosen), as browsers do.
+    const plain = () => new URLSearchParams(entries.map(([k, v]) => [k, typeof v === "string" ? v : (v.name ?? "")]));
     if (method === "GET")
-        return { method, action: `${action.replace(/[?#].*$/, "")}?${new URLSearchParams(entries)}` };
-    const multipart = (pick("enctype") ?? "").toLowerCase() === "multipart/form-data";
+        return { method, action: `${action.replace(/[?#].*$/, "")}?${plain()}` };
     if (!multipart)
-        return { method, action, body: new URLSearchParams(entries) };
+        return { method, action, body: plain() };
     const body = new FormData();
-    for (const [k, v] of entries)
-        body.append(k, v);
+    for (const [k, v] of entries) {
+        if (typeof v === "string")
+            body.append(k, v);
+        else
+            body.append(k, v, v.name ?? "blob");
+    }
     return { method, action, body };
 }
+/** Fields as `application/x-www-form-urlencoded`: lists repeat the key, nested objects use bracket keys (`metadata[order]`). */
+export function encodeForm(fields) {
+    const out = new URLSearchParams();
+    const add = (key, v) => {
+        if (v === null || v === undefined)
+            return;
+        if (Array.isArray(v)) {
+            const nested = v.some((x) => x !== null && typeof x === "object");
+            v.forEach((x, i) => add(nested ? `${key}[${i}]` : key, x));
+        }
+        else if (typeof v === "object" && !(v instanceof Date)) {
+            for (const [k, x] of Object.entries(v))
+                add(`${key}[${k}]`, x);
+        }
+        else
+            out.append(key, v instanceof Date ? v.toISOString() : String(v));
+    };
+    for (const [k, v] of Object.entries(fields))
+        add(k, v);
+    return out;
+}

package/dist/global-setup.d.ts

@@ -3,6 +3,11 @@ import type { ResolvedOptions } from "./config.js";
 import "./provided.js";
 /** Runs once per vitest run: start the database server, migrate a template database, hand its location to the workers. */
 export default function setup(project: TestProject): Promise<() => Promise<void>>;
+/**
+ * Why this run covers only part of the suite (a file or name filter, tags, a shard), or undefined for a full run.
+ * Coverage then says little about the suite, so `minCoverage` isn't enforced and the cache for `gen --uncovered` is kept.
+ */
+export declare function partialRun(project: TestProject): Promise<string | undefined>;
 /**
  * A hash of everything that determines the migrated schema, or undefined when
  * that can't be known (a migration command without `inputs`).

package/dist/global-setup.js

@@ -5,10 +5,12 @@ import os from "node:os";
 import path from "node:path";
 import { promisify } from "node:util";
 import { annotation, appendSummary, failureAnnotations, failureSummary, onGitHub, repoPath, yamlFailures } from "./ci.js";
+import { interpolate } from "./app.js";
+import { connectionVars } from "./connection.js";
 import { configureContainerRuntime } from "./container-runtime.js";
 import { engineFor } from "./drivers/index.js";
 import { coverageCacheFile } from "./gen.js";
-import { appSpecFile, formatCoverage, OpenApiSpec } from "./openapi.js";
+import { appSpecFile, formatCoverage, formatUsage, OpenApiSpec } from "./openapi.js";
 import { mergeRecordings } from "./recording.js";
 import "./provided.js";
 const exec = promisify(execFile);
@@ -27,14 +29,18 @@ export default async function setup(project) {
     const recordDir = recording ? await mkdtemp(path.join(os.tmpdir(), "slicetest-recordings-")) : undefined;
     // On GitHub Actions, failed YAML steps are collected here and turned into annotations at the end.
     const ciDir = onGitHub() ? await mkdtemp(path.join(os.tmpdir(), "slicetest-ci-")) : undefined;
-    project.provide("slicetestDb", { adminUrl: database?.adminUrl ?? "", template: database?.template ?? "", prefix: database?.prefix ?? "", coverageDir, recordDir, ciDir });
+    // Operations the app called on providers whose spec a stub has, reported at the end.
+    const usageDir = Object.keys(opts.openapi.stubs).length ? await mkdtemp(path.join(os.tmpdir(), "slicetest-usage-")) : undefined;
+    project.provide("slicetestDb", { adminUrl: database?.adminUrl ?? "", template: database?.template ?? "", prefix: database?.prefix ?? "", coverageDir, recordDir, ciDir, usageDir });
     return async () => {
         try {
             await database?.teardown();
         }
         finally {
             if (coverageDir)
-                await reportCoverage(opts, coverageDir);
+                await reportCoverage(opts, coverageDir, await partialRun(project));
+            if (usageDir)
+                await reportUsage(opts, usageDir);
             if (recordDir)
                 await saveRecordings(opts, recordDir);
             if (ciDir)
@@ -96,7 +102,30 @@ async function startDatabase(opts, builds) {
         },
     };
 }
-async function reportCoverage(opts, dir) {
+/**
+ * Why this run covers only part of the suite (a file or name filter, tags, a shard), or undefined for a full run.
+ * Coverage then says little about the suite, so `minCoverage` isn't enforced and the cache for `gen --uncovered` is kept.
+ */
+export async function partialRun(project) {
+    try {
+        const config = project.vitest.config;
+        if (config.testNamePattern)
+            return `only scenarios matching ${config.testNamePattern}`;
+        if (process.env.SLICETEST_TAGS)
+            return `only tags ${process.env.SLICETEST_TAGS}`;
+        if (config.shard)
+            return "one shard";
+        const all = (await project.globTestFiles()).testFiles.length;
+        const ran = project.vitest.state.getFiles().filter((f) => f.projectName === project.name).length;
+        if (ran > 0 && ran < all)
+            return `${ran} of ${all} files`;
+    }
+    catch {
+        // An API this Vitest version lacks: treat the run as complete, as before.
+    }
+    return undefined;
+}
+async function reportCoverage(opts, dir, partial) {
     try {
         const hits = new Set();
         for (const file of await readdir(dir)) {
@@ -111,11 +140,12 @@ async function reportCoverage(opts, dir) {
         const report = formatCoverage(spec, hits);
         // For `slicetest gen --uncovered`.
         const cache = coverageCacheFile(opts.root);
-        await mkdir(path.dirname(cache), { recursive: true }).then(() => writeFile(cache, JSON.stringify([...hits]))).catch(() => { });
-        console.log(`\n${report.text}\n`);
+        if (!partial)
+            await mkdir(path.dirname(cache), { recursive: true }).then(() => writeFile(cache, JSON.stringify([...hits]))).catch(() => { });
+        console.log(`\n${report.text}${partial ? `\n(partial run: ${partial}; openapi.minCoverage is checked on full runs)` : ""}\n`);
         await appendSummary(report.markdown);
         const min = opts.openapi.minCoverage;
-        if (min !== undefined && report.percent < min) {
+        if (min !== undefined && report.percent < min && !partial) {
             // Not thrown: Vitest reports teardown errors as a crash. The failing exit code is what CI needs.
             const message = `OpenAPI coverage ${report.percent}% is below openapi.minCoverage (${min}%)`;
             console.error(`slicetest: ${message}\n`);
@@ -129,6 +159,36 @@ async function reportCoverage(opts, dir) {
         await rm(appSpecFile(dir), { force: true });
     }
 }
+async function reportUsage(opts, dir) {
+    try {
+        const used = new Map();
+        for (const file of await readdir(dir)) {
+            for (const [name, keys] of Object.entries(JSON.parse(await readFile(path.join(dir, file), "utf8")))) {
+                const set = used.get(name) ?? new Set();
+                for (const k of keys)
+                    set.add(k);
+                used.set(name, set);
+            }
+        }
+        for (const [name, file] of Object.entries(opts.openapi.stubs)) {
+            const keys = used.get(name);
+            if (!keys)
+                continue;
+            const report = formatUsage(name, await OpenApiSpec.load(path.resolve(opts.root, file), file), keys);
+            console.log(`\n${report.text}\n`);
+            await appendSummary(report.markdown);
+            if (onGitHub() && report.deprecated.length) {
+                console.log(annotation("warning", `The app calls operations ${file} marks deprecated: ${report.deprecated.join(", ")}`, { file: repoPath(path.resolve(opts.root, file)), title: `slicetest: deprecated ${name} API` }));
+            }
+        }
+    }
+    catch (e) {
+        console.error(`slicetest: couldn't report API usage: ${e.message}`);
+    }
+    finally {
+        await rm(dir, { recursive: true, force: true });
+    }
+}
 async function reportToGitHub(dir) {
     try {
         const failures = await yamlFailures(dir);
@@ -268,8 +328,13 @@ async function applyMigrations(opts, engine, url, m) {
         }
         return "";
     }
-    // Through the platform shell (sh or cmd.exe), like app.command.
-    return run(m.command, [], opts.root, { DATABASE_URL: url }, true);
+    // Through the platform shell (sh or cmd.exe), like app.command, with the same {{db.*}} placeholders.
+    const vars = { "db.url": url };
+    if (engine.name === "sqlite")
+        vars["db.path"] = (await import("./drivers/sqlite.js")).sqlitePath(url);
+    Object.assign(vars, connectionVars(engine.name, url, vars["db.path"]));
+    const env = Object.fromEntries(Object.entries(m.env ?? {}).map(([k, v]) => [k, interpolate(v, vars, `db.migrate.env.${k}`)]));
+    return run(interpolate(m.command, vars, "db.migrate.command"), [], opts.root, { DATABASE_URL: url, ...env }, true);
 }
 /**
  * Atlas wants `file://<path>` with forward slashes. Absolute paths (including

package/dist/graphql.d.ts

@@ -0,0 +1,34 @@
+/**
+ * GraphQL over HTTP, as clients send it (Apollo, urql, graphql-request, gql, …):
+ * a POST with `{ query, variables, operationName }`, or a GET with those as query
+ * parameters. Stubs match calls by operation, and the app's own GraphQL endpoint
+ * is called with `http.graphql()`.
+ */
+export interface GraphQLCall {
+    /** `operationName` from the request, else the name in the document (`query GetUser { … }`). Undefined for an anonymous operation. */
+    operation?: string;
+    type: "query" | "mutation" | "subscription";
+    query: string;
+    variables: Record<string, unknown>;
+}
+/** The operations a document defines, in order. Comments and strings don't count. */
+export declare function operations(document: string): {
+    type: GraphQLCall["type"];
+    name?: string;
+}[];
+/** The GraphQL request in an HTTP call, or undefined when it isn't one. */
+export declare function graphqlOf(call: {
+    method: string;
+    query: URLSearchParams;
+    json: any;
+}): GraphQLCall | undefined;
+/** A GraphQL error list from messages or full error objects. */
+export declare function graphqlErrors(errors: (string | {
+    message: string;
+    [k: string]: unknown;
+})[]): {
+    [k: string]: unknown;
+    message: string;
+}[];
+/** `GraphQL mutation CreateIssue`, for failure messages. */
+export declare function describeGraphQL(g: GraphQLCall): string;