slicetest 0.1.0 → 0.2.0

package/dist/drivers/postgres.js

@@ -0,0 +1,164 @@
+import pg from "pg";
+const INT8 = 20;
+/** int8 columns (bigserial ids, count(*)) come back as numbers when they fit, instead of strings. */
+const types = {
+    getTypeParser(oid, format) {
+        if (oid === INT8 && format !== "binary") {
+            return (v) => {
+                const n = Number(v);
+                return Number.isSafeInteger(n) ? n : v;
+            };
+        }
+        return pg.types.getTypeParser(oid, format);
+    },
+};
+export class PostgresDriver {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    static async connect(url) {
+        const client = new pg.Client({ connectionString: url, types });
+        // Without a listener, a dropped connection would crash the worker; the next query reports it instead.
+        client.on("error", () => { });
+        await client.connect();
+        return new PostgresDriver(client);
+    }
+    async query(sql, params = []) {
+        return (await this.client.query(sql, params)).rows;
+    }
+    async queryAll(sqls) {
+        if (sqls.length === 0)
+            return [];
+        // The simple query protocol runs several statements in one round trip.
+        const res = (await this.client.query(sqls.join(";\n")));
+        return (Array.isArray(res) ? res : [res]).map((r) => r.rows);
+    }
+    async exec(script) {
+        await this.client.query(script);
+    }
+    ident(name) {
+        return name
+            .split(".")
+            .map((part) => this.column(part))
+            .join(".");
+    }
+    column(name) {
+        return `"${name.replace(/"/g, '""')}"`;
+    }
+    param(n) {
+        return `$${n}`;
+    }
+    inList(column, values, params) {
+        params.push(values);
+        return `${this.ident(column)} = ANY($${params.length})`;
+    }
+    /** Ordinary and partitioned tables, skipping partitions and tables owned by extensions (e.g. PostGIS's `spatial_ref_sys`). */
+    async listTables(schemas, keep) {
+        const rows = await this.query(`SELECT n.nspname AS schema, c.relname AS name,
+              (SELECT array_agg(a.attname::text ORDER BY k.ord)
+                 FROM pg_index i
+                 CROSS JOIN LATERAL unnest(i.indkey) WITH ORDINALITY AS k(attnum, ord)
+                 JOIN pg_attribute a ON a.attrelid = c.oid AND a.attnum = k.attnum
+                WHERE i.indrelid = c.oid AND i.indisprimary) AS key
+         FROM pg_class c
+         JOIN pg_namespace n ON n.oid = c.relnamespace
+        WHERE c.relkind IN ('r', 'p')
+          AND NOT c.relispartition
+          AND n.nspname = ANY($1)
+          AND NOT (c.relname = ANY($2) OR n.nspname || '.' || c.relname = ANY($2))
+          AND NOT EXISTS (
+            SELECT 1 FROM pg_depend d
+             WHERE d.classid = 'pg_class'::regclass AND d.objid = c.oid AND d.deptype = 'e')
+        ORDER BY 1, 2`, [schemas, keep]);
+        return rows.map((r) => ({
+            name: r.schema === "public" ? r.name : `${r.schema}.${r.name}`,
+            quoted: `${this.ident(r.schema)}.${this.ident(r.name)}`,
+            key: r.key ?? [],
+        }));
+    }
+    async truncate(tables) {
+        if (tables.length > 0)
+            await this.client.query(`TRUNCATE ${tables.map((t) => t.quoted).join(", ")} RESTART IDENTITY CASCADE`);
+    }
+    async insert(table, row) {
+        const cols = Object.keys(row);
+        const sql = cols.length === 0
+            ? `INSERT INTO ${this.ident(table)} DEFAULT VALUES RETURNING *`
+            : `INSERT INTO ${this.ident(table)} (${cols.map((c) => this.ident(c)).join(", ")}) VALUES (${cols.map((_, i) => `$${i + 1}`).join(", ")}) RETURNING *`;
+        return this.query(sql, Object.values(row));
+    }
+    async close() {
+        await this.client.end();
+    }
+}
+function withDatabase(url, database) {
+    const u = new URL(url);
+    u.pathname = `/${database}`;
+    return u.toString();
+}
+function quote(name) {
+    return `"${name.replace(/"/g, '""')}"`;
+}
+class PostgresAdmin {
+    client;
+    url;
+    constructor(client, url) {
+        this.client = client;
+        this.url = url;
+    }
+    async databases(prefix) {
+        const { rows } = await this.client.query("SELECT datname FROM pg_database WHERE starts_with(datname, $1)", [prefix]);
+        return rows.map((r) => r.datname);
+    }
+    async create(name) {
+        await this.client.query(`CREATE DATABASE ${quote(name)}`);
+    }
+    async clone(template, name) {
+        await this.client.query(`CREATE DATABASE ${quote(name)} TEMPLATE ${quote(template)}`);
+    }
+    async drop(name) {
+        await this.client.query(`DROP DATABASE IF EXISTS ${quote(name)} WITH (FORCE)`);
+    }
+    async withLock(key, fn) {
+        await this.client.query("SELECT pg_advisory_lock(hashtext($1))", [key]);
+        try {
+            return await fn();
+        }
+        finally {
+            await this.client.query("SELECT pg_advisory_unlock(hashtext($1))", [key]);
+        }
+    }
+    urlFor(name) {
+        return withDatabase(this.url, name);
+    }
+    async close() {
+        await this.client.end();
+    }
+}
+export const postgres = {
+    name: "postgres",
+    defaultImage: "postgres:17-alpine",
+    async startContainer(image, reuse) {
+        const { PostgreSqlContainer } = await import("@testcontainers/postgresql");
+        const definition = new PostgreSqlContainer(image);
+        // A reused container is left running and found again by its configuration on the next run.
+        if (reuse)
+            definition.withReuse();
+        const container = await definition.start();
+        return { url: container.getConnectionUri(), stop: () => container.stop() };
+    },
+    async admin(url) {
+        const client = new pg.Client({ connectionString: url });
+        client.on("error", () => { });
+        await client.connect();
+        return new PostgresAdmin(client, url);
+    },
+    driver: (url) => PostgresDriver.connect(url),
+    atlasUrl(url) {
+        const u = new URL(url);
+        if (!u.searchParams.has("sslmode"))
+            u.searchParams.set("sslmode", "disable");
+        return u.toString();
+    },
+};

package/dist/global-setup.d.ts

@@ -1,7 +1,13 @@
 import type { TestProject } from "vitest/node";
+import type { ResolvedOptions } from "./config.js";
 import "./provided.js";
-/** Runs once per vitest run: start Postgres, migrate a template database, hand its location to the workers. */
+/** 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>>;
+/**
+ * A hash of everything that determines the migrated schema, or undefined when
+ * that can't be known (a migration command without `inputs`).
+ */
+export declare function migrationKey(opts: Pick<ResolvedOptions, "db" | "root">): Promise<string | undefined>;
 /**
  * Atlas wants `file://<path>` with forward slashes. Absolute paths (including
  * Windows drive paths) are made relative to the root, which is the cwd Atlas runs in.

package/dist/global-setup.js

@@ -1,16 +1,18 @@
 import { execFile } from "node:child_process";
-import { randomBytes } from "node:crypto";
-import { readdir, readFile, stat } from "node:fs/promises";
+import { createHash, randomBytes } from "node:crypto";
+import { mkdtemp, readdir, readFile, rm, stat } from "node:fs/promises";
+import os from "node:os";
 import path from "node:path";
 import { promisify } from "node:util";
-import pg from "pg";
 import { configureContainerRuntime } from "./container-runtime.js";
-import { withDatabase } from "./db.js";
+import { engineFor } from "./drivers/index.js";
+import { formatCoverage, OpenApiSpec } from "./openapi.js";
 import "./provided.js";
 const exec = promisify(execFile);
-/** Runs once per vitest run: start Postgres, migrate a template database, hand its location to the workers. */
+/** Runs once per vitest run: start the database server, migrate a template database, hand its location to the workers. */
 export default async function setup(project) {
     const opts = project.getProvidedContext().slicetestOptions;
+    const engine = engineFor(opts);
     let adminUrl;
     let stopContainer;
     if (opts.db.url) {
@@ -18,65 +20,165 @@ export default async function setup(project) {
     }
     else {
         configureContainerRuntime();
-        const { PostgreSqlContainer } = await import("@testcontainers/postgresql");
-        const container = await new PostgreSqlContainer(opts.db.image).start();
-        adminUrl = container.getConnectionUri();
-        stopContainer = () => container.stop();
+        const container = await engine.startContainer(opts.db.image, opts.db.reuse);
+        adminUrl = container.url;
+        if (!opts.db.reuse)
+            stopContainer = container.stop;
     }
     // Unique per run and project, so parallel runs and projects sharing one server never collide.
-    const prefix = `slicetest_${randomBytes(4).toString("hex")}`;
-    const template = `${prefix}_template`;
-    const admin = new pg.Client({ connectionString: adminUrl });
+    // The timestamp lets a later run recognise databases left behind by a run that was killed.
+    const prefix = `${RUN_PREFIX}${Date.now().toString(36)}_${randomBytes(3).toString("hex")}`;
+    let admin;
+    let template;
     try {
-        await admin.connect();
-        await admin.query(`CREATE DATABASE "${template}"`);
-        await migrate(opts, withDatabase(adminUrl, template));
+        admin = await engine.admin(adminUrl);
+        if (!stopContainer)
+            await dropStale(admin);
+        const key = opts.db.reuse ? await migrationKey(opts) : undefined;
+        template = key ? await cachedTemplate(admin, engine, opts, key) : await freshTemplate(admin, engine, opts, prefix);
     }
     catch (e) {
-        await admin.end().catch(() => { });
+        await admin?.close().catch(() => { });
         await stopContainer?.();
         throw e;
     }
-    project.provide("slicetestDb", { adminUrl, template, prefix });
+    const server = admin;
+    // Each worker writes the documented responses it saw here; they are merged when the run ends.
+    const coverageDir = opts.openapi.app ? await mkdtemp(path.join(os.tmpdir(), "slicetest-coverage-")) : undefined;
+    project.provide("slicetestDb", { adminUrl, template, prefix, coverageDir });
     return async () => {
         try {
             if (!stopContainer) {
                 // Shared server: drop only the databases this run created.
-                const { rows } = await admin.query("SELECT datname FROM pg_database WHERE starts_with(datname, $1)", [`${prefix}_`]);
-                for (const { datname } of rows)
-                    await admin.query(`DROP DATABASE "${datname}" WITH (FORCE)`);
+                for (const name of await server.databases(`${prefix}_`))
+                    await server.drop(name);
             }
         }
         finally {
-            await admin.end();
+            await server.close();
             await stopContainer?.();
+            if (coverageDir)
+                await reportCoverage(opts, coverageDir);
         }
     };
 }
-async function migrate(opts, url) {
+async function reportCoverage(opts, dir) {
+    try {
+        const hits = new Set();
+        for (const file of await readdir(dir)) {
+            for (const key of JSON.parse(await readFile(path.join(dir, file), "utf8")))
+                hits.add(key);
+        }
+        // No scenario ran (e.g. everything filtered out): nothing to report.
+        if (hits.size === 0)
+            return;
+        const spec = await OpenApiSpec.load(path.resolve(opts.root, opts.openapi.app), opts.openapi.app);
+        const report = formatCoverage(spec, hits);
+        console.log(`\n${report.text}\n`);
+        const min = opts.openapi.minCoverage;
+        if (min !== undefined && report.percent < min) {
+            // Not thrown: Vitest reports teardown errors as a crash. The failing exit code is what CI needs.
+            console.error(`slicetest: OpenAPI coverage ${report.percent}% is below openapi.minCoverage (${min}%)\n`);
+            process.exitCode = 1;
+        }
+    }
+    finally {
+        await rm(dir, { recursive: true, force: true });
+    }
+}
+const RUN_PREFIX = "slicetest_r";
+const TEMPLATE_PREFIX = "slicetest_tpl_";
+const STALE_MS = 24 * 60 * 60 * 1000;
+async function freshTemplate(admin, engine, opts, prefix) {
+    const template = `${prefix}_template`;
+    await admin.create(template);
+    await migrate(opts, engine, admin.urlFor(template));
+    return template;
+}
+/**
+ * The template for these migrations, built once and kept on the server. The
+ * lock makes concurrent runs wait for the first one instead of building their own.
+ */
+async function cachedTemplate(admin, engine, opts, key) {
+    const name = `${TEMPLATE_PREFIX}${key}`;
+    return admin.withLock(name, async () => {
+        if ((await admin.databases(name)).includes(name))
+            return name;
+        await admin.create(name);
+        try {
+            await migrate(opts, engine, admin.urlFor(name));
+        }
+        catch (e) {
+            // Never leave a half-migrated template behind for later runs to reuse.
+            await admin.drop(name).catch(() => { });
+            throw e;
+        }
+        return name;
+    });
+}
+/**
+ * A hash of everything that determines the migrated schema, or undefined when
+ * that can't be known (a migration command without `inputs`).
+ */
+export async function migrationKey(opts) {
+    const m = opts.db.migrate;
+    const hash = createHash("sha256").update(`v1\0${opts.db.image}\0${JSON.stringify(m ?? null)}\0`);
+    const inputs = !m ? [] : "atlas" in m ? [atlasDirPath(m.atlas.dir, opts.root)] : "sql" in m ? [path.resolve(opts.root, m.sql)] : m.inputs?.map((p) => path.resolve(opts.root, p));
+    if (!inputs)
+        return undefined;
+    for (const input of inputs) {
+        for (const file of await filesUnder(input)) {
+            hash.update(`${path.relative(opts.root, file).replace(/\\/g, "/")}\0`);
+            hash.update(await readFile(file));
+            hash.update("\0");
+        }
+    }
+    return hash.digest("hex").slice(0, 20);
+}
+async function filesUnder(target) {
+    const info = await stat(target).catch(() => undefined);
+    if (!info)
+        throw new Error(`slicetest: migration input not found: ${target}`);
+    if (!info.isDirectory())
+        return [target];
+    const entries = await readdir(target, { recursive: true, withFileTypes: true });
+    return entries
+        .filter((e) => e.isFile())
+        .map((e) => path.join(e.parentPath, e.name))
+        .sort();
+}
+function atlasDirPath(dir, root) {
+    return path.resolve(root, dir.replace(/^file:\/\//, ""));
+}
+/** Databases from runs that were killed before cleaning up, recognised by the timestamp in their name. */
+async function dropStale(admin) {
+    for (const datname of await admin.databases(RUN_PREFIX)) {
+        const started = parseInt(datname.slice(RUN_PREFIX.length).split("_")[0], 36);
+        if (Number.isFinite(started) && Date.now() - started > STALE_MS) {
+            await admin.drop(datname).catch(() => { });
+        }
+    }
+}
+async function migrate(opts, engine, url) {
     const m = opts.db.migrate;
     if (!m)
         return;
     if ("atlas" in m) {
         const dir = atlasDirUrl(m.atlas.dir, opts.root);
-        const u = new URL(url);
-        if (!u.searchParams.has("sslmode"))
-            u.searchParams.set("sslmode", "disable");
-        await run("atlas", ["migrate", "apply", "--url", u.toString(), "--dir", dir], opts.root);
+        await run("atlas", ["migrate", "apply", "--url", engine.atlasUrl(url), "--dir", dir], opts.root);
     }
     else if ("sql" in m) {
         const target = path.resolve(opts.root, m.sql);
         const files = (await stat(target)).isDirectory()
             ? (await readdir(target)).filter((f) => f.endsWith(".sql")).sort().map((f) => path.join(target, f))
             : [target];
-        const client = new pg.Client({ connectionString: url });
-        await client.connect();
+        const driver = await engine.driver(url);
         try {
             for (const file of files)
-                await client.query(await readFile(file, "utf8"));
+                await driver.exec(await readFile(file, "utf8"));
         }
         finally {
-            await client.end();
+            await driver.close();
         }
     }
     else {

package/dist/http.d.ts

@@ -19,6 +19,7 @@ export interface RequestOptions {
 declare class Session {
     cookies: Map<string, string>;
     history: HttpResponse[];
+    listeners: ((res: HttpResponse) => void)[];
 }
 /** HTTP client bound to the app under test. Keeps cookies for the duration of a scenario. */
 export declare class HttpClient {
@@ -38,6 +39,8 @@ export declare class HttpClient {
     patch(path: string, body?: unknown, opts?: RequestOptions): Promise<HttpResponse>;
     /** Strings, URLSearchParams, FormData, Blob and byte arrays are sent as-is; anything else is sent as JSON. */
     request(method: string, path: string, body?: unknown, options?: RequestOptions): Promise<HttpResponse>;
+    /** Call `fn` with every response this client (or one derived with `with()`) receives. */
+    onResponse(fn: (res: HttpResponse) => void): void;
     /** Cookies the app has set during this scenario. Mutations are sent with later requests. */
     get cookies(): Map<string, string>;
     clearCookies(): void;

package/dist/http.js

@@ -2,6 +2,7 @@
 class Session {
     cookies = new Map();
     history = [];
+    listeners = [];
 }
 const HISTORY = 20;
 /** HTTP client bound to the app under test. Keeps cookies for the duration of a scenario. */
@@ -96,8 +97,14 @@ export class HttpClient {
             durationMs: Math.round(performance.now() - started),
         };
         this.#record(out);
+        for (const listener of this.#session.listeners)
+            listener(out);
         return out;
     }
+    /** Call `fn` with every response this client (or one derived with `with()`) receives. */
+    onResponse(fn) {
+        this.#session.listeners.push(fn);
+    }
     #record(res) {
         this.#session.history.push(res);
         if (this.#session.history.length > HISTORY)

package/dist/index.d.ts

@@ -1,7 +1,8 @@
 export { scenario } from "./scenario.js";
 export type { ScenarioContext } from "./runtime.js";
-export type { Db, Row, Where, RowsOptions } from "./db.js";
+export type { Db, Row, Where, RowsOptions, Changes, TableChanges } from "./db.js";
 export type { Stub, RecordedCall, StubResponse, Responder, MatchOptions, RouteBuilder } from "./stub.js";
 export type { HttpClient, HttpResponse, RequestOptions } from "./http.js";
 export type { App } from "./app.js";
 export type { SlicetestOptions } from "./config.js";
+export type {} from "./matchers.js";

package/dist/init.d.ts

@@ -0,0 +1,18 @@
+import type { CliConfig } from "./cli.js";
+/**
+ * `npx slicetest init`: look at a project and write a starting
+ * slicetest.config.yaml plus one scenario. Detection is best effort; every
+ * guess is listed so the user knows what to check.
+ */
+export interface Detected {
+    config: CliConfig;
+    /** One line per guess, e.g. "app: package.json has a start script". */
+    notes: string[];
+}
+export declare function detect(root: string): Promise<Detected>;
+export declare function init(root: string, { force }?: {
+    force?: boolean | undefined;
+}): Promise<{
+    files: string[];
+    notes: string[];
+}>;

package/dist/init.js

@@ -0,0 +1,134 @@
+import { existsSync } from "node:fs";
+import { mkdir, readdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { stringify } from "yaml";
+const TODO_COMMAND = "echo 'TODO: the command that starts your app' && exit 1";
+export async function detect(root) {
+    const notes = [];
+    const has = (p) => existsSync(path.join(root, p));
+    const read = async (p) => (has(p) ? readFile(path.join(root, p), "utf8") : "");
+    const pkg = has("package.json") ? JSON.parse(await read("package.json")) : undefined;
+    const deps = { ...pkg?.dependencies, ...pkg?.devDependencies };
+    const python = `${await read("requirements.txt")}\n${await read("pyproject.toml")}`.toLowerCase();
+    const gemfile = await read("Gemfile");
+    // --- app ---
+    let command = TODO_COMMAND;
+    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.");
+    }
+    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.");
+    }
+    else if (has("manage.py")) {
+        command = "python manage.py runserver 127.0.0.1:{{app.port}} --noreload";
+        notes.push("app: Django (manage.py)");
+    }
+    else if (python.includes("uvicorn") || python.includes("fastapi")) {
+        command = "uvicorn main:app --port {{app.port}}";
+        notes.push("app: FastAPI/uvicorn. Adjust `main:app` to your module.");
+    }
+    else if (python.includes("flask")) {
+        command = "flask run --port {{app.port}}";
+        notes.push("app: Flask");
+    }
+    else if (/\brails\b/.test(gemfile)) {
+        command = "bin/rails server -p {{app.port}}";
+        notes.push("app: Rails");
+    }
+    else if (has("go.mod")) {
+        command = "go run .";
+        notes.push("app: Go (go.mod). It must listen on $PORT.");
+    }
+    else if (has("Cargo.toml")) {
+        command = "cargo run";
+        notes.push("app: Rust (Cargo.toml). It must listen on $PORT.");
+    }
+    else {
+        notes.push("app: couldn't tell how to start the app. Set app.command.");
+    }
+    // --- migrations ---
+    let migrate;
+    const migrationsSql = has("migrations") && (await readdir(path.join(root, "migrations"))).some((f) => f.endsWith(".sql"));
+    if (has("atlas.hcl") || has("migrations/atlas.sum")) {
+        migrate = { atlas: { dir: "file://migrations" } };
+        notes.push("db: Atlas migrations in migrations/");
+    }
+    else if (has("prisma/schema.prisma")) {
+        migrate = { command: "npx prisma migrate deploy", inputs: ["prisma/migrations"] };
+        notes.push("db: Prisma (prisma migrate deploy)");
+    }
+    else if (has("alembic.ini")) {
+        const location = /^\s*script_location\s*=\s*(\S+)/m.exec(await read("alembic.ini"))?.[1] ?? "alembic";
+        migrate = { command: "alembic upgrade head", inputs: [path.posix.join(location.replace("%(here)s/", ""), "versions")] };
+        notes.push("db: Alembic (alembic upgrade head)");
+    }
+    else if (has("manage.py")) {
+        migrate = { command: "python manage.py migrate" };
+        notes.push("db: Django migrations. Add `inputs` (your apps' migrations dirs) to cache them between runs.");
+    }
+    else if (/\brails\b/.test(gemfile) && has("db/migrate")) {
+        migrate = { command: "bin/rails db:migrate", inputs: ["db/migrate"] };
+        notes.push("db: Rails migrations");
+    }
+    else if (deps["drizzle-kit"]) {
+        migrate = { command: "npx drizzle-kit migrate", inputs: ["drizzle"] };
+        notes.push("db: Drizzle (drizzle-kit migrate). Check that `inputs` points at your migrations folder.");
+    }
+    else if (deps.knex) {
+        migrate = { command: "npx knex migrate:latest", inputs: ["migrations"] };
+        notes.push("db: Knex migrations");
+    }
+    else if (migrationsSql) {
+        migrate = { sql: "migrations" };
+        notes.push("db: plain SQL files in migrations/, applied in name order");
+    }
+    else if (has("schema.sql")) {
+        migrate = { sql: "schema.sql" };
+        notes.push("db: schema.sql");
+    }
+    else {
+        notes.push("db: no migrations found; the database starts empty. Set db.migrate.");
+    }
+    // --- OpenAPI ---
+    const openapi = ["openapi.yaml", "openapi.yml", "openapi.json", "docs/openapi.yaml", "docs/openapi.yml", "docs/openapi.json"].find(has);
+    if (openapi)
+        notes.push(`openapi: ${openapi}. Every response will be checked against it.`);
+    const config = {
+        app: { command, env, ready: { path: "/" } },
+        ...(migrate ? { db: { migrate } } : {}),
+        stubs: [],
+        ...(openapi ? { openapi } : {}),
+    };
+    return { config, notes };
+}
+const SCENARIO = `# yaml-language-server: $schema=https://unpkg.com/slicetest/schema/scenario.schema.json
+# A first scenario. Run it with: npx slicetest
+scenarios:
+  - name: the app answers
+    steps:
+      - request: GET /
+        expect: { status: 200 }
+`;
+export async function init(root, { force = false } = {}) {
+    const configFile = path.join(root, "slicetest.config.yaml");
+    const scenarioFile = path.join(root, "scenarios", "smoke.scenario.yaml");
+    const existing = [configFile, scenarioFile].filter((f) => existsSync(f));
+    if (existing.length && !force) {
+        throw new Error(`slicetest: ${existing.map((f) => path.relative(root, f)).join(", ")} already exists. Use --force to overwrite.`);
+    }
+    const { config, notes } = await detect(root);
+    const header = [
+        "# slicetest config, generated by `npx slicetest init`. Paths are relative to this file.",
+        "# Everything the Vitest plugin accepts works here: https://github.com/revo1290/slicetest#configuration-reference",
+        "#",
+        ...notes.map((n) => `# - ${n}`),
+        "",
+    ].join("\n");
+    await writeFile(configFile, `${header}${stringify(config)}`);
+    await mkdir(path.dirname(scenarioFile), { recursive: true });
+    await writeFile(scenarioFile, SCENARIO);
+    return { files: [configFile, scenarioFile].map((f) => path.relative(root, f)), notes };
+}

package/dist/openapi.d.ts

@@ -0,0 +1,56 @@
+interface Operation {
+    /** `paths` key, e.g. `/polls/{id}`. */
+    template: string;
+    method: string;
+    op: Record<string, any>;
+}
+export interface Message {
+    status?: number;
+    contentType?: string;
+    /** Parsed JSON when the body is JSON, else the raw text. */
+    body: unknown;
+    query?: URLSearchParams;
+}
+/**
+ * An OpenAPI 3.0 / 3.1 document, used to check that real traffic matches it:
+ * the app's responses against the app's own spec, and the app's calls to a
+ * stubbed service (and the stub's canned replies) against that service's spec.
+ */
+export declare class OpenApiSpec {
+    #private;
+    readonly file: string;
+    private readonly doc;
+    private constructor();
+    /** `file` is read; `label` (default: `file`) is how messages refer to it. */
+    static load(file: string, label?: string): Promise<OpenApiSpec>;
+    find(method: string, path: string): Operation | undefined;
+    /** 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;
+    /** Every documented response as `METHOD /template key`, in document order. */
+    responseKeys(): string[];
+    checkResponse(method: string, path: string, res: Message): string[];
+    /**
+     * A response the real service could send to `method path`: the lowest
+     * documented 2xx, with its example if the spec has one, else a value built
+     * from its schema. Undefined when the operation isn't in the spec.
+     */
+    exampleResponse(method: string, path: string): {
+        status: number;
+        headers?: Record<string, string>;
+        body?: unknown;
+    } | undefined;
+    /** Problems with a request the app sent to `method path`. */
+    checkRequest(method: string, path: string, req: Message): string[];
+}
+/**
+ * Coverage report: which documented responses the scenarios produced.
+ * `hits` are `responseKey()` values collected from every worker.
+ */
+export declare function formatCoverage(spec: OpenApiSpec, hits: Set<string>): {
+    covered: number;
+    total: number;
+    percent: number;
+    text: string;
+};
+export {};