slicetest 0.2.0 → 0.3.0

package/dist/drivers/mysql.js

@@ -0,0 +1,270 @@
+import mysql from "mysql2/promise";
+/**
+ * Makes rows look like the Postgres driver's, so the same scenarios pass on
+ * both: BOOLEAN (`TINYINT(1)`) columns come back as booleans, BIGINT ids as
+ * numbers when they fit, DATETIME as UTC.
+ */
+const options = {
+    supportBigNumbers: true,
+    bigNumberStrings: false,
+    timezone: "Z",
+    multipleStatements: true,
+    typeCast(field, next) {
+        if (field.type === "TINY" && field.length === 1) {
+            const v = field.string();
+            return v === null ? null : v === "1";
+        }
+        return next();
+    },
+};
+async function connect(url) {
+    const conn = await mysql.createConnection({ uri: url, ...options });
+    // Without a listener, a dropped connection would crash the worker; the next query reports it instead.
+    conn.on("error", () => { });
+    return conn;
+}
+function rowsOf(result) {
+    return Array.isArray(result) ? result : [];
+}
+export class MysqlDriver {
+    conn;
+    #keys = new Map();
+    constructor(conn) {
+        this.conn = conn;
+    }
+    static async connect(url) {
+        return new MysqlDriver(await connect(url));
+    }
+    async query(sql, params = []) {
+        const [rows] = await this.conn.query(sql, params);
+        return rowsOf(rows);
+    }
+    async queryAll(sqls) {
+        if (sqls.length === 0)
+            return [];
+        // With multipleStatements, several SELECTs come back as one array of result sets.
+        const [results] = await this.conn.query(sqls.join(";\n"));
+        return sqls.length === 1 ? [rowsOf(results)] : results.map(rowsOf);
+    }
+    async exec(script) {
+        await this.conn.query(script);
+    }
+    ident(name) {
+        return name
+            .split(".")
+            .map((part) => this.column(part))
+            .join(".");
+    }
+    column(name) {
+        return `\`${name.replace(/`/g, "``")}\``;
+    }
+    param(_n) {
+        return "?";
+    }
+    inList(column, values, params) {
+        if (values.length === 0)
+            return "FALSE";
+        params.push(...values);
+        return `${this.ident(column)} IN (${values.map(() => "?").join(", ")})`;
+    }
+    /**
+     * Base tables in the configured schemas. In MySQL a schema is a database;
+     * `public` (the default) stands for the database the URL points at.
+     */
+    async listTables(schemas, keep) {
+        const [{ current }] = (await this.query("SELECT DATABASE() AS current"));
+        const names = schemas.map((s) => (s === "public" ? current : s));
+        const rows = await this.query(`SELECT t.TABLE_SCHEMA AS \`schema\`, t.TABLE_NAME AS name,
+              (SELECT GROUP_CONCAT(k.COLUMN_NAME ORDER BY k.ORDINAL_POSITION SEPARATOR '\\n')
+                 FROM information_schema.KEY_COLUMN_USAGE k
+                WHERE k.TABLE_SCHEMA = t.TABLE_SCHEMA AND k.TABLE_NAME = t.TABLE_NAME AND k.CONSTRAINT_NAME = 'PRIMARY') AS \`key\`
+         FROM information_schema.TABLES t
+        WHERE t.TABLE_TYPE = 'BASE TABLE' AND t.TABLE_SCHEMA IN (?)
+        ORDER BY 1, 2`, [names]);
+        return rows
+            .map((r) => ({
+            name: r.schema === current ? r.name : `${r.schema}.${r.name}`,
+            quoted: `${this.ident(r.schema)}.${this.ident(r.name)}`,
+            key: r.key ? r.key.split("\n") : [],
+            bare: r.name,
+        }))
+            .filter((t) => !keep.includes(t.bare) && !keep.includes(t.name))
+            .map(({ bare: _, ...t }) => t);
+    }
+    /**
+     * TRUNCATE also restarts AUTO_INCREMENT, but it is DDL and costs a few
+     * milliseconds per table, so only tables that have rows or a used counter are
+     * truncated. Foreign key checks are off for this session only.
+     */
+    async truncate(tables) {
+        if (tables.length === 0)
+            return;
+        const [, , counters, ...filled] = await this.queryAll([
+            // Otherwise information_schema serves AUTO_INCREMENT from a cache that can be a day old.
+            "SET SESSION information_schema_stats_expiry = 0",
+            "SELECT 1",
+            `SELECT CONCAT(TABLE_SCHEMA, '.', TABLE_NAME) AS t, AUTO_INCREMENT AS n FROM information_schema.TABLES WHERE AUTO_INCREMENT > 1`,
+            ...tables.map((t) => `SELECT 1 AS x FROM ${t.quoted} LIMIT 1`),
+        ]);
+        const used = new Set(counters.map((r) => this.ident(String(r.t))));
+        const dirty = tables.filter((t, i) => filled[i].length > 0 || used.has(t.quoted));
+        if (dirty.length === 0)
+            return;
+        await this.conn.query(`SET FOREIGN_KEY_CHECKS = 0; ${dirty.map((t) => `TRUNCATE TABLE ${t.quoted}`).join("; ")}; SET FOREIGN_KEY_CHECKS = 1`);
+    }
+    /** MySQL has no RETURNING: insert, then read the row back by its primary key. */
+    async insert(table, row) {
+        const cols = Object.keys(row);
+        const sql = cols.length === 0
+            ? `INSERT INTO ${this.ident(table)} () VALUES ()`
+            : `INSERT INTO ${this.ident(table)} (${cols.map((c) => this.column(c)).join(", ")}) VALUES (${cols.map(() => "?").join(", ")})`;
+        const [res] = (await this.conn.query(sql, Object.values(row)));
+        const key = await this.#primaryKey(table);
+        const where = {};
+        for (const k of key) {
+            if (k in row)
+                where[k] = row[k];
+            else if (key.length === 1 && res.insertId)
+                where[k] = res.insertId;
+            else
+                return [row];
+        }
+        if (key.length === 0)
+            return [row];
+        const conds = Object.keys(where).map((k) => `${this.column(k)} = ?`);
+        return this.query(`SELECT * FROM ${this.ident(table)} WHERE ${conds.join(" AND ")}`, Object.values(where));
+    }
+    async #primaryKey(table) {
+        let key = this.#keys.get(table);
+        if (!key) {
+            const [schema, name] = table.includes(".") ? table.split(".", 2) : [null, table];
+            const rows = await this.query(`SELECT COLUMN_NAME AS c FROM information_schema.KEY_COLUMN_USAGE
+          WHERE TABLE_SCHEMA = COALESCE(?, DATABASE()) AND TABLE_NAME = ? AND CONSTRAINT_NAME = 'PRIMARY'
+          ORDER BY ORDINAL_POSITION`, [schema, name]);
+            key = rows.map((r) => r.c);
+            this.#keys.set(table, key);
+        }
+        return key;
+    }
+    async close() {
+        await this.conn.end();
+    }
+}
+function withDatabase(url, database) {
+    const u = new URL(url);
+    u.pathname = `/${database}`;
+    return u.toString();
+}
+function quote(name) {
+    return `\`${name.replace(/`/g, "``")}\``;
+}
+class MysqlAdmin {
+    conn;
+    url;
+    constructor(conn, url) {
+        this.conn = conn;
+        this.url = url;
+    }
+    async databases(prefix) {
+        const [rows] = await this.conn.query("SELECT SCHEMA_NAME AS name FROM information_schema.SCHEMATA");
+        return rowsOf(rows)
+            .map((r) => String(r.name))
+            .filter((n) => n.startsWith(prefix));
+    }
+    async create(name) {
+        await this.conn.query(`CREATE DATABASE ${quote(name)}`);
+    }
+    /**
+     * MySQL has no template databases: recreate each table from `SHOW CREATE
+     * TABLE` (foreign keys included) and copy its rows, then views and triggers.
+     * Stored routines and events are not copied.
+     */
+    async clone(template, name) {
+        await this.create(name);
+        const target = await connect(withDatabase(this.url, name));
+        try {
+            await target.query("SET FOREIGN_KEY_CHECKS = 0");
+            const [tables] = await this.conn.query("SELECT TABLE_NAME AS name, TABLE_TYPE AS type FROM information_schema.TABLES WHERE TABLE_SCHEMA = ? ORDER BY TABLE_NAME", [template]);
+            const list = rowsOf(tables);
+            for (const t of list.filter((t) => t.type === "BASE TABLE")) {
+                const [[create]] = (await this.conn.query(`SHOW CREATE TABLE ${quote(template)}.${quote(t.name)}`));
+                await target.query(String(create["Create Table"]));
+                const [cols] = await this.conn.query("SELECT COLUMN_NAME AS c FROM information_schema.COLUMNS WHERE TABLE_SCHEMA = ? AND TABLE_NAME = ? AND EXTRA NOT LIKE '%GENERATED%' ORDER BY ORDINAL_POSITION", [template, t.name]);
+                const names = rowsOf(cols).map((c) => quote(String(c.c))).join(", ");
+                await target.query(`INSERT INTO ${quote(t.name)} (${names}) SELECT ${names} FROM ${quote(template)}.${quote(t.name)}`);
+            }
+            // Views may depend on each other; retry the ones that fail until no progress is made.
+            let views = list.filter((t) => t.type === "VIEW");
+            while (views.length > 0) {
+                const failed = [];
+                let lastError;
+                for (const v of views) {
+                    const [[create]] = (await this.conn.query(`SHOW CREATE VIEW ${quote(template)}.${quote(v.name)}`));
+                    const sql = String(create["Create View"]).split(`${quote(template)}.`).join("");
+                    await target.query(sql).catch((e) => {
+                        failed.push(v);
+                        lastError = e;
+                    });
+                }
+                if (failed.length === views.length)
+                    throw lastError;
+                views = failed;
+            }
+            const [triggers] = await this.conn.query(`SHOW TRIGGERS FROM ${quote(template)}`);
+            for (const trg of rowsOf(triggers)) {
+                const [[create]] = (await this.conn.query(`SHOW CREATE TRIGGER ${quote(template)}.${quote(String(trg.Trigger))}`));
+                await target.query(String(create["SQL Original Statement"]));
+            }
+        }
+        catch (e) {
+            await this.drop(name).catch(() => { });
+            throw e;
+        }
+        finally {
+            await target.end().catch(() => { });
+        }
+    }
+    /** DROP DATABASE waits for open transactions, so disconnect everyone using it first. */
+    async drop(name) {
+        const [rows] = await this.conn.query("SELECT ID AS id FROM information_schema.PROCESSLIST WHERE DB = ? AND ID <> CONNECTION_ID()", [name]);
+        for (const r of rowsOf(rows))
+            await this.conn.query(`KILL ${Number(r.id)}`).catch(() => { });
+        await this.conn.query(`DROP DATABASE IF EXISTS ${quote(name)}`);
+    }
+    async withLock(key, fn) {
+        const lock = key.slice(0, 64);
+        await this.conn.query("SELECT GET_LOCK(?, -1)", [lock]);
+        try {
+            return await fn();
+        }
+        finally {
+            await this.conn.query("SELECT RELEASE_LOCK(?)", [lock]);
+        }
+    }
+    urlFor(name) {
+        return withDatabase(this.url, name);
+    }
+    async close() {
+        await this.conn.end();
+    }
+}
+export const mysqlEngine = {
+    name: "mysql",
+    defaultImage: "mysql:8.4",
+    async startContainer(image, reuse) {
+        const { MySqlContainer } = await import("@testcontainers/mysql").catch(() => {
+            throw new Error("slicetest: starting a MySQL container needs the @testcontainers/mysql package: npm i -D @testcontainers/mysql (or set db.url)");
+        });
+        const definition = new MySqlContainer(image);
+        if (reuse)
+            definition.withReuse();
+        const container = await definition.start();
+        // Root, because slicetest creates and drops databases.
+        return { url: container.getConnectionUri(true), stop: () => container.stop() };
+    },
+    async admin(url) {
+        return new MysqlAdmin(await connect(url), url);
+    },
+    driver: (url) => MysqlDriver.connect(url),
+    atlasUrl: (url) => url,
+};

package/dist/gen.d.ts

@@ -0,0 +1,24 @@
+/** Where the last run's OpenAPI coverage is kept for `slicetest gen --uncovered`. */
+export declare function coverageCacheFile(root: string): string;
+export interface GenOptions {
+    /** The app's spec, relative to `root`. */
+    spec: string;
+    /** Directory for the scenario files, relative to `root`. Default `scenarios`. */
+    out?: string;
+    /** Only responses the last run didn't produce. */
+    uncovered?: boolean;
+    force?: boolean;
+}
+/**
+ * Scenario skeletons for the documented responses of an OpenAPI spec, one
+ * `<resource>.gen.scenario.yaml` per first path segment. A 2xx response gets a
+ * runnable scenario, with a request built from the spec and, when the path
+ * needs an id, a step that creates the resource first through the collection's
+ * POST. Other responses become skipped scenarios: a to-do list of the states
+ * the tests still have to arrange.
+ */
+export declare function gen(root: string, opts: GenOptions): Promise<{
+    written: string[];
+    skipped: string[];
+    count: number;
+}>;

package/dist/gen.js

@@ -0,0 +1,116 @@
+import { existsSync } from "node:fs";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { stringify } from "yaml";
+import { OpenApiSpec } from "./openapi.js";
+/** Where the last run's OpenAPI coverage is kept for `slicetest gen --uncovered`. */
+export function coverageCacheFile(root) {
+    return path.join(root, "node_modules", ".cache", "slicetest", "openapi-coverage.json");
+}
+/**
+ * Scenario skeletons for the documented responses of an OpenAPI spec, one
+ * `<resource>.gen.scenario.yaml` per first path segment. A 2xx response gets a
+ * runnable scenario, with a request built from the spec and, when the path
+ * needs an id, a step that creates the resource first through the collection's
+ * POST. Other responses become skipped scenarios: a to-do list of the states
+ * the tests still have to arrange.
+ */
+export async function gen(root, opts) {
+    const spec = await OpenApiSpec.load(path.resolve(root, opts.spec), opts.spec);
+    const ops = spec.operations();
+    let covered = new Set();
+    if (opts.uncovered) {
+        const cache = coverageCacheFile(root);
+        if (!existsSync(cache))
+            throw new Error("slicetest: no coverage from a previous run yet. Run the scenarios once (with `openapi` set), then `slicetest gen --uncovered`.");
+        covered = new Set(JSON.parse(await readFile(cache, "utf8")));
+    }
+    const files = new Map();
+    let count = 0;
+    for (const op of ops) {
+        for (const key of op.responses) {
+            if (covered.has(`${op.method} ${op.template} ${key}`))
+                continue;
+            const resource = op.template.split("/").find((s) => s && !s.startsWith("{")) ?? "root";
+            const list = files.get(resource) ?? [];
+            list.push(scenarioFor(op, key, ops));
+            files.set(resource, list);
+            count++;
+        }
+    }
+    const dir = path.resolve(root, opts.out ?? "scenarios");
+    const written = [];
+    const skipped = [];
+    for (const [resource, scenarios] of files) {
+        const file = path.join(dir, `${resource}.gen.scenario.yaml`);
+        const rel = path.relative(root, file);
+        if (existsSync(file) && !opts.force) {
+            skipped.push(rel);
+            continue;
+        }
+        const header = [
+            "# yaml-language-server: $schema=https://unpkg.com/slicetest/schema/scenario.schema.json",
+            `# Generated by \`slicetest gen\` from ${opts.spec}${opts.uncovered ? " (responses the last run didn't cover)" : ""}.`,
+            "# Requests are built from the spec's examples and schemas: adjust them to your data, then drop the `skip`s one by one.",
+            "",
+        ].join("\n");
+        await mkdir(dir, { recursive: true });
+        await writeFile(file, header + stringify({ scenarios }, { lineWidth: 0, aliasDuplicateObjects: false }));
+        written.push(rel);
+    }
+    return { written, skipped, count };
+}
+function scenarioFor(op, key, all) {
+    const steps = [];
+    let pathText = op.template;
+    const success = /^2/.test(key);
+    let unresolved = false;
+    for (const [name, sample] of Object.entries(op.pathParams)) {
+        const creator = success ? creatorFor(op, name, all) : undefined;
+        if (creator) {
+            steps.push(requestStep(creator.op, creator.op.template, { status: Number(creator.status) }, { [name]: `json.${creator.field}` }));
+            pathText = pathText.replace(`{${name}}`, `{{${name}}}`);
+        }
+        else {
+            pathText = pathText.replace(`{${name}}`, encodeURIComponent(String(sample ?? 1)));
+            unresolved = true;
+        }
+    }
+    const status = /^\d{3}$/.test(key) ? Number(key) : undefined;
+    // Two error responses need no arranging: a made-up id is not found, and an empty body is invalid.
+    const notFound = status === 404 && Object.keys(op.pathParams).length > 0;
+    const invalid = (status === 400 || status === 422) && isFilledObject(op.json);
+    steps.push(requestStep(invalid ? { ...op, json: {} } : op, pathText, { status }));
+    const name = `${op.method} ${op.template} → ${key}${op.summary ? ` (${op.summary})` : ""}`;
+    const runnable = success ? !unresolved : notFound || invalid;
+    return runnable ? { name, steps } : { name: `${name} — TODO: arrange the state that produces this`, skip: true, steps };
+}
+/**
+ * The POST on the collection above `template` whose success response carries
+ * the value for `param`: `{id}` in `/polls/{id}/votes` comes from `POST /polls`'s `id`.
+ */
+function creatorFor(op, param, all) {
+    const i = op.template.indexOf(`{${param}}`);
+    const collection = op.template.slice(0, i).replace(/\/$/, "");
+    const post = all.find((o) => o.method === "POST" && o.template === collection);
+    if (!post)
+        return undefined;
+    const field = [param, "id"].find((f) => post.createdFields.includes(f));
+    const status = post.responses.filter((k) => /^2\d\d$/.test(k)).sort()[0];
+    return field && status ? { op: post, field, status } : undefined;
+}
+function requestStep(op, pathText, expect, capture) {
+    const step = { request: `${op.method} ${pathText}` };
+    if (Object.keys(op.query).length)
+        step.query = Object.fromEntries(Object.entries(op.query).map(([k, v]) => [k, String(v)]));
+    if (op.json !== undefined)
+        step.json = op.json;
+    if (expect.status)
+        step.expect = { status: expect.status };
+    if (capture)
+        step.capture = capture;
+    return step;
+}
+function isFilledObject(v) {
+    return !!v && typeof v === "object" && !Array.isArray(v) && Object.keys(v).length > 0;
+}

package/dist/global-setup.js

@@ -1,18 +1,20 @@
 import { execFile } from "node:child_process";
 import { createHash, randomBytes } from "node:crypto";
-import { mkdtemp, readdir, readFile, rm, stat } from "node:fs/promises";
+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 { configureContainerRuntime } from "./container-runtime.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 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);
+    const engine = await engineFor(opts);
     let adminUrl;
     let stopContainer;
     if (opts.db.url) {
@@ -45,7 +47,10 @@ export default async function setup(project) {
     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 });
+    // 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) {
@@ -59,6 +64,8 @@ export default async function setup(project) {
             await stopContainer?.();
             if (coverageDir)
                 await reportCoverage(opts, coverageDir);
+            if (recordDir)
+                await saveRecordings(opts, recordDir);
         }
     };
 }
@@ -74,6 +81,9 @@ async function reportCoverage(opts, dir) {
             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) {
@@ -86,6 +96,23 @@ async function reportCoverage(opts, dir) {
         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;

package/dist/index.d.ts

@@ -1,8 +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, 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

@@ -16,3 +16,5 @@ export declare function init(root: string, { force }?: {
     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

@@ -1,7 +1,7 @@
 import { existsSync } from "node:fs";
 import { mkdir, readdir, readFile, writeFile } from "node:fs/promises";
 import path from "node:path";
-import { stringify } from "yaml";
+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 = [];
@@ -92,13 +92,22 @@ export async function detect(root) {
     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 ? { db: { migrate } } : {}),
+        ...(migrate || Object.keys(composeDb).length ? { db: { ...composeDb, ...(migrate ? { migrate } : {}) } } : {}),
+        ...(Object.keys(containers).length ? { containers } : {}),
         stubs: [],
         ...(openapi ? { openapi } : {}),
     };
@@ -132,3 +141,96 @@ export async function init(root, { force = false } = {}) {
     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

@@ -4,6 +4,18 @@ interface Operation {
     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;
@@ -40,6 +52,12 @@ export declare class OpenApiSpec {
         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[];
 }