slicetest 0.1.0 → 0.3.0

package/dist/global-setup.js

@@ -1,16 +1,20 @@
 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 { mkdir, mkdtemp, readdir, readFile, rm, stat, writeFile } 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 { coverageCacheFile } from "./gen.js";
+import { formatCoverage, OpenApiSpec } from "./openapi.js";
+import { mergeRecordings } from "./recording.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 = await engineFor(opts);
     let adminUrl;
     let stopContainer;
     if (opts.db.url) {
@@ -18,65 +22,190 @@ 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;
+    // Likewise for recordings made against real services, merged into the recordings files at the end.
+    const recording = Object.values(opts.recordings).some((r) => r.record);
+    const recordDir = recording ? await mkdtemp(path.join(os.tmpdir(), "slicetest-recordings-")) : undefined;
+    project.provide("slicetestDb", { adminUrl, template, prefix, coverageDir, recordDir });
     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);
+            if (recordDir)
+                await saveRecordings(opts, recordDir);
         }
     };
 }
-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);
+        // 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`);
+        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 });
+    }
+}
+async function saveRecordings(opts, dir) {
+    try {
+        const files = await readdir(dir);
+        for (const [name, r] of Object.entries(opts.recordings)) {
+            const added = [];
+            for (const f of files.filter((f) => f.startsWith(`${name}.`)).sort())
+                added.push(...JSON.parse(await readFile(path.join(dir, f), "utf8")));
+            if (added.length === 0)
+                continue;
+            await mergeRecordings(path.resolve(opts.root, r.file), r.upstream, added);
+            console.log(`slicetest: recorded ${added.length} call(s) to ${r.upstream} in ${r.file}`);
+        }
+    }
+    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,11 @@
 export { scenario } from "./scenario.js";
+export { mask } from "./trace.js";
+export type { Trace, MaskOptions } from "./trace.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 { Dependency } from "./containers.js";
+export type { SlicetestOptions, ContainerOptions } from "./config.js";
+export type {} from "./matchers.js";

package/dist/index.js

@@ -1 +1,2 @@
 export { scenario } from "./scenario.js";
+export { mask } from "./trace.js";

package/dist/init.d.ts

@@ -0,0 +1,20 @@
+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[];
+}>;
+/** `"6379:6379"`, `"127.0.0.1:5432:5432/tcp"`, `9000`, `{ target: 6379 }` → the port inside the container. */
+export declare function containerPort(spec: unknown): number | undefined;

package/dist/init.js

@@ -0,0 +1,236 @@
+import { existsSync } from "node:fs";
+import { mkdir, readdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { parse, 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.");
+    }
+    // --- docker compose: the database image and other dependencies ---
+    const { db: composeDb, containers, appEnv } = await fromCompose(root, notes);
+    Object.assign(env, appEnv);
+    const mysqlDeps = !!deps.mysql2 || !!deps.mysql || /\b(pymysql|mysqlclient|aiomysql)\b/.test(python) || /\bgem ['"]mysql2['"]/.test(gemfile);
+    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.");
+    }
+    // --- 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 || Object.keys(composeDb).length ? { db: { ...composeDb, ...(migrate ? { migrate } : {}) } } : {}),
+        ...(Object.keys(containers).length ? { containers } : {}),
+        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 };
+}
+const COMPOSE_FILES = ["compose.yaml", "compose.yml", "docker-compose.yml", "docker-compose.yaml"];
+/** Known images: the port they listen on, how to empty them, and the variable apps usually read. */
+const KNOWN = [
+    { match: /(^|\/)(redis|redis-stack|keydb)(:|$)/, port: 6379, reset: ["redis-cli", "FLUSHALL"], env: (n) => ["REDIS_URL", `redis://{{container.${n}}}`] },
+    { match: /(^|\/)valkey(:|$)/, port: 6379, reset: ["valkey-cli", "FLUSHALL"], env: (n) => ["REDIS_URL", `redis://{{container.${n}}}`] },
+    { match: /(^|\/)memcached(:|$)/, port: 11211 },
+    {
+        match: /(^|\/)mongo(:|$)/,
+        port: 27017,
+        reset: ["mongosh", "--quiet", "--eval", "db.getMongo().getDBNames().filter((n) => !['admin', 'config', 'local'].includes(n)).forEach((n) => db.getSiblingDB(n).dropDatabase())"],
+        env: (n) => ["MONGODB_URL", `mongodb://{{container.${n}}}`],
+    },
+    { match: /(^|\/)(elasticsearch|opensearch)(:|$)/, port: 9200, env: (n) => ["ELASTICSEARCH_URL", `http://{{container.${n}}}`] },
+    { match: /(^|\/)minio(:|$)/, port: 9000, env: (n) => ["S3_ENDPOINT", `http://{{container.${n}}}`] },
+    { match: /(^|\/)rabbitmq(:|$)/, port: 5672, env: (n) => ["AMQP_URL", `amqp://guest:guest@{{container.${n}}}`] },
+];
+/**
+ * Reads docker compose: a postgres / mysql service sets the database engine
+ * and image; Redis, Mongo, MinIO and other images become `containers`.
+ */
+async function fromCompose(root, notes) {
+    const db = {};
+    const containers = {};
+    const appEnv = {};
+    const file = COMPOSE_FILES.find((f) => existsSync(path.join(root, f)));
+    if (!file)
+        return { db, containers, appEnv };
+    let doc;
+    try {
+        doc = (parse(await readFile(path.join(root, file), "utf8")) ?? {});
+    }
+    catch (e) {
+        notes.push(`${file}: couldn't parse it (${e.message}); skipped`);
+        return { db, containers, appEnv };
+    }
+    for (const [name, svc] of Object.entries(doc.services ?? {})) {
+        const image = typeof svc?.image === "string" ? svc.image : undefined;
+        if (!image) {
+            if (svc?.build)
+                notes.push(`${file}: service "${name}" is built from source; if it's the app, app.command replaces it`);
+            continue;
+        }
+        if (/(^|\/)(postgres|postgis)(:|$)/.test(image) || /(^|\/)postgis\//.test(image)) {
+            db.image = image;
+            notes.push(`db: Postgres image ${image} (${file} service "${name}")`);
+            continue;
+        }
+        if (/(^|\/)(mysql|mariadb)(:|$)/.test(image)) {
+            db.engine = "mysql";
+            db.image = image;
+            notes.push(`db: MySQL image ${image} (${file} service "${name}"). Install mysql2 and @testcontainers/mysql next to slicetest.`);
+            continue;
+        }
+        const known = KNOWN.find((k) => k.match.test(image));
+        const port = known?.port ?? containerPort(svc.ports?.[0] ?? svc.expose?.[0]);
+        if (!port) {
+            notes.push(`${file}: service "${name}" (${image}) exposes no port; skipped`);
+            continue;
+        }
+        const environment = envOf(svc.environment);
+        const command = Array.isArray(svc.command) ? svc.command.map(String) : typeof svc.command === "string" ? svc.command.split(/\s+/).filter(Boolean) : undefined;
+        containers[name] = {
+            image,
+            port,
+            ...(Object.keys(environment).length ? { env: environment } : {}),
+            ...(command?.length ? { command } : {}),
+            ...(known?.reset ? { reset: known.reset } : {}),
+        };
+        const [key, value] = known?.env?.(name) ?? [];
+        if (key && value)
+            appEnv[key] = value;
+        notes.push(`containers.${name}: ${image} (${file})${key ? `, passed to the app as ${key}` : `, at {{container.${name}}}`}${known?.reset ? "" : ". Add `reset` to empty it between scenarios"}`);
+    }
+    return { db, containers, appEnv };
+}
+/** `"6379:6379"`, `"127.0.0.1:5432:5432/tcp"`, `9000`, `{ target: 6379 }` → the port inside the container. */
+export function containerPort(spec) {
+    if (spec && typeof spec === "object" && "target" in spec)
+        return Number(spec.target) || undefined;
+    if (typeof spec !== "string" && typeof spec !== "number")
+        return undefined;
+    const last = String(spec).split("/")[0].split(":").at(-1);
+    const n = Number(last.split("-")[0]);
+    return Number.isInteger(n) && n > 0 ? n : undefined;
+}
+function envOf(environment) {
+    if (Array.isArray(environment)) {
+        return Object.fromEntries(environment.map(String).filter((e) => e.includes("=")).map((e) => [e.slice(0, e.indexOf("=")), e.slice(e.indexOf("=") + 1)]));
+    }
+    if (environment && typeof environment === "object")
+        return Object.fromEntries(Object.entries(environment).map(([k, v]) => [k, String(v ?? "")]));
+    return {};
+}

package/dist/openapi.d.ts

@@ -0,0 +1,74 @@
+interface Operation {
+    /** `paths` key, e.g. `/polls/{id}`. */
+    template: string;
+    method: string;
+    op: Record<string, any>;
+}
+export interface OperationSketch {
+    method: string;
+    template: string;
+    summary?: string;
+    pathParams: Record<string, unknown>;
+    query: Record<string, unknown>;
+    json?: unknown;
+    /** Documented response keys, e.g. `201`, `4XX`, `default`. */
+    responses: string[];
+    /** Top-level properties of the first 2xx JSON response. */
+    createdFields: string[];
+}
+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;
+    /**
+     * Every operation with what it takes to call it: sample values for its
+     * required path and query parameters and for its JSON request body, and the
+     * properties of its first 2xx JSON response. Used by `slicetest gen`.
+     */
+    operations(): OperationSketch[];
+    /** 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 {};