slicetest 0.4.0 → 0.6.0

package/dist/cli.js

@@ -9,7 +9,7 @@ import { readFile } from "node:fs/promises";
 import path from "node:path";
 import { parseArgs } from "node:util";
 import { parse } from "yaml";
-const CONFIG_NAMES = ["slicetest.config.yaml", "slicetest.config.yml", "slicetest.config.json"];
+import { CONFIG_NAMES } from "./config.js";
 const HELP = `Usage: slicetest [filters...] [options]
        slicetest init [--force]
        slicetest gen [--spec <file>] [--out <dir>] [--uncovered] [--force]
@@ -39,11 +39,12 @@ Options:
 
 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}"]
@@ -86,17 +87,21 @@ export async function main(argv = process.argv.slice(2)) {
         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;
@@ -112,9 +117,16 @@ export async function main(argv = process.argv.slice(2)) {
         await record(configPath, options, { out: values.out, port: values.port ? Number(values.port) : 0 });
         return;
     }
-    const { startVitest } = await import("vitest/node");
+    const { startVitest, version } = await import("vitest/node");
+    if (Number.parseInt(version, 10) < 4) {
+        process.stderr.write(`slicetest: needs Vitest 4 or later, and this project has Vitest ${version}. Upgrade it (npm i -D vitest@latest), or run slicetest from a folder with its own package.json.\n`);
+        process.exitCode = 1;
+        return;
+    }
     const { slicetest, YAML_SCENARIOS } = await import("./vitest.js");
-    const vitest = await startVitest(positionals, {
+    // Vitest 4 takes the mode ("test") first; 5 dropped it.
+    const start = (Number.parseInt(version, 10) === 4 ? startVitest.bind(null, "test") : startVitest);
+    const vitest = await start(positionals, {
         config: false,
         root: path.dirname(configPath),
         include: include ?? [YAML_SCENARIOS],

package/dist/config.d.ts

@@ -1,7 +1,9 @@
+import type { AuthOptions } from "./auth.js";
 import type { RequestOptions } from "./http.js";
 export interface SlicetestOptions {
     app: AppOptions;
-    db?: DbOptions;
+    /** The database, or `false` for an app without one: no container, no resets, no `{{db.*}}`. */
+    db?: DbOptions | false;
     /**
      * Outbound HTTP services to stub. Each gets its own server, referenced as `{{stub.<name>}}` in `app.env`.
      * With `{ name, openapi }`, the app's calls to it and the stub's replies are checked against that service's spec.
@@ -17,7 +19,8 @@ export interface SlicetestOptions {
      * a lower coverage fails the run.
      */
     openapi?: string | {
-        spec: string;
+        spec?: string;
+        fromApp?: string;
         minCoverage?: number;
     };
     /** Defaults for every request made with `http`, e.g. `{ headers: { accept: "application/json" } }`. */
@@ -43,6 +46,24 @@ export interface SlicetestOptions {
      * scenarios read what arrived with `mail.messages()` / `mail.waitFor()`.
      */
     mail?: boolean;
+    /**
+     * Keep the app off the network: its HTTP(S) calls may only reach localhost and the
+     * hosts of stubs with `hosts`. A call anywhere else is refused and fails the
+     * scenario, naming the host, so a forgotten stub can't reach a real service.
+     */
+    offline?: boolean;
+    /**
+     * Most Vitest workers to run test files in (Vitest's `maxWorkers`). Each worker has
+     * its own app and database; with `app.scope: "worker"`, fewer workers means fewer app
+     * starts, which is what makes a slow-starting app fast to test.
+     */
+    workers?: number;
+    /**
+     * 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;
@@ -72,6 +93,12 @@ export interface StubOptions {
     upstream?: string;
     /** Recordings file, relative to the root. Default `recordings/<name>.yaml`. */
     recordings?: string;
+    /**
+     * Hosts the app calls directly, e.g. `["api.github.com"]`: their HTTP and HTTPS
+     * traffic is answered by this stub, for apps whose URLs can't be set from the
+     * environment. The app is started with proxy variables and a test CA it trusts.
+     */
+    hosts?: string[];
 }
 export interface ServiceOptions extends Omit<AppOptions, "ready"> {
     /** Default: no wait (for workers that don't listen). `{ path }` polls the service's own port. */
@@ -84,12 +111,20 @@ type ResolvedReady = {
     flags: string;
 };
 /** A process to start, with `ready` made JSON-serializable. The app always has `ready`; services may not. */
-export type ResolvedProcess = Omit<AppOptions, "ready"> & {
+export type ResolvedProcess = Omit<AppOptions, "ready" | "scope"> & {
     ready?: ResolvedReady;
+    /** Set by slicetest (proxy variables for intercepted hosts); `env` overrides it. */
+    baseEnv?: Record<string, string>;
 };
 export interface AppOptions {
     /** Command that starts the app, run through the shell. */
     command: string;
+    /**
+     * Command run once per run, before any worker starts the process, e.g.
+     * `npm run build` for an app started with `next start`. Runs in `cwd` while
+     * the database starts. Not repeated on re-runs in watch mode.
+     */
+    build?: string;
     cwd?: string;
     /**
      * Environment passed to the app. Values may reference
@@ -105,6 +140,13 @@ export interface AppOptions {
     };
     /** Milliseconds to wait for readiness. Default 30000. */
     readyTimeout?: number;
+    /**
+     * `"file"` (default) starts the app, stubs and services for each test file.
+     * `"worker"` starts them once per Vitest worker and keeps them for every file that
+     * worker runs, for apps that take seconds to start (a JVM, a large framework). It
+     * turns off Vitest's per-file module isolation (`isolate: false`).
+     */
+    scope?: "file" | "worker";
 }
 export interface DbOptions {
     /**
@@ -135,6 +177,18 @@ 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;
+    /**
+     * For apps on Neon's serverless driver over HTTP (`neon()` from @neondatabase/serverless,
+     * drizzle-orm/neon-http): `{{db.url}}` becomes a Neon-style connection string, and
+     * slicetest answers the driver's HTTP queries from the test database. Postgres only.
+     */
+    neon?: boolean;
 }
 export type MigrateOptions = {
     atlas: {
@@ -154,17 +208,26 @@ export type MigrateOptions = {
 /** Normalized shape passed from the plugin to globalSetup and workers. Must stay JSON-serializable. */
 export interface ResolvedOptions {
     root: string;
-    app: Omit<AppOptions, "ready"> & {
+    app: ResolvedProcess & {
         ready: ResolvedReady;
+        scope?: "file" | "worker";
     };
     services: Record<string, ResolvedProcess>;
     containers: Record<string, ContainerOptions>;
     mail: boolean;
-    db: Required<Pick<DbOptions, "engine" | "image" | "schemas" | "keep" | "reuse">> & Omit<DbOptions, "engine" | "image" | "schemas" | "keep" | "reuse">;
+    offline: boolean;
+    workers?: number;
+    auth: AuthOptions | false;
+    db: Required<Pick<DbOptions, "engine" | "image" | "schemas" | "keep" | "reuse">> & Omit<DbOptions, "engine" | "image" | "schemas" | "keep" | "reuse"> & {
+        /** `db: false`: the app has no database. */
+        none?: boolean;
+    };
     stubs: string[];
     /** Spec files, resolved against the root: the app's, and per stub name. */
+    /** `fromApp`: a path the running app serves its own spec at (springdoc, FastAPI, NestJS). */
     openapi: {
         app?: string;
+        fromApp?: string;
         minCoverage?: number;
         stubs: Record<string, string>;
         autoReply: string[];
@@ -175,7 +238,11 @@ export interface ResolvedOptions {
         upstream: string;
         record: boolean;
     }>;
+    /** Intercepted host (lower case) → the stub that answers it. */
+    intercept: Record<string, string>;
     http?: RequestOptions;
 }
+/** The config files `npx slicetest` (and `slicetest()` without options) look for, in order. */
+export declare const CONFIG_NAMES: string[];
 export declare function resolveOptions(opts: SlicetestOptions, root: string): ResolvedOptions;
 export {};

package/dist/config.js

@@ -1,3 +1,5 @@
+/** The config files `npx slicetest` (and `slicetest()` without options) look for, in order. */
+export const CONFIG_NAMES = ["slicetest.config.yaml", "slicetest.config.yml", "slicetest.config.json"];
 export function resolveOptions(opts, root) {
     validate(opts);
     return {
@@ -6,15 +8,20 @@ export function resolveOptions(opts, root) {
         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,
-        db: resolveDb(opts.db ?? {}),
+        offline: opts.offline ?? false,
+        workers: opts.workers,
+        auth: opts.auth === true ? {} : (opts.auth ?? false),
+        db: opts.db === false ? { ...resolveDb({}), none: true } : resolveDb(opts.db ?? {}),
         stubs: (opts.stubs ?? []).map(stubName),
         openapi: {
             app: typeof opts.openapi === "object" ? opts.openapi.spec : opts.openapi,
+            fromApp: typeof opts.openapi === "object" ? opts.openapi.fromApp : undefined,
             minCoverage: typeof opts.openapi === "object" ? opts.openapi.minCoverage : undefined,
             stubs: Object.fromEntries((opts.stubs ?? []).flatMap((s) => (typeof s === "object" && s.openapi ? [[s.name, s.openapi]] : []))),
             autoReply: (opts.stubs ?? []).flatMap((s) => (typeof s === "object" && s.autoReply ? [s.name] : [])),
         },
         recordings: resolveRecordings(opts.stubs ?? []),
+        intercept: Object.fromEntries((opts.stubs ?? []).flatMap((s) => (typeof s === "object" ? (s.hosts ?? []).map((h) => [h.toLowerCase(), s.name]) : []))),
         http: opts.http,
     };
 }
@@ -65,12 +72,20 @@ function validate(opts) {
             fail(`${where}.ready.path must start with "/", got "${ready.path}"`);
     };
     checkReady(opts.app.ready, "app");
+    if (opts.app.scope !== undefined && opts.app.scope !== "file" && opts.app.scope !== "worker")
+        fail(`app.scope must be "file" or "worker", got ${JSON.stringify(opts.app.scope)}`);
+    const checkBuild = (build, where) => {
+        if (build !== undefined && (typeof build !== "string" || !build.trim()))
+            fail(`${where}.build must be a command, e.g. "npm run build"`);
+    };
+    checkBuild(opts.app.build, "app");
     for (const [name, s] of Object.entries(opts.services ?? {})) {
         if (!/^[\w-]+$/.test(name))
             fail(`service name "${name}" may only contain letters, digits, "_" and "-"`);
         if (!s || typeof s.command !== "string" || !s.command.trim())
             fail(`services.${name}.command is required`);
         checkReady(s.ready, `services.${name}`);
+        checkBuild(s.build, `services.${name}`);
     }
     for (const [name, c] of Object.entries(opts.containers ?? {})) {
         if (!/^[\w-]+$/.test(name))
@@ -85,14 +100,38 @@ function validate(opts) {
                 fail(`containers.${name}.${key} must be a list of strings, e.g. ["redis-cli", "FLUSHALL"]`);
         }
     }
+    if (opts.workers !== undefined && !(Number.isInteger(opts.workers) && opts.workers >= 1))
+        fail(`workers must be a positive whole number, got ${JSON.stringify(opts.workers)}`);
+    if (opts.offline !== undefined && typeof opts.offline !== "boolean")
+        fail(`offline must be true or false, got ${JSON.stringify(opts.offline)}`);
     if (opts.mail !== undefined && typeof opts.mail !== "boolean")
         fail(`mail must be true or false, got ${JSON.stringify(opts.mail)}`);
-    const engine = opts.db?.engine;
+    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 dbOpts = opts.db === false ? undefined : opts.db;
+    const engine = dbOpts?.engine;
     if (engine !== undefined && engine !== "postgres" && engine !== "mysql" && engine !== "sqlite")
         fail(`db.engine must be "postgres", "mysql" or "sqlite", got ${JSON.stringify(engine)}`);
-    if (engine === "sqlite" && opts.db?.url)
+    if (dbOpts?.queries !== undefined && typeof dbOpts.queries !== "boolean")
+        fail(`db.queries must be true or false, got ${JSON.stringify(dbOpts.queries)}`);
+    if (dbOpts?.neon !== undefined && typeof dbOpts.neon !== "boolean")
+        fail(`db.neon must be true or false, got ${JSON.stringify(dbOpts.neon)}`);
+    if (dbOpts?.neon && (engine === "mysql" || engine === "sqlite"))
+        fail("db.neon is Neon's protocol for Postgres; it doesn't apply to " + engine);
+    if (engine === "sqlite" && dbOpts?.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" && dbOpts?.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;
+    const migrate = dbOpts?.migrate;
     if (migrate) {
         const keys = Object.keys(migrate).filter((k) => ["atlas", "sql", "command"].includes(k));
         if (keys.length !== 1)
@@ -101,8 +140,15 @@ function validate(opts) {
     const oas = opts.openapi;
     if (oas !== undefined) {
         const spec = typeof oas === "object" && oas ? oas.spec : oas;
-        if (typeof spec !== "string" || !spec)
-            fail('openapi must be the path of an OpenAPI file, or { spec, minCoverage }');
+        const fromApp = typeof oas === "object" && oas ? oas.fromApp : undefined;
+        if (fromApp !== undefined) {
+            if (spec !== undefined)
+                fail("openapi takes either spec (a file) or fromApp (a path the app serves its spec at), not both");
+            if (typeof fromApp !== "string" || !fromApp.startsWith("/"))
+                fail(`openapi.fromApp must be a path on the app such as "/v3/api-docs", got ${JSON.stringify(fromApp)}`);
+        }
+        else if (typeof spec !== "string" || !spec)
+            fail('openapi must be the path of an OpenAPI file, or { spec, minCoverage }, or { fromApp: "/v3/api-docs" }');
         const min = typeof oas === "object" ? oas.minCoverage : undefined;
         if (min !== undefined && !(typeof min === "number" && min >= 0 && min <= 100))
             fail("openapi.minCoverage must be a percentage between 0 and 100");
@@ -116,6 +162,28 @@ function validate(opts) {
             fail(`stub "${s.name}": upstream must be an http(s) URL, got ${JSON.stringify(s.upstream)}`);
         if (typeof s === "object" && s.recordings !== undefined && !s.upstream)
             fail(`stub "${s.name}": recordings needs an upstream to record from`);
+        if (typeof s === "object" && s.hosts !== undefined) {
+            if (!Array.isArray(s.hosts) || s.hosts.length === 0)
+                fail(`stub "${s.name}": hosts must be a list of host names, e.g. ["api.github.com"]`);
+            for (const h of s.hosts) {
+                if (typeof h !== "string" || !/^(\*\.)?[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)+$|^[a-z0-9-]+$/i.test(h)) {
+                    fail(`stub "${s.name}": hosts takes host names (or *.domain for every subdomain), no scheme, port or path; got ${JSON.stringify(h)}`);
+                }
+                if (["localhost", "127.0.0.1"].includes(h.toLowerCase()))
+                    fail(`stub "${s.name}": ${h} can't be intercepted; point the app at {{stub.${s.name}}} instead`);
+            }
+        }
+    }
+    const seen = new Map();
+    for (const s of opts.stubs ?? []) {
+        if (typeof s !== "object")
+            continue;
+        for (const h of s.hosts ?? []) {
+            const other = seen.get(h.toLowerCase());
+            if (other)
+                fail(`host ${h} is intercepted by both stub "${other}" and stub "${s.name}"`);
+            seen.set(h.toLowerCase(), s.name);
+        }
     }
     const stubs = (opts.stubs ?? []).map(stubName);
     for (const name of stubs) {

package/dist/containers.d.ts

@@ -19,4 +19,6 @@ export declare class Dependency {
     /** Start of a scenario: run the `reset` command, if any. */
     reset(): Promise<void>;
     stop(): Promise<void>;
+    /** Synchronous removal for a worker exiting without tearing down (Ryuk is often off with Podman). */
+    removeNow(): void;
 }

package/dist/containers.js

@@ -1,3 +1,4 @@
+import { execFileSync } from "node:child_process";
 import { configureContainerRuntime } from "./container-runtime.js";
 /**
  * A container the app depends on (Redis, a search engine, an S3 emulator),
@@ -23,7 +24,9 @@ export class Dependency {
         if (opts.ready)
             definition = definition.withWaitStrategy(Wait.forLogMessage(opts.ready.log));
         try {
-            return new Dependency(name, await definition.start(), opts);
+            const dependency = new Dependency(name, await definition.start(), opts);
+            running.add(dependency);
+            return dependency;
         }
         catch (e) {
             throw new Error(`slicetest: container "${name}" (${opts.image}) didn't start: ${e.message}`);
@@ -54,6 +57,22 @@ export class Dependency {
             await this.exec(this.opts.reset);
     }
     async stop() {
+        running.delete(this);
         await this.container.stop();
     }
+    /** Synchronous removal for a worker exiting without tearing down (Ryuk is often off with Podman). */
+    removeNow() {
+        for (const cli of ["docker", "podman"]) {
+            try {
+                execFileSync(cli, ["rm", "-f", this.container.getId()], { stdio: "ignore", timeout: 10_000, windowsHide: true });
+                return;
+            }
+            catch { }
+        }
+    }
 }
+const running = new Set();
+process.once("exit", () => {
+    for (const d of running)
+        d.removeNow();
+});

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>;
     /**
@@ -69,3 +95,5 @@ export declare class Db {
 }
 /** Short summary of `changes()` for failure output. */
 export declare function formatChanges(changes: Changes, maxRows?: number): string;
+/** The `db` of an app without a database (`db: false`): resetting is a no-op, anything else explains. */
+export declare function noDatabase(): Db;

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) {
@@ -232,3 +282,21 @@ export function formatChanges(changes, maxRows = 3) {
 function truncate(s, max = 200) {
     return s.length > max ? `${s.slice(0, max)}…` : s;
 }
+/** The `db` of an app without a database (`db: false`): resetting is a no-op, anything else explains. */
+export function noDatabase() {
+    const off = () => {
+        throw new Error("slicetest: the app has no database (db: false), so db.* isn't available. Configure `db` to use it.");
+    };
+    return new Proxy({}, {
+        get(_, prop) {
+            if (prop === "reset" || prop === "close")
+                return async () => { };
+            if (prop === "changesSinceStart")
+                return async () => ({});
+            if (prop === "then")
+                return undefined;
+            // The real methods are async, so this rejects like they would.
+            return async () => off();
+        },
+    });
+}

package/dist/doctor.js

@@ -67,7 +67,12 @@ export async function doctor(configPath, probes = machine, env = process.env) {
     }
     // 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") {
+    if (opts.db.none) {
+        add("ok", "no database (db: false)");
+        if (Object.keys(opts.containers).length)
+            await checkContainerRuntime(add, probes, `runs ${Object.values(opts.containers).map((c) => c.image).join(", ")}`);
+    }
+    else 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)");
@@ -97,7 +102,10 @@ export async function doctor(configPath, probes = machine, env = process.env) {
         }
     }
     const m = opts.db.migrate;
-    if (!m)
+    if (opts.db.none) {
+        // Nothing to migrate.
+    }
+    else 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);
@@ -118,12 +126,16 @@ export async function doctor(configPath, probes = machine, env = process.env) {
     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)) {
+        const seen = new Set();
+        for (const command of [p.build, p.command]) {
+            const program = command && firstWord(command);
+            if (!program || /^[.\\/]|\{\{|\$/.test(program) || seen.has(program))
+                continue;
+            seen.add(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`);
+                add("warn", `${label}: ${program} not found on PATH`, `\`${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])];

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. */

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;