slicetest 0.6.0 → 0.7.0

package/dist/init.js

@@ -1,4 +1,4 @@
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { mkdir, readdir, readFile, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { parse, stringify } from "yaml";
@@ -15,7 +15,11 @@ const KNOWN_APIS = [
     { packages: ["twilio"], stub: "twilio", hosts: ["api.twilio.com"], env: { TWILIO_ACCOUNT_SID: "AC00000000000000000000000000000000", TWILIO_AUTH_TOKEN: "slicetest" } },
 ];
 /** Files that mark a directory as an app slicetest can start. */
-const APP_MARKERS = ["manage.py", "requirements.txt", "pyproject.toml", "Gemfile", "go.mod", "Cargo.toml", "build.gradle", "build.gradle.kts", "pom.xml"];
+const APP_MARKERS = ["manage.py", "requirements.txt", "pyproject.toml", "Gemfile", "go.mod", "Cargo.toml", "build.gradle", "build.gradle.kts", "pom.xml", "composer.json", "mix.exs", "deno.json", "deno.jsonc"];
+/** A fixed Phoenix SECRET_KEY_BASE for tests (it must be at least 64 bytes). */
+const PHOENIX_SECRET = "slicetest-secret-key-base-for-tests-only-".padEnd(64, "0");
+/** A fixed Laravel APP_KEY for tests (32 bytes), so encrypted cookies and sessions work without `key:generate`. */
+const LARAVEL_KEY = `base64:${Buffer.from("slicetest-app-key-for-tests-only").toString("base64")}`;
 /** Build files of a Gradle or Maven multi-project build (two levels down), for dependencies declared in a subproject. */
 async function subprojectBuildFiles(dir, gradle) {
     const names = gradle ? ["build.gradle", "build.gradle.kts"] : ["pom.xml"];
@@ -36,11 +40,32 @@ async function subprojectBuildFiles(dir, gradle) {
     await walk(dir, 1);
     return texts;
 }
+/** The ASP.NET Core project (Sdk="Microsoft.NET.Sdk.Web") in `dir` or two levels below it (src/Api/Api.csproj). */
+async function findWebProject(dir) {
+    const found = [];
+    const walk = async (d, depth) => {
+        for (const entry of await readdir(path.join(dir, d), { withFileTypes: true }).catch(() => [])) {
+            const rel = d ? `${d}/${entry.name}` : entry.name;
+            if (entry.isFile() && entry.name.endsWith(".csproj"))
+                found.push({ file: rel, text: await readFile(path.join(dir, rel), "utf8") });
+            else if (entry.isDirectory() && depth < 2 && !entry.name.startsWith(".") && !["bin", "obj", "node_modules", "tests", "test"].includes(entry.name))
+                await walk(rel, depth + 1);
+        }
+    };
+    await walk("", 0);
+    // Test projects reference the web project too; the web SDK is what marks the app.
+    return found.find((p) => /Sdk="Microsoft\.NET\.Sdk\.Web"/.test(p.text) && !/\.Tests?\.csproj$/.test(p.file));
+}
 /** Where monorepos usually keep the server, when the root isn't one. */
 const APP_DIRS = ["backend", "server", "api", "app", "service"];
 function runnable(dir) {
     if (APP_MARKERS.some((f) => existsSync(path.join(dir, f))))
         return true;
+    try {
+        if (readdirSync(dir).some((f) => f.endsWith(".csproj") || f.endsWith(".sln") || f.endsWith(".slnx")))
+            return true;
+    }
+    catch { }
     try {
         const scripts = JSON.parse(readFileSync(path.join(dir, "package.json"), "utf8")).scripts ?? {};
         return !!(scripts.start || scripts.dev);
@@ -62,6 +87,23 @@ export async function detect(root) {
     const deps = { ...pkg?.dependencies, ...pkg?.devDependencies };
     const python = `${await read("requirements.txt")}\n${await read("pyproject.toml")}`.toLowerCase();
     const gemfile = await read("Gemfile");
+    const composer = has("composer.json") ? JSON.parse(await read("composer.json")) : undefined;
+    const php = { ...composer?.require, ...composer?.["require-dev"] };
+    const laravel = !!php["laravel/framework"] && has("artisan");
+    const symfony = !laravel && !!php["symfony/framework-bundle"] && has("bin/console");
+    const mix = await read("mix.exs");
+    const phoenix = /:phoenix\b/.test(mix);
+    const denoConfig = has("deno.json") ? "deno.json" : has("deno.jsonc") ? "deno.jsonc" : undefined;
+    let denoTasks = {};
+    try {
+        denoTasks = denoConfig ? (JSON.parse((await read(denoConfig)).replace(/^\s*\/\/.*$/gm, "")).tasks ?? {}) : {};
+    }
+    catch { }
+    // The package manager the lockfile belongs to runs the scripts (Bun scripts may call `bun` itself).
+    const pm = has("bun.lock") || has("bun.lockb") ? "bun" : has("pnpm-lock.yaml") ? "pnpm" : has("yarn.lock") ? "yarn" : "npm";
+    const dotnet = !pkg?.scripts?.start && !pkg?.scripts?.dev ? await findWebProject(appRoot) : undefined;
+    const nuget = new Set([...(dotnet?.text.matchAll(/<PackageReference\s+Include="([^"]+)"/g) ?? [])].map((m) => m[1].toLowerCase()));
+    let dotnetConnection;
     // --- app ---
     let command = TODO_COMMAND;
     let jvmBuild;
@@ -72,17 +114,35 @@ export async function detect(root) {
     let readyTimeout;
     const env = { PORT: "{{app.port}}", DATABASE_URL: "{{db.url}}" };
     if (pkg?.scripts?.start) {
-        command = "npm start";
-        notes.push("app: `npm start` (package.json start script). It must listen on $PORT.");
+        command = pm === "npm" ? "npm start" : `${pm} run start`;
+        notes.push(`app: \`${command}\` (package.json start script${pm === "npm" ? "" : `, ${pm} from its lockfile`}). It must listen on $PORT.`);
         if (pkg.scripts.build) {
             // Otherwise `next start` and the like serve whatever was built last, and scenarios pass against stale code.
-            build = "npm run build";
-            notes.push("app: `npm run build` once per run, before starting (package.json build script).");
+            build = `${pm} run build`;
+            notes.push(`app: \`${build}\` once per run, before starting (package.json build script).`);
         }
     }
     else if (pkg?.scripts?.dev) {
-        command = "npm run dev";
-        notes.push("app: `npm run dev` (no start script). A production start command is usually faster to boot.");
+        command = `${pm} run dev`;
+        notes.push(`app: \`${command}\` (no start script). A production start command is usually faster to boot.`);
+    }
+    else if (denoConfig) {
+        const task = ["start", "serve", "dev"].find((t) => t in denoTasks);
+        const main = ["main.ts", "server.ts", "src/main.ts", "mod.ts"].find(has);
+        command = task ? `deno task ${task}` : `deno run --allow-net --allow-env --allow-read ${main ?? "main.ts"}`;
+        notes.push(`app: Deno (${denoConfig}), \`${command}\`. It must listen on Deno.env.get("PORT").`);
+    }
+    else if (phoenix) {
+        // Phoenix reads PORT and DATABASE_URL in config/runtime.exs for prod only; dev.exs hard-codes port 4000.
+        command = "mix phx.server";
+        build = "mix compile";
+        Object.assign(env, { MIX_ENV: "prod", PHX_SERVER: "true", PHX_HOST: "127.0.0.1", SECRET_KEY_BASE: PHOENIX_SECRET });
+        readyTimeout = 60_000;
+        notes.push("app: Phoenix in MIX_ENV=prod, where config/runtime.exs reads PORT and DATABASE_URL (dev.exs hard-codes them). SECRET_KEY_BASE is a fixed test key. Run `MIX_ENV=prod mix deps.get` once first");
+    }
+    else if (mix) {
+        command = "mix run --no-halt";
+        notes.push("app: Elixir (mix.exs). It must listen on $PORT.");
     }
     else if (has("manage.py")) {
         command = "python manage.py runserver 127.0.0.1:{{app.port}} --noreload";
@@ -100,6 +160,48 @@ export async function detect(root) {
         command = "bin/rails server -p {{app.port}}";
         notes.push("app: Rails");
     }
+    else if (dotnet) {
+        // Built once, then run without building, so workers don't compile at the same time; launch profiles would override the URL.
+        build = `dotnet build ${dotnet.file} -v q`;
+        command = `dotnet run --project ${dotnet.file} --no-build --no-launch-profile`;
+        delete env.PORT;
+        delete env.DATABASE_URL;
+        const dir = path.posix.dirname(dotnet.file);
+        let settings = {};
+        try {
+            settings = JSON.parse((await read(path.posix.join(dir, "appsettings.json"))).replace(/^\uFEFF/, "") || "{}");
+        }
+        catch { }
+        dotnetConnection = Object.keys(settings.ConnectionStrings ?? {})[0] ?? "DefaultConnection";
+        Object.assign(env, { ASPNETCORE_URLS: "http://127.0.0.1:{{app.port}}", ASPNETCORE_ENVIRONMENT: "Development" });
+        readyTimeout = 60_000;
+        const program = await read(path.posix.join(dir, "Program.cs"));
+        const health = /MapHealthChecks\(\s*"([^"]+)"/.exec(program)?.[1];
+        if (health)
+            readyPath = health;
+        notes.push(`app: ASP.NET Core (${dotnet.file}), built once with \`dotnet build\` and started with \`dotnet run --no-build\` at ASPNETCORE_URLS`);
+    }
+    else if (laravel) {
+        // `artisan serve` is PHP's built-in server; Laravel reads DB_* (set below, once the engine is known).
+        command = "php artisan serve --host=127.0.0.1 --port={{app.port}} --no-reload";
+        delete env.PORT;
+        delete env.DATABASE_URL;
+        Object.assign(env, { APP_ENV: "local", APP_KEY: LARAVEL_KEY, APP_DEBUG: "true", LOG_CHANNEL: "stderr" });
+        if (/health:\s*['"]\/up['"]/.test(await read("bootstrap/app.php")))
+            readyPath = "/up";
+        notes.push("app: Laravel (php artisan serve). DB_* variables point Laravel at the test database; APP_KEY is a fixed test key; logs go to stderr so failures show them");
+    }
+    else if (symfony) {
+        command = "php -S 127.0.0.1:{{app.port}} -t public";
+        delete env.PORT;
+        Object.assign(env, { APP_ENV: "dev", APP_DEBUG: "1" });
+        notes.push("app: Symfony, served by PHP's built-in server from public/. Doctrine reads DATABASE_URL");
+    }
+    else if (composer && has("public/index.php")) {
+        command = "php -S 127.0.0.1:{{app.port}} -t public";
+        delete env.PORT;
+        notes.push("app: PHP (composer.json), served by PHP's built-in server from public/");
+    }
     else if (has("build.gradle") || has("build.gradle.kts") || has("pom.xml")) {
         const gradle = !has("pom.xml");
         const buildFile = await read(gradle ? (has("build.gradle.kts") ? "build.gradle.kts" : "build.gradle") : "pom.xml");
@@ -154,6 +256,23 @@ export async function detect(root) {
         migrate = { atlas: { dir: `file://${atlas}` } };
         notes.push(`db: Atlas migrations in ${atlas}/`);
     }
+    else if (phoenix && has("priv/repo/migrations")) {
+        migrate = { command: "mix ecto.migrate", inputs: ["priv/repo/migrations"], env: { MIX_ENV: "prod", SECRET_KEY_BASE: PHOENIX_SECRET } };
+        notes.push("db: Ecto migrations (mix ecto.migrate, in MIX_ENV=prod like the app)");
+    }
+    else if (dotnet && nuget.has("microsoft.entityframeworkcore.design") && has(path.posix.join(path.posix.dirname(dotnet.file), "Migrations"))) {
+        const migrations = path.posix.join(path.posix.dirname(dotnet.file), "Migrations");
+        migrate = { command: `dotnet ef database update --project ${dotnet.file}`, inputs: [migrations] };
+        notes.push(`db: EF Core migrations in ${migrations}/ (dotnet ef database update; install it with \`dotnet tool install --global dotnet-ef\`)`);
+    }
+    else if (laravel) {
+        migrate = { command: "php artisan migrate --force", inputs: ["database/migrations"] };
+        notes.push("db: Laravel migrations (php artisan migrate), given the same DB_* variables as the app");
+    }
+    else if (symfony && php["doctrine/doctrine-migrations-bundle"]) {
+        migrate = { command: "php bin/console doctrine:migrations:migrate --no-interaction", inputs: ["migrations"] };
+        notes.push("db: Doctrine migrations (doctrine:migrations:migrate)");
+    }
     else if (has("prisma/schema.prisma")) {
         migrate = { command: "npx prisma migrate deploy", inputs: ["prisma/migrations"] };
         notes.push("db: Prisma (prisma migrate deploy)");
@@ -201,7 +320,7 @@ export async function detect(root) {
         if ("sql" in migrate)
             migrate = { sql: path.posix.join(appDir, migrate.sql) };
         else
-            migrate = { command: `cd ${appDir} && ${migrate.command}`, ...(migrate.inputs ? { inputs: migrate.inputs.map((i) => path.posix.join(appDir, i)) } : {}) };
+            migrate = { ...migrate, command: `cd ${appDir} && ${migrate.command}`, ...(migrate.inputs ? { inputs: migrate.inputs.map((i) => path.posix.join(appDir, i)) } : {}) };
     }
     // --- docker compose: the database image and other dependencies ---
     const { db: composeDb, containers, appEnv, mail: composeMail } = await fromCompose(root, notes, [...new Set(["", appDir])]);
@@ -249,11 +368,53 @@ export async function detect(root) {
         notes.push("auth: Clerk. Sessions are tokens from slicetest's issuer (auth: true); the clerk stub serves its keys at /v1/jwks and users at /v1/users/:id. See the README's Clerk section");
     }
     notes.push("network: URLs written in the code (https://api.example.com) can be stubbed with `hosts`. Add `offline: true` and the first run names every host the app calls");
-    const mysqlDeps = !!deps.mysql2 || !!deps.mysql || /\b(pymysql|mysqlclient|aiomysql)\b/.test(python) || /\bgem ['"]mysql2['"]/.test(gemfile);
+    const mysqlDeps = !!deps.mysql2 || !!deps.mysql || /\b(pymysql|mysqlclient|aiomysql)\b/.test(python) || /\bgem ['"]mysql2['"]/.test(gemfile) || /:myxql\b/.test(mix);
     if (!composeDb.engine && mysqlDeps) {
         composeDb.engine = "mysql";
         notes.push("db: MySQL (a MySQL driver is a dependency). Install mysql2 and @testcontainers/mysql next to slicetest.");
     }
+    if (dotnet) {
+        if (!composeDb.engine && [...nuget].some((n) => /^(pomelo\.entityframeworkcore\.mysql|mysqlconnector|mysql\.data|mysql\.entityframeworkcore)$/.test(n))) {
+            composeDb.engine = "mysql";
+            notes.push("db: MySQL (a MySQL provider is a NuGet dependency). Install mysql2 and @testcontainers/mysql next to slicetest.");
+        }
+        else if (!composeDb.engine && nuget.has("microsoft.entityframeworkcore.sqlite") && ![...nuget].some((n) => n.startsWith("npgsql"))) {
+            composeDb.engine = "sqlite";
+            notes.push("db: SQLite (Microsoft.EntityFrameworkCore.Sqlite), no container needed");
+        }
+        // ASP.NET reads ConnectionStrings:<name> from ConnectionStrings__<name>; `dotnet ef` builds the same host, so it reads it too.
+        const dbEnv = { [`ConnectionStrings__${dotnetConnection}`]: "{{db.adoNet}}" };
+        Object.assign(env, dbEnv);
+        if (migrate && "command" in migrate)
+            migrate = { ...migrate, env: dbEnv };
+        notes.push(`db: ConnectionStrings__${dotnetConnection} is the test database as an ADO.NET connection string ({{db.adoNet}})`);
+    }
+    if (laravel) {
+        // Laravel names its connection in .env (DB_CONNECTION=sqlite is the default of new projects).
+        const connection = /^\s*DB_CONNECTION\s*=\s*["']?(\w+)/m.exec(exampleText)?.[1];
+        if (!composeDb.engine && connection === "sqlite") {
+            composeDb.engine = "sqlite";
+            notes.push("db: SQLite (DB_CONNECTION=sqlite in .env.example), no container needed");
+        }
+        else if (!composeDb.engine && (connection === "mysql" || connection === "mariadb")) {
+            composeDb.engine = "mysql";
+            notes.push(`db: MySQL (DB_CONNECTION=${connection} in .env.example). Install mysql2 and @testcontainers/mysql next to slicetest.`);
+        }
+        const dbEnv = composeDb.engine === "sqlite"
+            ? { DB_CONNECTION: "sqlite", DB_DATABASE: "{{db.path}}" }
+            : { DB_CONNECTION: composeDb.engine === "mysql" ? "mysql" : "pgsql", DB_HOST: "{{db.host}}", DB_PORT: "{{db.port}}", DB_DATABASE: "{{db.name}}", DB_USERNAME: "{{db.user}}", DB_PASSWORD: "{{db.password}}" };
+        if (env.DATABASE_URL?.startsWith("{{"))
+            delete env.DATABASE_URL;
+        Object.assign(env, dbEnv);
+        if (migrate && "command" in migrate)
+            migrate = { ...migrate, env: dbEnv };
+        if (mail) {
+            delete env.SMTP_HOST;
+            delete env.SMTP_PORT;
+            Object.assign(env, { MAIL_MAILER: "smtp", MAIL_HOST: "{{mail.host}}", MAIL_PORT: "{{mail.port}}" });
+            notes.push("mail: Laravel's MAIL_MAILER=smtp, MAIL_HOST and MAIL_PORT point at slicetest's SMTP server");
+        }
+    }
     // --- OpenAPI ---
     const openapi = ["openapi.yaml", "openapi.yml", "openapi.json", "docs/openapi.yaml", "docs/openapi.yml", "docs/openapi.json"].find(has);
     if (openapi)
@@ -265,12 +426,19 @@ export async function detect(root) {
     const dbLibrary = Object.keys(deps).some((d) => /^(pg|postgres|mysql2?|@prisma\/client|prisma|drizzle-orm|knex|typeorm|sequelize|kysely|better-sqlite3|sqlite3|@neondatabase\/serverless|@vercel\/postgres|@libsql\/client|mongoose|mongodb)$/.test(d)) ||
         /data-jpa|data-jdbc|spring-jdbc|r2dbc|postgresql|mysql|flyway|liquibase|hibernate/.test(jvmBuild ?? "") ||
         /\b(psycopg|sqlalchemy|asyncpg|pymysql|mysqlclient|django|peewee|tortoise|sqlmodel)\b/.test(python) ||
-        /\b(rails|activerecord|sequel|pg|mysql2|sqlite3)\b/.test(gemfile);
-    const knownStack = !!pkg || jvmBuild !== undefined || python.trim().length > 0 || gemfile.length > 0;
+        /\b(rails|activerecord|sequel|pg|mysql2|sqlite3)\b/.test(gemfile) ||
+        Object.keys(php).some((d) => /^(laravel\/framework|illuminate\/database|doctrine\/(orm|dbal)|doctrine\/doctrine-bundle)$/.test(d)) ||
+        [...nuget].some((n) => /^(microsoft\.entityframeworkcore|npgsql|dapper|mysqlconnector|pomelo\.|microsoft\.data\.sqlite)/.test(n)) ||
+        /:(ecto_sql|postgrex|myxql|ecto_sqlite3)\b/.test(mix);
+    const knownStack = !!pkg || jvmBuild !== undefined || python.trim().length > 0 || gemfile.length > 0 || !!composer || !!dotnet || !!mix;
     const noDb = knownStack && !dbLibrary && !migrate && !composeDb.engine && !composeDb.image && !has("manage.py");
     if (noDb) {
-        for (const k of ["DATABASE_URL", "SPRING_DATASOURCE_URL", "SPRING_DATASOURCE_USERNAME", "SPRING_DATASOURCE_PASSWORD"])
-            delete env[k];
+        // Whatever was meant to reach the database (DATABASE_URL, SPRING_DATASOURCE_*, ConnectionStrings__*).
+        for (const [k, v] of Object.entries(env))
+            if (v.includes("{{db."))
+                delete env[k];
+        for (let i = notes.findIndex((n) => n.startsWith("db: ConnectionStrings__")); i >= 0; i = notes.findIndex((n) => n.startsWith("db: ConnectionStrings__")))
+            notes.splice(i, 1);
         const i = notes.indexOf("db: no migrations found; the database starts empty. Set db.migrate.");
         if (i >= 0)
             notes.splice(i, 1);
@@ -468,7 +636,8 @@ async function fromCompose(root, notes, dirs = [""]) {
     }
     for (const [name, svc] of Object.entries(doc.services ?? {})) {
         const image = typeof svc?.image === "string" ? svc.image : undefined;
-        if (!image) {
+        // A service built from source (with or without an image name for the result, like Laravel Sail's) is usually the app.
+        if (!image || svc?.build) {
             if (svc?.build)
                 notes.push(`${file}: service "${name}" is built from source; if it's the app, app.command replaces it`);
             continue;

package/dist/matchers.d.ts

@@ -6,6 +6,15 @@ interface SlicetestMatchers<R = unknown> {
     toHaveReceived(method: string, path: string | RegExp, match?: MatchOptions): R;
     /** The stub received exactly `n` calls matching `method path`. */
     toHaveReceivedTimes(n: number, method?: string, path?: string | RegExp, match?: MatchOptions): R;
+    /** The stub received a GraphQL request for `operation` (with `variables` as a subset, if given). */
+    toHaveReceivedGraphQL(operation: string | RegExp, variables?: unknown): R;
+    /** A GraphQL response without `errors`, whose `data` contains `expected` (if given). The failure message shows the errors. */
+    toHaveGraphQLData(expected?: unknown): R;
+    /**
+     * The value (a response's JSON, for a response) matches a JSON Schema: an object, or a file
+     * relative to the working directory with an optional pointer, `openapi.yaml#/components/schemas/Poll`.
+     */
+    toMatchSchema(schema: object | string): R;
     /** The response has this status; the failure message shows the response body. */
     toHaveStatus(status: number): R;
     /** An array of responses has exactly these status counts, e.g. `{ 201: 1, 409: 9 }`. */

package/dist/matchers.js

@@ -1,12 +1,16 @@
 import { expect } from "vitest";
 import { Db } from "./db.js";
-import { Stub } from "./stub.js";
+import { describeGraphQL } from "./graphql.js";
+import { schemaProblems } from "./schema.js";
+import { Stub, subset } from "./stub.js";
 const MAX_SHOWN = 5;
 function describeCalls(calls) {
     if (calls.length === 0)
         return "  (no calls)";
     const shown = calls.slice(-MAX_SHOWN).map((c) => {
         const q = c.query.size ? `?${c.query}` : "";
+        if (c.graphql)
+            return `  ${describeGraphQL(c.graphql)} (${c.method} ${c.path})  variables ${JSON.stringify(c.graphql.variables)}`;
         const body = c.body ? `  ${c.body.length > 200 ? `${c.body.slice(0, 200)}…` : c.body}` : "";
         return `  ${c.method} ${c.path}${q}${body}`;
     });
@@ -59,6 +63,48 @@ expect.extend({
             expected: n,
         };
     },
+    toHaveReceivedGraphQL(received, operation, variables) {
+        assertStub(received);
+        const pass = received.calls("*", undefined, { graphql: { operation, variables } }).length > 0;
+        const cond = variables === undefined ? "" : ` with variables ${this.utils.stringify(variables)}`;
+        return {
+            pass,
+            message: () => `expected stub "${received.name}" ${pass ? "not " : ""}to have received GraphQL ${operation}${cond}\n` +
+                `Calls received:\n${describeCalls(received.calls())}`,
+        };
+    },
+    toHaveGraphQLData(received, expected) {
+        const body = received?.json;
+        const errors = body && typeof body === "object" ? body.errors : undefined;
+        const isGraphQL = body && typeof body === "object" && ("data" in body || "errors" in body);
+        const hasErrors = Array.isArray(errors) && errors.length > 0;
+        const pass = received?.status === 200 && isGraphQL && !hasErrors && (expected === undefined || subset(expected, body.data));
+        return {
+            pass,
+            message: () => {
+                const head = `expected ${received.method} ${received.url} ${this.isNot ? "not " : ""}to answer GraphQL data${expected === undefined ? "" : ` containing ${this.utils.stringify(expected)}`}`;
+                if (!isGraphQL)
+                    return `${head}, got status ${received.status} without data or errors:\n  ${received.text.slice(0, 1000) || "(empty)"}`;
+                if (hasErrors)
+                    return `${head}, got errors:\n${errors.map((e) => `  ${e.message}${e.path ? ` (at ${e.path.join(".")})` : ""}`).join("\n")}`;
+                return `${head}, got status ${received.status} and data:\n  ${JSON.stringify(body.data)}`;
+            },
+            actual: body?.data,
+            expected,
+        };
+    },
+    toMatchSchema(received, schema) {
+        const isResponse = !!received && typeof received === "object" && "status" in received && received.headers instanceof Headers;
+        const value = isResponse ? received.json : received;
+        const problems = schemaProblems(schema, value);
+        const what = isResponse ? `${received.method} ${received.url}'s JSON` : "the value";
+        return {
+            pass: problems.length === 0,
+            message: () => problems.length
+                ? `expected ${what} to match ${typeof schema === "string" ? schema : "the schema"}:\n${problems.map((p) => `  ${p}`).join("\n")}\nValue:\n  ${JSON.stringify(value)?.slice(0, 1000)}`
+                : `expected ${what} not to match ${typeof schema === "string" ? schema : "the schema"}`,
+        };
+    },
     toHaveStatus(received, status) {
         const pass = received?.status === status;
         return {

package/dist/openapi.d.ts

@@ -47,6 +47,16 @@ export declare class OpenApiSpec {
     /** Problems with a response to `method path`; empty when it matches the spec. */
     /** The documented response (`200`, `4XX`, `default`) that `status` falls under, for coverage. */
     responseKey(method: string, path: string, status: number): string | undefined;
+    /** The documented operation `method path` falls under, as `METHOD /template`, and whether the spec deprecates it. */
+    operationOf(method: string, path: string): {
+        key: string;
+        deprecated: boolean;
+    } | undefined;
+    /** Every documented operation as `METHOD /template`, with its `deprecated` flag. */
+    operationKeys(): {
+        key: string;
+        deprecated: boolean;
+    }[];
     /** Every documented response as `METHOD /template key`, in document order. */
     responseKeys(): string[];
     checkResponse(method: string, path: string, res: Message): string[];
@@ -80,6 +90,17 @@ export declare function formatCoverage(spec: OpenApiSpec, hits: Set<string>): {
     markdown: string;
     text: string;
 };
+/** OpenAPI 3.0's `nullable: true` → JSON Schema's `type: [T, "null"]`. */
+export declare function nullableToType(node: any): any;
+/**
+ * Which of a provider's operations the app called during the run: its dependency
+ * surface on that API, with the operations the provider has deprecated flagged.
+ */
+export declare function formatUsage(name: string, spec: OpenApiSpec, used: Set<string>): {
+    text: string;
+    markdown: string;
+    deprecated: string[];
+};
 /** Where a spec fetched from the app (`openapi.fromApp`) is kept for the coverage report. */
 export declare function appSpecFile(coverageDir: string): string;
 export {};

package/dist/openapi.js

@@ -81,6 +81,15 @@ export class OpenApiSpec {
         const key = pickResponse(found.op.responses ?? {}, status);
         return key && `${method.toUpperCase()} ${found.template} ${key}`;
     }
+    /** The documented operation `method path` falls under, as `METHOD /template`, and whether the spec deprecates it. */
+    operationOf(method, path) {
+        const found = this.find(method, path);
+        return found && { key: `${method.toUpperCase()} ${found.template}`, deprecated: found.op.deprecated === true };
+    }
+    /** Every documented operation as `METHOD /template`, with its `deprecated` flag. */
+    operationKeys() {
+        return this.#documentOrder.map(({ template, method, op }) => ({ key: `${method.toUpperCase()} ${template}`, deprecated: op.deprecated === true }));
+    }
     /** Every documented response as `METHOD /template key`, in document order. */
     responseKeys() {
         return this.#documentOrder.flatMap(({ template, method, op }) => Object.keys(op.responses ?? {}).map((key) => `${method.toUpperCase()} ${template} ${key}`));
@@ -343,7 +352,7 @@ function escape(s) {
     return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
 /** OpenAPI 3.0's `nullable: true` → JSON Schema's `type: [T, "null"]`. */
-function nullableToType(node) {
+export function nullableToType(node) {
     if (Array.isArray(node))
         return node.map(nullableToType);
     if (!node || typeof node !== "object")
@@ -363,6 +372,28 @@ function nullableToType(node) {
     }
     return node;
 }
+/**
+ * Which of a provider's operations the app called during the run: its dependency
+ * surface on that API, with the operations the provider has deprecated flagged.
+ */
+export function formatUsage(name, spec, used) {
+    const ops = spec.operationKeys().filter((o) => used.has(o.key));
+    const deprecated = ops.filter((o) => o.deprecated);
+    const width = Math.max(0, ...ops.map((o) => o.key.length));
+    const text = [
+        `slicetest: the app used ${ops.length} of ${spec.operationKeys().length} operations of ${name} (${spec.file})${deprecated.length ? `, ${deprecated.length} deprecated` : ""}`,
+        ...ops.map((o) => `  ${o.key.padEnd(width)}${o.deprecated ? "  ⚠ deprecated" : ""}`),
+    ].join("\n");
+    const markdown = [
+        `### slicetest: ${name} API usage`,
+        "",
+        `The app called ${ops.length} of ${spec.operationKeys().length} operations in \`${spec.file}\`${deprecated.length ? `, **${deprecated.length} deprecated**` : ""}.`,
+        "",
+        ...ops.map((o) => `- \`${o.key}\`${o.deprecated ? " ⚠️ deprecated" : ""}`),
+        "",
+    ].join("\n");
+    return { text, markdown, deprecated: deprecated.map((o) => o.key) };
+}
 /** Where a spec fetched from the app (`openapi.fromApp`) is kept for the coverage report. */
 export function appSpecFile(coverageDir) {
     return `${coverageDir}.spec.json`;

package/dist/provided.d.ts

@@ -9,6 +9,7 @@ declare module "vitest" {
             coverageDir?: string;
             recordDir?: string;
             ciDir?: string;
+            usageDir?: string;
         };
     }
 }

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 };