slicetest 0.3.0 → 0.5.0

package/dist/cli.js

@@ -13,11 +13,17 @@ const CONFIG_NAMES = ["slicetest.config.yaml", "slicetest.config.yml", "slicetes
 const HELP = `Usage: slicetest [filters...] [options]
        slicetest init [--force]
        slicetest gen [--spec <file>] [--out <dir>] [--uncovered] [--force]
+       slicetest doctor [--config <file>]
+       slicetest record [--out <file>] [--port <n>]
 
 Runs *.scenario.yaml files against your app, as configured in slicetest.config.yaml.
 \`slicetest init\` looks at the project and writes a starting config and scenario.
 \`slicetest gen\` writes scenario skeletons for the documented responses of the
 app's OpenAPI spec; with --uncovered, only for those the last run didn't produce.
+\`slicetest doctor\` checks the config, the container runtime or database server,
+migrations, commands and spec files, and says what to fix.
+\`slicetest record\` starts everything and a proxy in front of the app: use the app
+through it (a browser, curl), press Enter, and get the session as a YAML scenario.
 
 Options:
   -c, --config <file>  Config file (default: ${CONFIG_NAMES.join(" / ")} in the current directory)
@@ -25,16 +31,20 @@ Options:
   -t, --name <pattern> Only run scenarios whose name matches
       --spec <file>    gen: OpenAPI file (default: \`openapi\` from the config)
       --out <dir>      gen: where to write scenarios (default: scenarios)
+                       record: the scenario file (default: scenarios/recorded-<time>.scenario.yaml)
+      --port <n>       record: the proxy's port (default: any free port)
       --uncovered      gen: only responses the last run didn't cover
       --force          init, gen: overwrite existing files
   -h, --help           Show this help
 
 Config (paths are relative to the config file):
   app:      { command, env, cwd, ready: { path } | { log }, readyTimeout }
-  db:       { migrate: { atlas: { dir } } | { sql } | { command, inputs }, engine, seed, url, image, schemas, keep, reuse }
+  db:       { migrate: { atlas: { dir } } | { sql } | { command, inputs }, engine, seed, url, image, schemas, keep, reuse, queries }
   stubs:    [name | { name, openapi, autoReply, upstream, recordings }]
   services: { name: { command, env, cwd, ready } }
   containers: { name: { image, port, env, command, ready: { log }, reset } }
+  mail:     true    SMTP server at {{mail.host}} / {{mail.port}}
+  auth:     true | { audience, claims }   OpenID issuer at {{auth.issuer}} / {{auth.jwks}}
   openapi:  file | { spec, minCoverage }
   http:     { headers, query }
   include:  [globs]  default ["**/*.scenario.{yaml,yml}"]
@@ -52,6 +62,7 @@ export async function main(argv = process.argv.slice(2)) {
             spec: { type: "string" },
             out: { type: "string" },
             uncovered: { type: "boolean" },
+            port: { type: "string" },
         },
     });
     if (values.help) {
@@ -67,18 +78,30 @@ export async function main(argv = process.argv.slice(2)) {
     const configPath = values.config
         ? path.resolve(values.config)
         : CONFIG_NAMES.map((n) => path.resolve(n)).find((p) => existsSync(p));
+    if (positionals[0] === "doctor") {
+        const { doctor, formatChecks } = await import("./doctor.js");
+        const checks = await doctor(configPath);
+        process.stdout.write(formatChecks(checks));
+        if (checks.some((c) => c.status === "fail"))
+            process.exitCode = 1;
+        return;
+    }
     if (positionals[0] === "gen") {
-        const configOpenapi = configPath && existsSync(configPath) ? (parse(await readFile(configPath, "utf8")) ?? {}).openapi : undefined;
+        const config = configPath && existsSync(configPath) ? (parse(await readFile(configPath, "utf8")) ?? {}) : undefined;
+        const configOpenapi = config?.openapi;
         const spec = values.spec ?? (typeof configOpenapi === "object" ? configOpenapi.spec : configOpenapi);
         if (!spec)
             throw new Error("slicetest gen: no OpenAPI spec. Pass --spec openapi.yaml, or set `openapi` in the config.");
         const root = values.spec || !configPath ? process.cwd() : path.dirname(configPath);
         const { gen } = await import("./gen.js");
-        const { written, skipped, count } = await gen(root, { spec, out: values.out, uncovered: values.uncovered, force: values.force });
+        const { written, skipped, count, needsAuth } = await gen(root, { spec, out: values.out, uncovered: values.uncovered, force: values.force });
         const lines = [
             count === 0 ? "Every documented response is already covered; nothing to generate." : `${count} scenario(s) for the responses in ${spec}.`,
             ...written.map((f) => `  wrote   ${f}`),
             ...skipped.map((f) => `  skipped ${f} (exists; --force to overwrite)`),
+            ...(needsAuth && count > 0 && !config?.auth
+                ? ["", "The spec requires bearer tokens: requests carry `auth:`. Add `auth: true` to the config and point the app's JWT settings at {{auth.issuer}} / {{auth.jwks}}."]
+                : []),
         ];
         process.stdout.write(`${lines.join("\n")}\n`);
         return;
@@ -89,6 +112,11 @@ export async function main(argv = process.argv.slice(2)) {
         return;
     }
     const { include, ...options } = (parse(await readFile(configPath, "utf8")) ?? {});
+    if (positionals[0] === "record") {
+        const { record } = await import("./record-cli.js");
+        await record(configPath, options, { out: values.out, port: values.port ? Number(values.port) : 0 });
+        return;
+    }
     const { startVitest } = await import("vitest/node");
     const { slicetest, YAML_SCENARIOS } = await import("./vitest.js");
     const vitest = await startVitest(positionals, {

package/dist/config.d.ts

@@ -1,3 +1,4 @@
+import type { AuthOptions } from "./auth.js";
 import type { RequestOptions } from "./http.js";
 export interface SlicetestOptions {
     app: AppOptions;
@@ -37,6 +38,18 @@ export interface SlicetestOptions {
      * `{{container.<name>.port}}`. `reset` runs inside it before every scenario.
      */
     containers?: Record<string, ContainerOptions>;
+    /**
+     * Catch the mail the app sends. An SMTP server (no TLS, any credentials)
+     * listens at `{{mail.host}}` / `{{mail.port}}` (`{{mail.url}}` is `smtp://host:port`);
+     * scenarios read what arrived with `mail.messages()` / `mail.waitFor()`.
+     */
+    mail?: boolean;
+    /**
+     * An OpenID Connect issuer for apps that verify JWTs. The app gets
+     * `{{auth.issuer}}`, `{{auth.jwks}}` and `{{auth.audience}}`; scenarios mint
+     * tokens with `auth.token({ sub, roles })`. `true`, or `{ audience, claims }`.
+     */
+    auth?: boolean | AuthOptions;
 }
 export interface ContainerOptions {
     image: string;
@@ -102,10 +115,12 @@ export interface AppOptions {
 }
 export interface DbOptions {
     /**
-     * `postgres` (default) or `mysql`. Inferred from `url` when it starts with `mysql://`.
+     * `postgres` (default), `mysql` or `sqlite`. Inferred from `url` when it starts with `mysql://`.
      * MySQL needs the `mysql2` package, and `@testcontainers/mysql` unless `url` is given.
+     * SQLite needs Node.js 22.5+ and nothing else: no server, no container. The app gets
+     * `{{db.url}}` as `sqlite:///path/to/file.db` and `{{db.path}}` as the file path.
      */
-    engine?: "postgres" | "mysql";
+    engine?: "postgres" | "mysql" | "sqlite";
     /** Image used when no `url` is given. Default `postgres:17-alpine`, or `mysql:8.4` for MySQL. */
     image?: string;
     /**
@@ -127,6 +142,12 @@ export interface DbOptions {
      * Default: on, except when `CI` is set or `url` is given.
      */
     reuse?: boolean;
+    /**
+     * Record the SQL the app runs: `{{db.url}}` points the app at a proxy that
+     * reads the wire protocol (Postgres and MySQL), so `db.queries()` lists every
+     * statement, whatever the app's language or driver. Off by default.
+     */
+    queries?: boolean;
 }
 export type MigrateOptions = {
     atlas: {
@@ -151,6 +172,8 @@ export interface ResolvedOptions {
     };
     services: Record<string, ResolvedProcess>;
     containers: Record<string, ContainerOptions>;
+    mail: boolean;
+    auth: AuthOptions | false;
     db: Required<Pick<DbOptions, "engine" | "image" | "schemas" | "keep" | "reuse">> & Omit<DbOptions, "engine" | "image" | "schemas" | "keep" | "reuse">;
     stubs: string[];
     /** Spec files, resolved against the root: the app's, and per stub name. */

package/dist/config.js

@@ -5,6 +5,8 @@ export function resolveOptions(opts, root) {
         app: { ...opts.app, ready: resolveReady(opts.app.ready ?? { path: "/" }) },
         services: Object.fromEntries(Object.entries(opts.services ?? {}).map(([name, s]) => [name, { ...s, ready: s.ready && resolveReady(s.ready) }])),
         containers: opts.containers ?? {},
+        mail: opts.mail ?? false,
+        auth: opts.auth === true ? {} : (opts.auth ?? false),
         db: resolveDb(opts.db ?? {}),
         stubs: (opts.stubs ?? []).map(stubName),
         openapi: {
@@ -39,9 +41,9 @@ function resolveDb(db) {
     const env = process.env.SLICETEST_DATABASE_URL || undefined;
     const engine = db.engine ?? (isMysql(db.url ?? env ?? "") ? "mysql" : "postgres");
     // The environment variable names one server for the whole CI job; a project on the other engine starts its own.
-    const url = db.url ?? (env && isMysql(env) === (engine === "mysql") ? env : undefined);
+    const url = engine === "sqlite" ? undefined : (db.url ?? (env && isMysql(env) === (engine === "mysql") ? env : undefined));
     return {
-        image: engine === "mysql" ? "mysql:8.4" : "postgres:17-alpine",
+        image: engine === "mysql" ? "mysql:8.4" : engine === "sqlite" ? "" : "postgres:17-alpine",
         schemas: ["public"],
         keep: [],
         ...db,
@@ -84,9 +86,28 @@ function validate(opts) {
                 fail(`containers.${name}.${key} must be a list of strings, e.g. ["redis-cli", "FLUSHALL"]`);
         }
     }
+    if (opts.mail !== undefined && typeof opts.mail !== "boolean")
+        fail(`mail must be true or false, got ${JSON.stringify(opts.mail)}`);
+    if (opts.auth !== undefined && typeof opts.auth !== "boolean") {
+        if (!opts.auth || typeof opts.auth !== "object" || Array.isArray(opts.auth))
+            fail(`auth must be true or { audience, claims }, got ${JSON.stringify(opts.auth)}`);
+        for (const key of Object.keys(opts.auth))
+            if (key !== "audience" && key !== "claims")
+                fail(`unknown key auth.${key} (expected audience, claims)`);
+        if (opts.auth.audience !== undefined && typeof opts.auth.audience !== "string")
+            fail("auth.audience must be a string");
+        if (opts.auth.claims !== undefined && (!opts.auth.claims || typeof opts.auth.claims !== "object" || Array.isArray(opts.auth.claims)))
+            fail("auth.claims must be a mapping of claim names to values");
+    }
     const engine = opts.db?.engine;
-    if (engine !== undefined && engine !== "postgres" && engine !== "mysql")
-        fail(`db.engine must be "postgres" or "mysql", got ${JSON.stringify(engine)}`);
+    if (engine !== undefined && engine !== "postgres" && engine !== "mysql" && engine !== "sqlite")
+        fail(`db.engine must be "postgres", "mysql" or "sqlite", got ${JSON.stringify(engine)}`);
+    if (opts.db?.queries !== undefined && typeof opts.db.queries !== "boolean")
+        fail(`db.queries must be true or false, got ${JSON.stringify(opts.db.queries)}`);
+    if (engine === "sqlite" && opts.db?.queries)
+        fail("db.queries needs a database server (postgres or mysql): an SQLite app opens the file directly, so there is no connection to read");
+    if (engine === "sqlite" && opts.db?.url)
+        fail("db.url doesn't apply to sqlite: slicetest creates the database files itself and passes them to the app as {{db.url}} / {{db.path}}");
     const migrate = opts.db?.migrate;
     if (migrate) {
         const keys = Object.keys(migrate).filter((k) => ["atlas", "sql", "command"].includes(k));

package/dist/db.d.ts

@@ -1,4 +1,5 @@
 import type { Driver, Row } from "./drivers/driver.js";
+import type { QueryList, QueryLog } from "./query-log.js";
 export type { Row } from "./drivers/driver.js";
 /**
  * Column filters. `null` means IS NULL and an array means IN (...);
@@ -48,6 +49,31 @@ export declare class Db {
     count(table: string, where?: Where): Promise<number>;
     /** Insert rows and return them as stored (with defaults and generated ids). */
     insert<T extends Row = Row>(table: string, rows: Row | Row[]): Promise<T[]>;
+    /**
+     * Insert a row that satisfies the schema, giving only the columns the test cares about.
+     * Required columns get a value of their type (enums and `CHECK (... IN (...))` their first
+     * allowed value) and required foreign keys a parent row made the same way.
+     *
+     * ```ts
+     * const order = await db.make("orders", { status: "paid" }); // also creates the customer it needs
+     * ```
+     */
+    make<T extends Row = Row>(table: string, overrides?: Row): Promise<T>;
+    /** `count` rows made like `make()`; `overrides` may depend on the index. */
+    makeMany<T extends Row = Row>(table: string, count: number, overrides?: Row | ((i: number) => Row)): Promise<T[]>;
+    /** @internal Set by the runtime when `db.queries` is on. */
+    attachQueryLog(log: QueryLog): void;
+    /**
+     * SQL the app ran during this scenario, or only while `fn` ran. Needs `db: { queries: true }`.
+     * The test's own `db` calls aren't included.
+     *
+     * ```ts
+     * const queries = await db.queries(() => http.get("/posts"));
+     * expect(queries.repeated()).toEqual([]);   // no statement shape ran 3+ times: no N+1
+     * expect(queries.length).toBeLessThanOrEqual(3);
+     * ```
+     */
+    queries(fn?: () => unknown): Promise<QueryList>;
     /** Empty every data table without dropping the app's connections, then re-apply the seed. */
     reset(): Promise<void>;
     /**

package/dist/db.js

@@ -1,4 +1,5 @@
 import { readFile } from "node:fs/promises";
+import { Factory } from "./factory.js";
 /** Tables that record applied migrations. Truncating them would make tools re-run migrations. */
 const MIGRATION_TABLES = [
     "atlas_schema_revisions",
@@ -29,10 +30,13 @@ export class Db {
     /** Contents right after the reset (and seed); undefined means every table was empty. */
     #start;
     #checkpoint;
+    #factory;
+    #queryLog;
     constructor(driver, url, opts) {
         this.url = url;
         this.opts = opts;
         this.#driver = driver;
+        this.#factory = new Factory((table) => driver.describe(table), (table, row) => driver.insert(table, row));
     }
     static async connect(driver, url, opts) {
         const db = new Db(driver, url, opts);
@@ -80,10 +84,56 @@ export class Db {
             out.push(...(await this.#driver.insert(table, row)));
         return out;
     }
+    /**
+     * Insert a row that satisfies the schema, giving only the columns the test cares about.
+     * Required columns get a value of their type (enums and `CHECK (... IN (...))` their first
+     * allowed value) and required foreign keys a parent row made the same way.
+     *
+     * ```ts
+     * const order = await db.make("orders", { status: "paid" }); // also creates the customer it needs
+     * ```
+     */
+    async make(table, overrides = {}) {
+        return (await this.#factory.make(table, overrides));
+    }
+    /** `count` rows made like `make()`; `overrides` may depend on the index. */
+    async makeMany(table, count, overrides = {}) {
+        const out = [];
+        for (let i = 0; i < count; i++)
+            out.push(await this.make(table, typeof overrides === "function" ? overrides(i) : overrides));
+        return out;
+    }
+    /** @internal Set by the runtime when `db.queries` is on. */
+    attachQueryLog(log) {
+        this.#queryLog = log;
+    }
+    /**
+     * SQL the app ran during this scenario, or only while `fn` ran. Needs `db: { queries: true }`.
+     * The test's own `db` calls aren't included.
+     *
+     * ```ts
+     * const queries = await db.queries(() => http.get("/posts"));
+     * expect(queries.repeated()).toEqual([]);   // no statement shape ran 3+ times: no N+1
+     * expect(queries.length).toBeLessThanOrEqual(3);
+     * ```
+     */
+    async queries(fn) {
+        const log = this.#queryLog;
+        if (!log)
+            throw new Error("slicetest: db.queries() needs `db: { queries: true }` in the config (Postgres or MySQL); the app then connects through a proxy that records its SQL.");
+        if (!fn)
+            return log.queries();
+        const mark = log.mark();
+        await fn();
+        // Let statements already on the wire arrive.
+        await new Promise((r) => setTimeout(r, 10));
+        return log.queries(mark);
+    }
     /** Empty every data table without dropping the app's connections, then re-apply the seed. */
     async reset() {
         this.#tables ??= await this.#listTables();
         await this.#driver.truncate(this.#tables);
+        this.#factory.reset();
         this.#start = undefined;
         this.#checkpoint = undefined;
         if (this.#seed) {

package/dist/doctor.d.ts

@@ -0,0 +1,22 @@
+import { type ResolvedOptions } from "./config.js";
+/**
+ * `slicetest doctor`: everything a run needs, checked up front, each problem
+ * with what to do about it. Meant for a first setup and for CI logs, where a
+ * container runtime that isn't there otherwise shows up as a timeout.
+ */
+export interface Check {
+    status: "ok" | "warn" | "fail";
+    label: string;
+    /** What was found, or what to do. */
+    detail?: string;
+}
+/** Things that touch the machine, replaceable in tests. */
+export interface Probes {
+    containerRuntime(): Promise<string>;
+    database(opts: ResolvedOptions, url: string): Promise<void>;
+    command(name: string, args: string[]): Promise<string>;
+    resolvePackage(name: string, from: string): boolean;
+}
+export declare const machine: Probes;
+export declare function doctor(configPath: string | undefined, probes?: Probes, env?: NodeJS.ProcessEnv): Promise<Check[]>;
+export declare function formatChecks(checks: Check[]): string;

package/dist/doctor.js

@@ -0,0 +1,190 @@
+import { execFile } from "node:child_process";
+import { existsSync } from "node:fs";
+import { readFile, stat } from "node:fs/promises";
+import { createRequire } from "node:module";
+import path from "node:path";
+import { promisify } from "node:util";
+import { parse } from "yaml";
+import { resolveOptions } from "./config.js";
+import { configureContainerRuntime } from "./container-runtime.js";
+import { engineFor } from "./drivers/index.js";
+import { OpenApiSpec } from "./openapi.js";
+const exec = promisify(execFile);
+export const machine = {
+    async containerRuntime() {
+        configureContainerRuntime();
+        const { getContainerRuntimeClient } = await import("testcontainers");
+        const client = await withTimeout(getContainerRuntimeClient(), 15_000, "no answer from the container runtime");
+        const { containerRuntime: rt } = client.info;
+        return `${rt.operatingSystem} ${rt.serverVersion} at ${rt.host}`;
+    },
+    async database(opts, url) {
+        const admin = await withTimeout((await engineFor(opts)).admin(url), 10_000, "connection timed out");
+        await admin.close();
+    },
+    async command(name, args) {
+        const { stdout, stderr } = await exec(name, args, { windowsHide: true, timeout: 10_000, shell: process.platform === "win32" });
+        return (stdout || stderr).trim().split(/\r?\n/)[0];
+    },
+    resolvePackage(name, from) {
+        try {
+            createRequire(path.join(from, "noop.js")).resolve(`${name}/package.json`);
+            return true;
+        }
+        catch {
+            try {
+                createRequire(import.meta.url).resolve(name);
+                return true;
+            }
+            catch {
+                return false;
+            }
+        }
+    },
+};
+export async function doctor(configPath, probes = machine, env = process.env) {
+    const checks = [];
+    const add = (status, label, detail) => checks.push({ status, label, ...(detail ? { detail } : {}) });
+    const major = Number(process.versions.node.split(".")[0]);
+    add(major >= 20 ? "ok" : "fail", `Node.js ${process.versions.node}`, major >= 20 ? undefined : "slicetest needs Node.js 20 or later");
+    if (!configPath || !existsSync(configPath)) {
+        add("warn", "no slicetest.config.yaml", "checked the machine only. `npx slicetest init` writes a config; with the Vitest plugin, pass the same options to --config as YAML to check them");
+        await checkContainerRuntime(add, probes);
+        return checks;
+    }
+    const root = path.dirname(configPath);
+    const rel = (p) => path.relative(process.cwd(), path.resolve(root, p)) || ".";
+    let opts;
+    try {
+        const raw = (parse(await readFile(configPath, "utf8")) ?? {});
+        delete raw.include;
+        opts = resolveOptions(raw, root);
+        add("ok", `config ${rel(configPath)}`);
+    }
+    catch (e) {
+        add("fail", `config ${rel(configPath)}`, e.message.replace(/^slicetest: /, ""));
+        return checks;
+    }
+    // Database: a server that's there already, or a container runtime to start one in.
+    const url = opts.db.engine === "sqlite" ? undefined : (opts.db.url ?? env.SLICETEST_DATABASE_URL);
+    if (opts.db.engine === "sqlite") {
+        const [maj = 0, min = 0] = process.versions.node.split(".").map(Number);
+        if (maj > 22 || (maj === 22 && min >= 5))
+            add("ok", "sqlite (node:sqlite, no server needed)");
+        else
+            add("fail", "sqlite needs Node.js 22.5 or later", `this is ${process.versions.node}; slicetest uses the built-in node:sqlite`);
+        if (Object.keys(opts.containers).length)
+            await checkContainerRuntime(add, probes, `runs ${Object.values(opts.containers).map((c) => c.image).join(", ")}`);
+    }
+    else if (url) {
+        try {
+            await probes.database(opts, url);
+            add("ok", `${opts.db.engine} at ${redact(url)}`);
+        }
+        catch (e) {
+            add("fail", `${opts.db.engine} at ${redact(url)}`, `can't connect: ${e.message}. It must be a superuser (root) connection that can create databases`);
+        }
+    }
+    else {
+        await checkContainerRuntime(add, probes, `runs ${[opts.db.image, ...Object.values(opts.containers).map((c) => c.image)].join(", ")}`);
+    }
+    if (opts.db.engine === "mysql") {
+        for (const pkg of ["mysql2", ...(url ? [] : ["@testcontainers/mysql"])]) {
+            if (probes.resolvePackage(pkg, root))
+                add("ok", `${pkg} installed`);
+            else
+                add("fail", `${pkg} not installed`, `db.engine "mysql" needs it: npm i -D ${pkg}`);
+        }
+    }
+    const m = opts.db.migrate;
+    if (!m)
+        add("warn", "db.migrate not set", "scenarios run against an empty database unless the app creates its own tables");
+    else if ("atlas" in m) {
+        await checkPath(add, "migrations", m.atlas.dir.replace(/^file:\/\//, ""), root, rel);
+        try {
+            add("ok", `atlas CLI (${await probes.command("atlas", ["version"])})`);
+        }
+        catch {
+            add("fail", "atlas CLI not found", "db.migrate.atlas runs `atlas migrate apply`. Install it: https://atlasgo.io/getting-started");
+        }
+    }
+    else if ("sql" in m)
+        await checkPath(add, "migrations", m.sql, root, rel);
+    else
+        for (const input of m.inputs ?? [])
+            await checkPath(add, "migration input", input, root, rel);
+    if (opts.db.seed)
+        await checkPath(add, "seed", opts.db.seed, root, rel);
+    for (const [label, p] of [["app", opts.app], ...Object.entries(opts.services).map(([n, s]) => [`service ${n}`, s])]) {
+        if (p.cwd)
+            await checkPath(add, `${label} cwd`, p.cwd, root, rel);
+        const program = firstWord(p.command);
+        if (program && !/^[.\\/]|\{\{|\$/.test(program)) {
+            if (await onPath(program, env))
+                add("ok", `${label}: ${program} found`);
+            else
+                add("warn", `${label}: ${program} not found on PATH`, `\`${p.command}\` may fail to start. Fine if a shell alias or a relative script provides it`);
+        }
+    }
+    const specs = [...(opts.openapi.app ? [["app OpenAPI", opts.openapi.app]] : []), ...Object.entries(opts.openapi.stubs).map(([n, f]) => [`stub ${n} OpenAPI`, f])];
+    for (const [label, file] of specs) {
+        try {
+            const spec = await OpenApiSpec.load(path.resolve(root, file), file);
+            add("ok", `${label} ${rel(file)}`, `${spec.operations().length} operation(s)`);
+        }
+        catch (e) {
+            add("fail", `${label} ${rel(file)}`, e.message.replace(/^slicetest: /, ""));
+        }
+    }
+    for (const [name, r] of Object.entries(opts.recordings)) {
+        if (existsSync(r.file))
+            add("ok", `stub ${name}: recordings ${rel(r.file)}`);
+        else
+            add("warn", `stub ${name}: no recordings yet (${rel(r.file)})`, `run once with SLICETEST_RECORD=${name} to record ${r.upstream}`);
+    }
+    return checks;
+}
+async function checkContainerRuntime(add, probes, forWhat) {
+    try {
+        add("ok", `container runtime: ${await probes.containerRuntime()}`, forWhat);
+    }
+    catch (e) {
+        add("fail", "no container runtime", `${e.message.split("\n")[0]}. Start Docker or a Podman machine (\`podman machine start\`), or set SLICETEST_DATABASE_URL / db.url to an existing database server`);
+    }
+}
+async function checkPath(add, label, p, root, rel) {
+    try {
+        await stat(path.resolve(root, p));
+        add("ok", `${label} ${rel(p)}`);
+    }
+    catch {
+        add("fail", `${label} ${rel(p)} not found`, `paths in the config are relative to the config file's directory (${rel(".")})`);
+    }
+}
+function firstWord(command) {
+    return /^\s*(?:"([^"]+)"|(\S+))/.exec(command)?.slice(1).find(Boolean);
+}
+async function onPath(program, env) {
+    const exts = process.platform === "win32" ? (env.PATHEXT ?? ".EXE;.CMD;.BAT").split(";") : [""];
+    for (const dir of (env.PATH ?? env.Path ?? "").split(path.delimiter).filter(Boolean)) {
+        for (const ext of exts) {
+            if (existsSync(path.join(dir, program + ext)) || existsSync(path.join(dir, program)))
+                return true;
+        }
+    }
+    return false;
+}
+function redact(url) {
+    return url.replace(/\/\/([^:/@]+):[^@]*@/, "//$1:***@");
+}
+function withTimeout(p, ms, message) {
+    return Promise.race([p, new Promise((_, reject) => setTimeout(() => reject(new Error(message)), ms).unref())]);
+}
+export function formatChecks(checks) {
+    const icon = { ok: "✓", warn: "!", fail: "✗" };
+    const lines = checks.map((c) => `  ${icon[c.status]} ${c.label}${c.detail ? `\n      ${c.detail}` : ""}`);
+    const fails = checks.filter((c) => c.status === "fail").length;
+    const warns = checks.filter((c) => c.status === "warn").length;
+    const summary = fails ? `${fails} problem(s) to fix before running.` : warns ? `Ready to run, with ${warns} warning(s).` : "Ready to run.";
+    return `${lines.join("\n")}\n\n${summary}\n`;
+}

package/dist/drivers/driver.d.ts

@@ -13,6 +13,31 @@ export interface Table {
     /** Primary-key columns, in order; empty when there is none. */
     key: string[];
 }
+export interface Column {
+    name: string;
+    /** The declared type as the engine reports it, e.g. `character varying(20)`, `int`, `TEXT`. */
+    type: string;
+    nullable: boolean;
+    /** Has a default, is generated, an identity or auto-increment column: inserts may leave it out. */
+    hasDefault: boolean;
+    maxLength?: number;
+    /** Labels of an enum type. */
+    values?: string[];
+}
+export interface ForeignKey {
+    columns: string[];
+    /** Referenced table, named like `Table.name`. */
+    table: string;
+    /** Referenced columns; empty means the referenced table's primary key (SQLite). */
+    references: string[];
+}
+/** What `db.make()` needs to build a valid row. */
+export interface TableShape {
+    columns: Column[];
+    foreignKeys: ForeignKey[];
+    /** Bodies of CHECK constraints, as the engine prints them. */
+    checks: string[];
+}
 export interface Driver {
     query<T extends Row = Row>(sql: string, params?: unknown[]): Promise<T[]>;
     /** Several parameterless SELECTs in one round trip. */
@@ -33,6 +58,8 @@ export interface Driver {
     truncate(tables: Table[]): Promise<void>;
     /** Insert one row and return it as stored (defaults and generated ids filled in). */
     insert(table: string, row: Row): Promise<Row[]>;
+    /** Columns, foreign keys and checks of `table`. Throws when there is no such table. */
+    describe(table: string): Promise<TableShape>;
     close(): Promise<void>;
 }
 /** Server-level operations: the databases slicetest creates for templates and workers. */
@@ -54,6 +81,8 @@ export interface Engine {
     name: string;
     /** Container image used when no `db.url` is given. */
     defaultImage: string;
+    /** Runs in-process (SQLite): no container runtime needed. */
+    local?: boolean;
     startContainer(image: string, reuse: boolean): Promise<{
         url: string;
         stop(): Promise<unknown>;

package/dist/drivers/index.js

@@ -10,5 +10,7 @@ export async function engineFor(opts) {
         });
         return mod.mysqlEngine;
     }
+    if (opts.db.engine === "sqlite")
+        return (await import("./sqlite.js")).sqliteEngine;
     return postgres;
 }

package/dist/drivers/mysql.d.ts

@@ -1,4 +1,4 @@
-import type { Driver, Engine, Row, Table } from "./driver.js";
+import type { Driver, Engine, Row, Table, TableShape } from "./driver.js";
 export declare class MysqlDriver implements Driver {
     #private;
     private readonly conn;
@@ -24,6 +24,7 @@ export declare class MysqlDriver implements Driver {
     truncate(tables: Table[]): Promise<void>;
     /** MySQL has no RETURNING: insert, then read the row back by its primary key. */
     insert(table: string, row: Row): Promise<Row[]>;
+    describe(table: string): Promise<TableShape>;
     close(): Promise<void>;
 }
 export declare const mysqlEngine: Engine;

package/dist/drivers/mysql.js

@@ -134,6 +134,44 @@ export class MysqlDriver {
         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 describe(table) {
+        const [schema, name] = table.includes(".") ? table.split(".", 2) : [null, table];
+        const columns = await this.query(`SELECT COLUMN_NAME AS name, COLUMN_TYPE AS type, IS_NULLABLE AS nullable, COLUMN_DEFAULT AS dflt, EXTRA AS extra,
+              CHARACTER_MAXIMUM_LENGTH AS max
+         FROM information_schema.COLUMNS
+        WHERE TABLE_SCHEMA = COALESCE(?, DATABASE()) AND TABLE_NAME = ?
+        ORDER BY ORDINAL_POSITION`, [schema, name]);
+        if (columns.length === 0)
+            throw new Error(`slicetest: there is no table "${table}"`);
+        const keys = await this.query(`SELECT CONSTRAINT_NAME AS id, COLUMN_NAME AS \`column\`, REFERENCED_TABLE_SCHEMA AS \`schema\`,
+              REFERENCED_TABLE_NAME AS \`table\`, REFERENCED_COLUMN_NAME AS ref, DATABASE() AS current
+         FROM information_schema.KEY_COLUMN_USAGE
+        WHERE TABLE_SCHEMA = COALESCE(?, DATABASE()) AND TABLE_NAME = ? AND REFERENCED_TABLE_NAME IS NOT NULL
+        ORDER BY CONSTRAINT_NAME, ORDINAL_POSITION`, [schema, name]);
+        const foreignKeys = new Map();
+        for (const k of keys) {
+            const fk = foreignKeys.get(k.id) ?? { columns: [], table: k.schema === k.current ? k.table : `${k.schema}.${k.table}`, references: [] };
+            fk.columns.push(k.column);
+            fk.references.push(k.ref);
+            foreignKeys.set(k.id, fk);
+        }
+        const checks = await this.query(`SELECT c.CHECK_CLAUSE AS def
+         FROM information_schema.CHECK_CONSTRAINTS c
+         JOIN information_schema.TABLE_CONSTRAINTS t ON t.CONSTRAINT_SCHEMA = c.CONSTRAINT_SCHEMA AND t.CONSTRAINT_NAME = c.CONSTRAINT_NAME
+        WHERE t.TABLE_SCHEMA = COALESCE(?, DATABASE()) AND t.TABLE_NAME = ?`, [schema, name]);
+        return {
+            columns: columns.map((c) => ({
+                name: c.name,
+                type: c.type,
+                nullable: c.nullable === "YES",
+                hasDefault: c.dflt !== null || /auto_increment|generated/i.test(c.extra),
+                maxLength: c.max === null ? undefined : Number(c.max),
+                values: /^enum\(/i.test(c.type) ? [...c.type.matchAll(/'((?:[^']|'')*)'/g)].map((m) => m[1].replace(/''/g, "'")) : undefined,
+            })),
+            foreignKeys: [...foreignKeys.values()],
+            checks: checks.map((c) => c.def),
+        };
+    }
     async #primaryKey(table) {
         let key = this.#keys.get(table);
         if (!key) {