slicetest 0.8.0 → 0.10.0

package/dist/cli.js

@@ -7,8 +7,8 @@
 import { existsSync } from "node:fs";
 import { readFile } from "node:fs/promises";
 import path from "node:path";
-import { parseArgs } from "node:util";
 import { parse } from "yaml";
+import { compatStart, packageVersion, parseCliArgs, runOptions } from "./cli-run.js";
 import { CONFIG_NAMES } from "./config.js";
 const HELP = `Usage: slicetest [filters...] [options]
        slicetest init [--force]
@@ -46,15 +46,25 @@ Options:
       --upstream <url> import: the real service's base URL for --stub
       --uncovered      gen: only responses the last run didn't cover
       --force          init, gen: overwrite existing files
+  -u, --update         Rewrite snapshots (\`snapshot: true\` steps) that no longer match
+      --reporter <name> Vitest reporter: default, verbose, dot, junit, json, tap,
+                       github-actions (repeat for several)
+      --output-file <file> Where junit / json / tap reporters write
+      --shard <i/n>    Run the i-th of n parts of the suite (split CI jobs)
+      --shuffle        Run scenarios in a random order (the seed is printed), to find
+                       ones that depend on another's leftovers
+      --seed <n>       With --shuffle: repeat the order of that seed
+      --retry <n>      Run a failing scenario up to n more times
       --diagrams <dir> Write a Mermaid sequence diagram of every scenario to <dir>,
                        one Markdown page per scenario file
+  -v, --version        Show the version
   -h, --help           Show this help
 
 Config (paths are relative to the config file):
-  app:      { command, env, cwd, ready: { path } | { log }, readyTimeout }
+  app:      { command, env, cwd, ready: { path } | { log }, readyTimeout, restart, reset: { path }, idle: { path } }
   db:       { migrate: { atlas: { dir } } | { sql } | { command, inputs }, engine, seed, url, image, schemas, keep, ignoreChanges, reuse, queries }
   stubs:    [name | { name, openapi, autoReply, upstream, recordings }]
-  services: { name: { command, env, cwd, ready } }
+  services: { name: { command, env, cwd, ready, restart, reset: { path }, idle: { path } } }
   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}}
@@ -65,26 +75,11 @@ Config (paths are relative to the config file):
   include:  [globs]  default ["**/*.scenario.{yaml,yml}"]
 `;
 export async function main(argv = process.argv.slice(2)) {
-    const { values, positionals } = parseArgs({
-        args: argv,
-        allowPositionals: true,
-        options: {
-            config: { type: "string", short: "c" },
-            watch: { type: "boolean", short: "w" },
-            name: { type: "string", short: "t" },
-            tag: { type: "string", multiple: true },
-            help: { type: "boolean", short: "h" },
-            force: { type: "boolean" },
-            spec: { type: "string" },
-            out: { type: "string" },
-            uncovered: { type: "boolean" },
-            port: { type: "string" },
-            diagrams: { type: "string" },
-            stub: { type: "string" },
-            upstream: { type: "string" },
-            json: { type: "boolean" },
-        },
-    });
+    const { values, positionals } = parseCliArgs(argv);
+    if (values.version) {
+        process.stdout.write(`${await packageVersion()}\n`);
+        return;
+    }
     if (values.help) {
         process.stdout.write(HELP);
         return;
@@ -159,7 +154,8 @@ export async function main(argv = process.argv.slice(2)) {
     if (positionals[0] === "list") {
         const root = configPath && existsSync(configPath) ? path.dirname(configPath) : process.cwd();
         const { listScenarios, formatList } = await import("./list.js");
-        const listed = await listScenarios(root, { filters: positionals.slice(1), name: values.name, tags: values.tag?.join(",") });
+        const config = configPath && existsSync(configPath) ? (parse(await readFile(configPath, "utf8")) ?? {}) : undefined;
+        const listed = await listScenarios(root, { filters: positionals.slice(1), name: values.name, tags: values.tag?.join(","), include: config?.include });
         process.stdout.write(values.json ? `${JSON.stringify(listed, null, 2)}\n` : formatList(listed));
         if (listed.errors.length)
             process.exitCode = 1;
@@ -181,15 +177,16 @@ export async function main(argv = process.argv.slice(2)) {
         process.env.SLICETEST_DIAGRAMS = path.resolve(values.diagrams);
     if (values.tag?.length)
         process.env.SLICETEST_TAGS = values.tag.join(",");
-    const { startVitest, version } = await import("vitest/node");
+    const vitestNode = await import("vitest/node");
+    const { version } = vitestNode;
     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");
-    // Vitest 4 takes the mode ("test") first; 5 dropped it.
-    const start = (Number.parseInt(version, 10) === 4 ? startVitest.bind(null, "test") : startVitest);
+    const { slicetestPlugin, YAML_SCENARIOS } = await import("./vitest.js");
+    const start = compatStart(vitestNode);
+    const run = runOptions(values);
     const vitest = await start(positionals, {
         config: false,
         root: path.dirname(configPath),
@@ -197,7 +194,8 @@ export async function main(argv = process.argv.slice(2)) {
         watch: !!values.watch,
         run: !values.watch,
         testNamePattern: values.name,
-    }, { plugins: [slicetest(options)] });
+        ...run,
+    }, { plugins: [slicetestPlugin(options, { include: include ?? [YAML_SCENARIOS] })] });
     if (!values.watch)
         await vitest?.close();
 }

package/dist/config.d.ts

@@ -152,6 +152,29 @@ export interface AppOptions {
      * turns off Vitest's per-file module isolation (`isolate: false`).
      */
     scope?: "file" | "worker";
+    /**
+     * `"scenario"`: stop before the reset, start after. Not a cure for other processes, containers without `reset`
+     * or files. Default `"never"`: the process, and its caches and timers, outlive the scenario. Also on `services`.
+     */
+    restart?: "never" | "scenario";
+    /**
+     * Endpoint that drops in-process state, called after the reset. Not for work already in flight: it can still
+     * write before the call, so use `idle` or `restart`. A status of 400+ fails the scenario.
+     */
+    reset?: HookOptions;
+    /**
+     * 2xx once no background work is left. Not a fixed sleep: slicetest can't know when a job is done.
+     * Still busy after `timeout`: the scenario fails and the process is restarted.
+     */
+    idle?: HookOptions;
+}
+/** Sent by slicetest itself; not the scenario's `http` client. */
+export interface HookOptions {
+    path: string;
+    /** Default `POST` for `reset`, `GET` for `idle`. */
+    method?: string;
+    /** Milliseconds: how long `idle` is polled, or a `reset` request may take. Default 5000. */
+    timeout?: number;
 }
 export interface DbOptions {
     /**
@@ -169,8 +192,8 @@ export interface DbOptions {
      */
     url?: string;
     migrate?: MigrateOptions;
-    /** SQL file (relative to the vitest root) run after every reset. */
-    seed?: string;
+    /** Files (relative to the vitest root) applied after every reset: SQL, or YAML / JSON rows per table (`plans: [{ id: 1 }]`). */
+    seed?: string | string[];
     /** Schemas whose tables are reset between scenarios. Default `["public"]`. */
     schemas?: string[];
     /** Extra tables kept across resets, in addition to known migration bookkeeping tables. */
@@ -263,4 +286,12 @@ export interface ResolvedOptions {
 /** 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 declare const TOP_LEVEL_KEYS: readonly ["app", "db", "stubs", "openapi", "http", "services", "containers", "mail", "offline", "strictStubs", "workers", "auth", "include"];
+export declare const APP_KEYS: readonly ["command", "build", "cwd", "env", "ready", "readyTimeout", "scope", "restart", "reset", "idle", "baseEnv"];
+export declare const STUB_KEYS: readonly ["name", "openapi", "autoReply", "upstream", "recordings", "hosts"];
+export declare const CONTAINER_KEYS: readonly ["image", "port", "env", "command", "ready", "reset"];
+export declare const DB_KEYS: readonly ["engine", "image", "url", "migrate", "seed", "schemas", "keep", "ignoreChanges", "reuse", "queries", "neon"];
+export declare function editDistance(a: string, b: string): number;
+/** `db.seed` as a list of files, in the order they run. */
+export declare function seedFiles(seed: string | string[] | undefined): string[];
 export {};

package/dist/config.js

@@ -2,6 +2,7 @@
 export const CONFIG_NAMES = ["slicetest.config.yaml", "slicetest.config.yml", "slicetest.config.json"];
 export function resolveOptions(opts, root) {
     validate(opts);
+    opts = withStringEnv(opts);
     return {
         root,
         app: { ...opts.app, ready: resolveReady(opts.app.ready ?? { path: "/" }) },
@@ -26,6 +27,18 @@ export function resolveOptions(opts, root) {
         http: opts.http,
     };
 }
+/** YAML reads `DEBUG: true` and `WORKERS: 2` as a boolean and a number; a process only takes strings. */
+function withStringEnv(opts) {
+    const str = (p) => (p.env ? { ...p, env: Object.fromEntries(Object.entries(p.env).map(([k, v]) => [k, String(v)])) } : p);
+    const db = opts.db && opts.db.migrate && "command" in opts.db.migrate ? { ...opts.db, migrate: str(opts.db.migrate) } : opts.db;
+    return {
+        ...opts,
+        app: str(opts.app),
+        ...(opts.services ? { services: Object.fromEntries(Object.entries(opts.services).map(([n, s]) => [n, str(s)])) } : {}),
+        ...(opts.containers ? { containers: Object.fromEntries(Object.entries(opts.containers).map(([n, c]) => [n, str(c)])) } : {}),
+        ...(db !== undefined ? { db } : {}),
+    };
+}
 function resolveRecordings(stubs) {
     const withUpstream = stubs.filter((s) => typeof s === "object" && !!s.upstream);
     const env = (process.env.SLICETEST_RECORD ?? "").trim();
@@ -59,10 +72,55 @@ function resolveDb(db) {
         reuse: db.reuse ?? (!url && !process.env.CI),
     };
 }
+export const TOP_LEVEL_KEYS = ["app", "db", "stubs", "openapi", "http", "services", "containers", "mail", "offline", "strictStubs", "workers", "auth", "include"];
+export const APP_KEYS = ["command", "build", "cwd", "env", "ready", "readyTimeout", "scope", "restart", "reset", "idle", "baseEnv"];
+export const STUB_KEYS = ["name", "openapi", "autoReply", "upstream", "recordings", "hosts"];
+export const CONTAINER_KEYS = ["image", "port", "env", "command", "ready", "reset"];
+export const DB_KEYS = ["engine", "image", "url", "migrate", "seed", "schemas", "keep", "ignoreChanges", "reuse", "queries", "neon"];
+export function editDistance(a, b) {
+    const row = Array.from({ length: b.length + 1 }, (_, i) => i);
+    for (let i = 1; i <= a.length; i++) {
+        let prev = row[0];
+        row[0] = i;
+        for (let j = 1; j <= b.length; j++) {
+            const tmp = row[j];
+            row[j] = Math.min(row[j] + 1, row[j - 1] + 1, prev + (a[i - 1] === b[j - 1] ? 0 : 1));
+            prev = tmp;
+        }
+    }
+    return row[b.length];
+}
 function validate(opts) {
     const fail = (msg) => {
         throw new Error(`slicetest: invalid config: ${msg}`);
     };
+    // A misspelt key (`stub:`, `strictstubs:`) would otherwise be ignored without a word; YAML configs have no type checker.
+    const checkKeys = (value, allowed, where) => {
+        if (!value || typeof value !== "object" || Array.isArray(value))
+            return;
+        for (const key of Object.keys(value)) {
+            if (allowed.includes(key) || key === "$schema")
+                continue;
+            // Close in spelling, or sharing the first four letters (`servers` / `services`, `migrations` / `migrate`).
+            const near = allowed
+                .map((k) => ({ k, d: editDistance(k.toLowerCase(), key.toLowerCase()) }))
+                .filter(({ k, d }) => d <= Math.max(2, Math.floor(key.length / 3)) || (key.length >= 4 && k.toLowerCase().startsWith(key.slice(0, 4).toLowerCase())))
+                .sort((a, b) => a.d - b.d)[0];
+            const hint = near ? `; did you mean "${near.k}"?` : ` (expected ${allowed.join(", ")})`;
+            fail(`unknown key ${where}${key}${hint}`);
+        }
+    };
+    checkKeys(opts, TOP_LEVEL_KEYS, "");
+    checkKeys(opts?.app, APP_KEYS, "app.");
+    if (opts?.db)
+        checkKeys(opts.db, DB_KEYS, "db.");
+    for (const stub of opts?.stubs ?? [])
+        if (typeof stub === "object" && stub)
+            checkKeys(stub, STUB_KEYS, `stubs.${stub.name ?? "?"}.`);
+    for (const [name, service] of Object.entries(opts?.services ?? {}))
+        checkKeys(service, APP_KEYS, `services.${name}.`);
+    for (const [name, container] of Object.entries(opts?.containers ?? {}))
+        checkKeys(container, CONTAINER_KEYS, `containers.${name}.`);
     if (!opts?.app || typeof opts.app.command !== "string" || !opts.app.command.trim()) {
         fail("app.command is required, e.g. { app: { command: \"node server.js\" } }");
     }
@@ -72,7 +130,39 @@ function validate(opts) {
         if (ready && "path" in ready && !ready.path.startsWith("/"))
             fail(`${where}.ready.path must start with "/", got "${ready.path}"`);
     };
+    const checkEnv = (env, where) => {
+        if (env === undefined)
+            return;
+        if (!env || typeof env !== "object" || Array.isArray(env))
+            fail(`${where} maps variable names to values, e.g. { NODE_ENV: test }, got ${JSON.stringify(env)}`);
+        for (const [k, v] of Object.entries(env)) {
+            if (!["string", "number", "boolean"].includes(typeof v))
+                fail(`${where}.${k} must be a string, a number or true/false, got ${JSON.stringify(v)}`);
+        }
+    };
+    checkEnv(opts.app.env, "app.env");
+    for (const [name, s] of Object.entries(opts.services ?? {}))
+        checkEnv(s?.env, `services.${name}.env`);
+    for (const [name, c] of Object.entries(opts.containers ?? {}))
+        checkEnv(c?.env, `containers.${name}.env`);
     checkReady(opts.app.ready, "app");
+    const checkTimeout = (v, where) => {
+        if (v !== undefined && !(typeof v === "number" && v > 0))
+            fail(`${where} must be a positive number of milliseconds, got ${JSON.stringify(v)}`);
+    };
+    checkTimeout(opts.app.readyTimeout, "app.readyTimeout");
+    if (opts.http !== undefined) {
+        if (!opts.http || typeof opts.http !== "object" || Array.isArray(opts.http))
+            fail(`http must be { headers, timeout, follow }, got ${JSON.stringify(opts.http)}`);
+        checkKeys(opts.http, ["headers", "query", "follow", "timeout"], "http.");
+        checkTimeout(opts.http.timeout, "http.timeout");
+        if (opts.http.follow !== undefined && typeof opts.http.follow !== "boolean")
+            fail(`http.follow must be true or false, got ${JSON.stringify(opts.http.follow)}`);
+        const headers = opts.http.headers;
+        if (headers !== undefined && (!headers || typeof headers !== "object" || Array.isArray(headers) || Object.values(headers).some((v) => typeof v !== "string"))) {
+            fail('http.headers maps header names to strings, e.g. { accept: "application/json" }');
+        }
+    }
     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) => {
@@ -80,13 +170,35 @@ function validate(opts) {
             fail(`${where}.build must be a command, e.g. "npm run build"`);
     };
     checkBuild(opts.app.build, "app");
+    const checkLifecycle = (p, where) => {
+        if (p.restart !== undefined && p.restart !== "never" && p.restart !== "scenario")
+            fail(`${where}.restart must be "never" or "scenario", got ${JSON.stringify(p.restart)}`);
+        for (const key of ["reset", "idle"]) {
+            const hook = p[key];
+            if (hook === undefined)
+                continue;
+            if (!hook || typeof hook !== "object" || Array.isArray(hook))
+                fail(`${where}.${key} must be { path }, e.g. { path: "/__test/${key}" }`);
+            checkKeys(hook, ["path", "method", "timeout"], `${where}.${key}.`);
+            // Not just startsWith("/"): "//host/x" and "/\\host" resolve to another host.
+            if (typeof hook.path !== "string" || !/^\/(?![/\\])[^\s\\]*$/.test(hook.path))
+                fail(`${where}.${key}.path must be a path on the app starting with "/" (no "//", backslash or spaces), got ${JSON.stringify(hook.path)}`);
+            if (hook.method !== undefined && !(typeof hook.method === "string" && ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD"].includes(hook.method.toUpperCase())))
+                fail(`${where}.${key}.method must be GET, POST, PUT, PATCH, DELETE or HEAD, got ${JSON.stringify(hook.method)}`);
+            if (hook.timeout !== undefined && !(Number.isInteger(hook.timeout) && hook.timeout >= 1 && hook.timeout <= 600_000))
+                fail(`${where}.${key}.timeout must be between 1 and 600000 milliseconds, got ${JSON.stringify(hook.timeout)}`);
+        }
+    };
+    checkLifecycle(opts.app, "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}`);
+        checkTimeout(s.readyTimeout, `services.${name}.readyTimeout`);
         checkBuild(s.build, `services.${name}`);
+        checkLifecycle(s, `services.${name}`);
     }
     for (const [name, c] of Object.entries(opts.containers ?? {})) {
         if (!/^[\w-]+$/.test(name))
@@ -137,6 +249,10 @@ function validate(opts) {
         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 seed = dbOpts?.seed;
+    if (seed !== undefined && !(typeof seed === "string" ? seed : Array.isArray(seed) && seed.length > 0 && seed.every((f) => typeof f === "string" && f))) {
+        fail(`db.seed must be a file (SQL, YAML or JSON) or a list of them, e.g. seed.sql, got ${JSON.stringify(seed)}`);
+    }
     const migrate = dbOpts?.migrate;
     if (migrate) {
         const keys = Object.keys(migrate).filter((k) => ["atlas", "sql", "command"].includes(k));
@@ -146,8 +262,7 @@ function validate(opts) {
         if (menv !== undefined) {
             if (!("command" in migrate))
                 fail("db.migrate.env is for a migration `command`; atlas and sql get the database URL themselves");
-            if (!menv || typeof menv !== "object" || Array.isArray(menv) || Object.values(menv).some((v) => typeof v !== "string"))
-                fail('db.migrate.env maps variable names to strings, e.g. { DB_HOST: "{{db.host}}" }');
+            checkEnv(menv, "db.migrate.env");
         }
     }
     const oas = opts.openapi;
@@ -213,3 +328,7 @@ function stubName(s) {
 function escapeRegExp(s) {
     return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
+/** `db.seed` as a list of files, in the order they run. */
+export function seedFiles(seed) {
+    return seed === undefined ? [] : Array.isArray(seed) ? seed : [seed];
+}

package/dist/container-runtime.d.ts

@@ -6,3 +6,7 @@
 export declare function configureContainerRuntime(platform?: NodeJS.Platform): void;
 /** `\\.\pipe\podman-machine-default` → `npipe:////./pipe/podman-machine-default`. */
 export declare function dockerHost(location: string, windows: boolean): string;
+/** Testcontainers declares Node.js 22.22+; below that its HTTP library fails when it loads. */
+export declare function nodeTooOldForContainers(version?: string): boolean;
+/** Loads a Testcontainers module; on an old Node.js, says that is the reason instead of showing the library's TypeError. */
+export declare function loadContainers<T>(load: () => Promise<T>, version?: string): Promise<T>;

package/dist/container-runtime.js

@@ -29,3 +29,19 @@ export function configureContainerRuntime(platform = process.platform) {
 export function dockerHost(location, windows) {
     return windows ? `npipe://${location.replace(/\\/g, "/")}` : `unix://${location}`;
 }
+/** Testcontainers declares Node.js 22.22+; below that its HTTP library fails when it loads. */
+export function nodeTooOldForContainers(version = process.versions.node) {
+    const [major = 0, minor = 0] = version.split(".").map(Number);
+    return major < 22 || (major === 22 && minor < 22);
+}
+/** Loads a Testcontainers module; on an old Node.js, says that is the reason instead of showing the library's TypeError. */
+export async function loadContainers(load, version = process.versions.node) {
+    try {
+        return await load();
+    }
+    catch (e) {
+        if (!nodeTooOldForContainers(version))
+            throw e;
+        throw new Error(`slicetest: Node.js ${version} can't load the container library (${e.message}). Starting a database or a dependency in a container needs Node.js 22.22 or later: upgrade Node.js, or use a database server you run yourself (SLICETEST_DATABASE_URL or db.url; no containers are then started for it).`, { cause: e });
+    }
+}

package/dist/containers.js

@@ -1,5 +1,6 @@
 import { execFileSync } from "node:child_process";
-import { configureContainerRuntime } from "./container-runtime.js";
+import { configureContainerRuntime, loadContainers } from "./container-runtime.js";
+import { onProcessExit } from "./exit.js";
 /**
  * A container the app depends on (Redis, a search engine, an S3 emulator),
  * started for one test file and emptied between scenarios with `reset`.
@@ -15,7 +16,7 @@ export class Dependency {
     }
     static async start(name, opts) {
         configureContainerRuntime();
-        const { GenericContainer, Wait } = await import("testcontainers");
+        const { GenericContainer, Wait } = await loadContainers(() => import("testcontainers"));
         let definition = new GenericContainer(opts.image).withExposedPorts(opts.port);
         if (opts.env)
             definition = definition.withEnvironment(opts.env);
@@ -72,7 +73,7 @@ export class Dependency {
     }
 }
 const running = new Set();
-process.once("exit", () => {
+onProcessExit(() => {
     for (const d of running)
         d.removeNow();
 });

package/dist/db.d.ts

@@ -42,7 +42,7 @@ export declare class Db {
         schemas: string[];
         keep: string[];
         ignoreChanges?: string[];
-        seedFile?: string;
+        seedFiles?: string[];
     }): Promise<Db>;
     query<T extends Row = Row>(sql: string, params?: unknown[]): Promise<T[]>;
     /** Rows of a table, optionally filtered, ordered by the first column unless `orderBy` is given. */
@@ -98,6 +98,8 @@ export declare class Db {
     changesSinceStart(): Promise<Changes>;
     close(): Promise<void>;
 }
+/** A data seed file: `table: [rows]`, in file order; each row a mapping of columns. */
+export declare function seedRows(file: string, text: string): [string, Row[]][];
 /**
  * What `ignore` leaves out of one table: `"*"` for the whole table, else the columns.
  * `updated_at` is that column in every table, `orders.synced_at` in one, `sessions.*` the whole table

package/dist/db.js

@@ -1,4 +1,6 @@
 import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { parse as parseYaml } from "yaml";
 import { Factory } from "./factory.js";
 /** Tables that record applied migrations. Truncating them would make tools re-run migrations. */
 const MIGRATION_TABLES = [
@@ -26,7 +28,8 @@ export class Db {
     opts;
     #driver;
     #tables;
-    #seed;
+    /** SQL scripts, or rows per table from a YAML / JSON file. */
+    #seeds = [];
     /** Contents right after the reset (and seed); undefined means every table was empty. */
     #start;
     #checkpoint;
@@ -36,12 +39,14 @@ export class Db {
         this.url = url;
         this.opts = opts;
         this.#driver = driver;
-        this.#factory = new Factory((table) => driver.describe(table), (table, row) => driver.insert(table, row));
+        this.#factory = new Factory((table) => driver.describe(table), (table, row) => this.#insertRow(table, row));
     }
     static async connect(driver, url, opts) {
         const db = new Db(driver, url, opts);
-        if (opts.seedFile)
-            db.#seed = await readFile(opts.seedFile, "utf8");
+        db.#seeds = await Promise.all((opts.seedFiles ?? []).map(async (file) => {
+            const text = await readFile(file, "utf8");
+            return /\.(ya?ml|json)$/i.test(file) ? seedRows(file, text) : text;
+        }));
         return db;
     }
     async query(sql, params = []) {
@@ -81,9 +86,15 @@ export class Db {
         const list = Array.isArray(rows) ? rows : [rows];
         const out = [];
         for (const row of list)
-            out.push(...(await this.#driver.insert(table, row)));
+            out.push(...(await this.#insertRow(table, row)));
         return out;
     }
+    /** An explicit id would otherwise be handed out again by the sequence: the app's next insert would collide. */
+    async #insertRow(table, row) {
+        const stored = await this.#driver.insert(table, row);
+        await this.#driver.syncSequences?.(table, Object.keys(row));
+        return stored;
+    }
     /**
      * 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
@@ -131,13 +142,21 @@ export class Db {
     }
     /** Empty every data table without dropping the app's connections, then re-apply the seed. */
     async reset() {
-        this.#tables ??= await this.#listTables();
+        // Listed again each time: a table the app or a scenario created since the last reset must be emptied too.
+        this.#tables = await this.#listTables();
         await this.#driver.truncate(this.#tables);
         this.#factory.reset();
         this.#start = undefined;
         this.#checkpoint = undefined;
-        if (this.#seed) {
-            await this.#driver.exec(this.#seed);
+        if (this.#seeds.length) {
+            for (const seed of this.#seeds) {
+                if (typeof seed === "string")
+                    await this.#driver.exec(seed);
+                else
+                    for (const [table, rows] of seed)
+                        for (const row of rows)
+                            await this.#insertRow(table, row);
+            }
             this.#start = await this.#snapshot();
         }
     }
@@ -201,6 +220,24 @@ export class Db {
         await this.#driver.close();
     }
 }
+/** A data seed file: `table: [rows]`, in file order; each row a mapping of columns. */
+export function seedRows(file, text) {
+    let doc;
+    try {
+        doc = path.extname(file).toLowerCase() === ".json" ? JSON.parse(text) : parseYaml(text);
+    }
+    catch (e) {
+        throw new Error(`slicetest: seed ${file}: ${e.message}`);
+    }
+    if (!doc || typeof doc !== "object" || Array.isArray(doc))
+        throw new Error(`slicetest: seed ${file} must map tables to rows, e.g. plans: [{ id: 1, name: free }]`);
+    return Object.entries(doc).map(([table, rows]) => {
+        if (!Array.isArray(rows) || !rows.every((r) => r && typeof r === "object" && !Array.isArray(r))) {
+            throw new Error(`slicetest: seed ${file}: "${table}" must be a list of rows, e.g. ${table}: [{ id: 1, name: free }]`);
+        }
+        return [table, rows];
+    });
+}
 /**
  * What `ignore` leaves out of one table: `"*"` for the whole table, else the columns.
  * `updated_at` is that column in every table, `orders.synced_at` in one, `sessions.*` the whole table

package/dist/deadline.d.ts

@@ -0,0 +1,7 @@
+export declare function setScenarioDeadline(started: number, timeout: number | undefined): void;
+export declare function clearScenarioDeadline(): void;
+/** `ms`, or less when the scenario's timeout ends first; `note` says so for the error message. */
+export declare function waitBudget(ms: number): {
+    ms: number;
+    note: string;
+};

package/dist/deadline.js

@@ -0,0 +1,24 @@
+/** When the running scenario's own timeout ends (epoch ms); shared across copies of the package. */
+const KEY = Symbol.for("slicetest.deadline");
+const slot = globalThis;
+/** Kept short of the timeout, so the wait's own message (what it waited for) is what the user sees. */
+const MARGIN = 300;
+export function setScenarioDeadline(started, timeout) {
+    if (timeout)
+        slot[KEY] = { at: started + timeout, timeout };
+    else
+        delete slot[KEY];
+}
+export function clearScenarioDeadline() {
+    delete slot[KEY];
+}
+/** `ms`, or less when the scenario's timeout ends first; `note` says so for the error message. */
+export function waitBudget(ms) {
+    const d = slot[KEY];
+    if (!d)
+        return { ms, note: "" };
+    const left = d.at - MARGIN - Date.now();
+    if (left >= ms)
+        return { ms, note: "" };
+    return { ms: Math.max(0, left), note: ` (the scenario's timeout of ${d.timeout}ms ends then; raise it with \`timeout:\`)` };
+}

package/dist/doctor.js

@@ -5,15 +5,16 @@ 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 { seedRows } from "./db.js";
+import { resolveOptions, seedFiles } from "./config.js";
+import { configureContainerRuntime, loadContainers } 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 { getContainerRuntimeClient } = await loadContainers(() => 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}`;
@@ -121,8 +122,29 @@ export async function doctor(configPath, probes = machine, env = process.env) {
     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 file of seedFiles(opts.db.seed)) {
+        if (!/\.(ya?ml|json)$/i.test(file)) {
+            await checkPath(add, "seed", file, root, rel);
+            continue;
+        }
+        // A data seed is read here, so a broken one is reported before any container starts.
+        let text;
+        try {
+            text = await readFile(path.resolve(root, file), "utf8");
+        }
+        catch {
+            await checkPath(add, "seed", file, root, rel);
+            continue;
+        }
+        try {
+            const tables = seedRows(file, text);
+            add("ok", `seed ${rel(file)} (${tables.map(([t, rows]) => `${t} ×${rows.length}`).join(", ") || "no tables"})`);
+        }
+        catch (e) {
+            const why = e.message.replace(/^slicetest: seed [^:]+: /, "");
+            add("fail", /must be a list|must map/.test(why) ? `seed ${rel(file)} isn't rows per table` : `seed ${rel(file)} isn't valid ${path.extname(file).slice(1).toUpperCase()}`, why);
+        }
+    }
     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);

package/dist/drivers/driver.d.ts

@@ -58,6 +58,12 @@ 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[]>;
+    /**
+     * Move `table`'s id sequences past the ids it holds, after rows were inserted with explicit ids
+     * (only those of `columns`, when given). Only Postgres needs it: MySQL's AUTO_INCREMENT and
+     * SQLite's rowid follow the largest id themselves.
+     */
+    syncSequences?(table: string, columns?: string[]): Promise<void>;
     /** Columns, foreign keys and checks of `table`. Throws when there is no such table. */
     describe(table: string): Promise<TableShape>;
     close(): Promise<void>;

package/dist/drivers/mysql.js

@@ -1,4 +1,5 @@
 import mysql from "mysql2/promise";
+import { loadContainers } from "../container-runtime.js";
 /**
  * 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
@@ -290,7 +291,10 @@ export const mysqlEngine = {
     name: "mysql",
     defaultImage: "mysql:8.4",
     async startContainer(image, reuse) {
-        const { MySqlContainer } = await import("@testcontainers/mysql").catch(() => {
+        const { MySqlContainer } = await loadContainers(() => import("@testcontainers/mysql")).catch((e) => {
+            // An old Node.js already has its own explanation; a missing package gets the install hint.
+            if (/^slicetest: Node\.js/.test(e.message))
+                throw e;
             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);