slicetest 0.2.0 → 0.3.0

package/README.md

@@ -4,7 +4,7 @@
 
 Tests that sit between unit tests and end-to-end tests, for apps written in any language or framework.
 
-slicetest starts your app as a real process, points it at a real Postgres and at stub servers for the services it calls, and lets you check all three sides in one scenario:
+slicetest starts your app as a real process, points it at a real Postgres (or MySQL) and at stub servers for the services it calls, and lets you check all three sides in one scenario:
 
 ```ts
 import { expect } from "vitest";
@@ -38,14 +38,17 @@ npx slicetest init   # detects your stack, writes slicetest.config.yaml and a fi
 npx slicetest        # starts Postgres, migrates, starts your app, runs scenarios/*.scenario.yaml
 ```
 
-`init` recognises Node (`npm start`), Django, FastAPI, Flask, Rails, Go and Rust apps; Atlas, Prisma, Alembic, Django, Rails, Drizzle, Knex and plain SQL migrations; and an `openapi.yaml`. It lists every guess as a comment in the config so you know what to check.
+`init` recognises Node (`npm start`), Django, FastAPI, Flask, Rails, Go and Rust apps; Atlas, Prisma, Alembic, Django, Rails, Drizzle, Knex and plain SQL migrations; and an `openapi.yaml`. If there's a `compose.yaml` / `docker-compose.yml`, its database service sets `db.image` (and `db.engine: mysql` for MySQL or MariaDB), and Redis, Valkey, Mongo, Elasticsearch, MinIO, RabbitMQ and other services with a port become [`containers`](#containers-redis-search-s3-and-other-dependencies), with a reset command where one is known and the usual variable (`REDIS_URL`, `S3_ENDPOINT`, …) passed to the app. It lists every guess as a comment in the config so you know what to check.
 
 ## What you get that's hard to find elsewhere
 
 - **One scenario, three boundaries.** Assert on the HTTP response, the rows in the real database and the calls to third-party APIs in the same test, in any language the app is written in.
 - **`db.changes()`**: a diff of every row the scenario inserted, updated or deleted. `toEqual` on it catches writes you didn't expect.
 - **Stubs that can't lie.** Give a stub the provider's OpenAPI spec, and a canned reply the real service would never send fails the test.
-- **OpenAPI coverage** of your own API, per operation and status, across all scenarios.
+- **Whole-scenario snapshots.** `expect(await trace()).toMatchSnapshot()` pins the responses, the outbound calls and the database changes in one reviewable file, with dates and UUIDs masked.
+- **Record the real service once, replay forever.** Point a stub at the real API with `SLICETEST_RECORD=1`, commit the YAML it writes, and later runs are offline and deterministic.
+- **OpenAPI coverage** of your own API, per operation and status, across all scenarios, and `slicetest gen --uncovered` to scaffold scenarios for what's missing.
+- **Postgres or MySQL**, with the same scenarios and the same row types on both, plus Redis, MinIO or any other `containers` reset between scenarios.
 - **Fast resets.** `TRUNCATE` between scenarios (about 1.5 ms) with the app still running, and a cached migrated template, so the second run skips container start-up and migrations.
 
 ## Install
@@ -56,6 +59,16 @@ npm i -D slicetest vitest
 
 You also need Docker or Podman. slicetest finds a running Podman machine on its own (on Windows too). Alternatively, pass `db.url` or set `SLICETEST_DATABASE_URL` to use an existing Postgres server, for example a CI service container.
 
+### MySQL
+
+Set `db: { engine: "mysql" }` (or give a `mysql://` URL) and install the driver:
+
+```sh
+npm i -D mysql2 @testcontainers/mysql   # the second is only needed without db.url
+```
+
+Everything works the same: `mysql:8.4` in a container, a migrated template cloned per worker (tables, foreign keys, views and triggers; stored routines are not copied), a `TRUNCATE` reset that only touches tables that were written to, and `db.*` helpers whose rows look like Postgres's (`BOOLEAN` as `true`/`false`, `BIGINT` ids as numbers, `DATETIME` in UTC). Only the SQL you write yourself differs: `?` placeholders in `db.query` and YAML `sql` steps. `db.schemas` defaults to the database in the URL. `SLICETEST_DATABASE_URL` is only used by projects on the same engine as its scheme, so a CI job can provide one Postgres server while a MySQL project starts its own container.
+
 Works on macOS, Linux and Windows. On Windows the app's process tree is stopped with `taskkill /T`, and `app.command` / `db.migrate.command` run through `cmd.exe`.
 
 ## Configure
@@ -246,6 +259,24 @@ To fail the run below a threshold, use `openapi: { spec: "openapi.yaml", minCove
 
 The example apps in `examples/` run every scenario against `examples/openapi.yaml` with `minCoverage: 100`, and their Slack calls against `examples/slack.openapi.yaml`.
 
+### Recording a real service
+
+A stub can also answer from recordings of the real service, the way VCR or Polly do, except that it works for an app in any language because the stub is a server. Give it the real base URL:
+
+```ts
+stubs: [{ name: "github", upstream: "https://api.github.com" }],
+```
+
+Record once, with real credentials in the app's environment:
+
+```sh
+SLICETEST_RECORD=github npx vitest     # or SLICETEST_RECORD=1 for every stub with an upstream
+```
+
+Calls no route matches are forwarded to `upstream` (under its path prefix, headers included) and the answers are written to `recordings/github.yaml` (`recordings:` changes the path). Later runs replay them without touching the network. A request is identified by method, path, query and body (JSON key order doesn't matter); identical requests replay their recordings in the order they were made. Only `content-type`, `location`, `retry-after`, `link` and `etag` response headers are kept, and request headers are never stored, so tokens stay out of the file; bodies are stored as sent, so review the file before committing it.
+
+Precedence is: registered route, then recording, then `autoReply`, then a 501 that says how to record the call. Replayed calls have `call.fallback === true`, and are checked against the provider's spec when the stub has one. To refresh recordings, delete the file (or the entries) and record again.
+
 ### Matchers
 
 Registered automatically:
@@ -291,6 +322,22 @@ scenario("uploading an image queues a thumbnail job", async ({ http, db, service
 
 `waitForLog(pattern, timeout = 5000)` resolves with the matching line and also works on `app`. In YAML: `- log: thumbnail \d+ done` with `from: worker` and `within: <ms>`.
 
+### Containers: Redis, search, S3 and other dependencies
+
+Anything else the app talks to can run as a container next to the database. Each test file gets its own, and `reset` runs inside it before every scenario, like the database's `TRUNCATE`:
+
+```ts
+slicetest({
+  containers: {
+    cache: { image: "redis:7-alpine", port: 6379, reset: ["redis-cli", "FLUSHALL"] },
+    s3: { image: "minio/minio", port: 9000, command: ["server", "/data"], env: { MINIO_ROOT_USER: "test", MINIO_ROOT_PASSWORD: "testtest" } },
+  },
+  app: { command: "node server.js", env: { REDIS_URL: "redis://{{container.cache}}", S3_ENDPOINT: "http://{{container.s3}}" } },
+});
+```
+
+`{{container.<name>}}` is `host:port`; `.host` and `.port` are there too. The container is ready when its port accepts connections, or when it prints `ready: { log }`. In a scenario, `container("cache").exec(["redis-cli", "GET", "hits"])` runs a command inside it and returns its stdout.
+
 ### Asynchronous side effects
 
 If the app does work in the background (a job queue, a fire-and-forget webhook), wait for the effect with Vitest's own helpers. slicetest doesn't need its own:
@@ -302,10 +349,28 @@ await expect.poll(() => db.count("jobs", { status: "done" })).toBe(1);
 
 In YAML, add `within: <ms>` to a `db`, `sql`, `received` or `changes` step.
 
+### Snapshot the whole scenario: `trace()`
+
+Because every scenario starts from the same database, ids and rows come out the same on every run. `trace()` returns everything the scenario did at the three boundaries: requests to the app with their responses, calls to each stub with the replies' statuses, and the database changes. Snapshot it, and a change in any of them shows up in review:
+
+```ts
+scenario("voting flow", async ({ http, stub, trace }) => {
+  stub("slack").on("POST", "/hook").reply(200, "ok");
+  const { json } = await http.post("/polls", { title: "Tea or coffee", a: "tea", b: "coffee" });
+  await http.post(`/polls/${json.id}/votes`, { choice: "b" });
+
+  expect(await trace()).toMatchSnapshot();
+});
+```
+
+Dates (`Date` values and ISO strings) become `[date]` and UUIDs `[uuid]`. Mask more with `trace({ keys: ["token"], patterns: [/^tok_/] })`, or use `mask(value, opts)` from `slicetest` on anything else. Update snapshots with `vitest -u`. In YAML, the step is `snapshot: true` (with `mask: [token]`).
+
+The example apps share one snapshot file: the Node and the Python implementation must produce the same trace, byte for byte.
+
 ### Scenarios
 
 ```ts
-scenario("name", async ({ http, db, stub, app }) => { ... }, timeoutMs?);
+scenario("name", async ({ http, db, stub, app, service, container, trace }) => { ... }, timeoutMs?);
 scenario.only / scenario.skip / scenario.todo
 scenario.each([{ choice: "a", status: 204 }, { choice: "x", status: 400 }])(
   "voting $choice returns $status",
@@ -324,15 +389,17 @@ Scenarios in one file share an app and a database, so they always run one at a t
 | `app.cwd` | vitest root | |
 | `app.ready` | `{ path: "/" }` | Poll a path until it answers below 500, or `{ log: "listening" \| /regex/ }`. |
 | `app.readyTimeout` | `30000` | |
+| `db.engine` | `postgres`, or `mysql` for a `mysql://` URL | `postgres` or `mysql` (see [MySQL](#mysql)). |
 | `db.migrate` | none | `{ atlas: { dir } }`, `{ sql: "file-or-dir" }` or `{ command, inputs? }` (gets `DATABASE_URL`). |
 | `db.seed` | none | SQL file re-run after every reset. |
 | `db.schemas` | `["public"]` | Schemas whose tables are reset. |
 | `db.keep` | `[]` | Extra tables (`name` or `schema.name`) never truncated. |
 | `db.url` | `$SLICETEST_DATABASE_URL`, else a container | Use an existing Postgres server (e.g. a CI service container) instead of Testcontainers. |
-| `db.image` | `postgres:17-alpine` | |
+| `db.image` | `postgres:17-alpine` / `mysql:8.4` | |
 | `db.reuse` | on, unless `CI` is set or `db.url` is given | Keep the container between runs and cache the migrated template. The cache key is the migration files' contents; for `{ command }`, list what it reads in `inputs: ["prisma/migrations"]`, or it migrates every run. Databases left by killed runs are dropped after a day. Remove the container (`docker rm -f` / `podman rm -f`) to start clean. |
+| `containers` | `{}` | Dependencies as containers: `{ name: { image, port, env?, command?, ready?: { log }, reset? } }`. See [Containers](#containers-redis-search-s3-and-other-dependencies). |
 | `services` | `{}` | Other processes: `{ name: { command, env?, cwd?, ready?, readyTimeout? } }`. Without `ready` a service is not waited for. |
-| `stubs` | `[]` | Names of stubbed services, or `{ name, openapi }` to check calls and replies against the provider's spec. |
+| `stubs` | `[]` | Names of stubbed services, or `{ name, openapi?, autoReply?, upstream?, recordings? }`: check calls against the provider's spec, answer from it, or [replay recordings](#recording-a-real-service) of the real service. |
 | `openapi` | none | The app's OpenAPI 3 spec, or `{ spec, minCoverage }`. Every response must match it; the run ends with a coverage report. |
 | `http` | `{}` | Default `headers` / `query` for every request. |
 
@@ -393,6 +460,7 @@ scenarios:
 | `log: <regex>` | `from` (a service; default the app), `within` (ms, default 5000). Waits for a matching line printed during the scenario. |
 | `changes: { <table>: { inserted, updated, deleted } }` | Each is a count or a list of subset rows (`updated` matches the row after the update). Tables that aren't listed must be unchanged. |
 | `checkpoint: true` | Later `changes` steps only see what happens after this step. |
+| `snapshot: true` | The scenario's [trace](#snapshot-the-whole-scenario-trace) so far must match its stored snapshot. `mask: [keys]` hides more values. |
 
 `db`, `sql`, `received` and `changes` steps take `within: <ms>` to retry until they pass, for effects the app applies asynchronously.
 
@@ -422,6 +490,17 @@ npx slicetest polls -t voting # filter by file and scenario name
 npx slicetest --watch
 ```
 
+### Scenarios from your OpenAPI spec: `npx slicetest gen`
+
+```sh
+npx slicetest gen                 # uses `openapi` from slicetest.config.yaml, or --spec openapi.yaml
+npx slicetest gen --uncovered     # only the documented responses the last run didn't produce
+```
+
+writes `scenarios/<resource>.gen.scenario.yaml` with one scenario per documented response. Requests are built from the spec's examples and schemas. A path that needs an id gets a step that creates the resource first through the collection's `POST` and captures its id. A 404 on a made-up id and a 400/422 on an empty body are runnable as is; other responses are generated as `skip: true` scenarios marked TODO, so the skipped list in the test output is what's left to cover. Existing files are kept unless you pass `--force`.
+
+`--uncovered` reads the coverage the last run left in `node_modules/.cache/slicetest/`, which closes the loop: run, look at the ✗ in the coverage table, `gen --uncovered`, fill in the TODOs.
+
 ## Examples
 
 `examples/` has a Node app (`node:http` + `pg`) and a Python app (`http.server` + `psycopg`) with the same API. **The same scenario files (`polls.test.ts` and `polls.scenario.yaml`) run against both**:
@@ -431,6 +510,10 @@ npm test            # unit tests + both example apps
 npm run test:dist   # the built package, and the CLI with examples/slicetest.config.yaml
 ```
 
+## Using a coding agent
+
+[`.claude/skills/slicetest-write-tests`](.claude/skills/slicetest-write-tests/SKILL.md) teaches Claude Code (or any agent that reads skills) how to write slicetest scenarios. Copy it into your project's `.claude/skills/`. Contributors: see [`AGENTS.md`](AGENTS.md).
+
 ## Status
 
-Early. Postgres only. CI runs on Linux and Windows. Planned: MySQL.
+Early. Postgres and MySQL. CI runs on Linux and Windows.

package/dist/cli.js

@@ -12,22 +12,29 @@ import { parse } from "yaml";
 const CONFIG_NAMES = ["slicetest.config.yaml", "slicetest.config.yml", "slicetest.config.json"];
 const HELP = `Usage: slicetest [filters...] [options]
        slicetest init [--force]
+       slicetest gen [--spec <file>] [--out <dir>] [--uncovered] [--force]
 
 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.
 
 Options:
   -c, --config <file>  Config file (default: ${CONFIG_NAMES.join(" / ")} in the current directory)
   -w, --watch          Re-run on changes
   -t, --name <pattern> Only run scenarios whose name matches
-      --force          init: overwrite existing files
+      --spec <file>    gen: OpenAPI file (default: \`openapi\` from the config)
+      --out <dir>      gen: where to write scenarios (default: scenarios)
+      --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 }, seed, url, image, schemas, keep, reuse }
-  stubs:    [name | { name, openapi }]
+  db:       { migrate: { atlas: { dir } } | { sql } | { command, inputs }, engine, seed, url, image, schemas, keep, reuse }
+  stubs:    [name | { name, openapi, autoReply, upstream, recordings }]
   services: { name: { command, env, cwd, ready } }
+  containers: { name: { image, port, env, command, ready: { log }, reset } }
   openapi:  file | { spec, minCoverage }
   http:     { headers, query }
   include:  [globs]  default ["**/*.scenario.{yaml,yml}"]
@@ -42,6 +49,9 @@ export async function main(argv = process.argv.slice(2)) {
             name: { type: "string", short: "t" },
             help: { type: "boolean", short: "h" },
             force: { type: "boolean" },
+            spec: { type: "string" },
+            out: { type: "string" },
+            uncovered: { type: "boolean" },
         },
     });
     if (values.help) {
@@ -57,6 +67,22 @@ 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] === "gen") {
+        const configOpenapi = configPath && existsSync(configPath) ? (parse(await readFile(configPath, "utf8")) ?? {}).openapi : undefined;
+        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 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)`),
+        ];
+        process.stdout.write(`${lines.join("\n")}\n`);
+        return;
+    }
     if (!configPath || !existsSync(configPath)) {
         process.stderr.write(`slicetest: no config found. Run "npx slicetest init" to create ${CONFIG_NAMES[0]} (see --help).\n`);
         process.exitCode = 1;

package/dist/config.d.ts

@@ -8,11 +8,7 @@ export interface SlicetestOptions {
      * With `autoReply: true` as well, calls no route matches are answered from the spec (its examples, or values
      * built from its schemas) instead of failing, so you only register the routes a scenario cares about.
      */
-    stubs?: (string | {
-        name: string;
-        openapi?: string;
-        autoReply?: boolean;
-    })[];
+    stubs?: (string | StubOptions)[];
     /**
      * The app's own OpenAPI 3 spec (YAML or JSON, relative to the root). Every
      * response the app gives during a scenario must be documented and match its
@@ -34,6 +30,42 @@ export interface SlicetestOptions {
      * usable in `app.env` and in the env of services declared after them.
      */
     services?: Record<string, ServiceOptions>;
+    /**
+     * Containers the app depends on besides the database: Redis, Elasticsearch,
+     * MinIO, LocalStack. Each test file gets its own, reachable at
+     * `{{container.<name>}}` (`host:port`), `{{container.<name>.host}}` and
+     * `{{container.<name>.port}}`. `reset` runs inside it before every scenario.
+     */
+    containers?: Record<string, ContainerOptions>;
+}
+export interface ContainerOptions {
+    image: string;
+    /** The port the service listens on inside the container. */
+    port: number;
+    env?: Record<string, string>;
+    command?: string[];
+    /** Wait for this log line instead of the port accepting connections. */
+    ready?: {
+        log: string;
+    };
+    /** Command run inside the container before each scenario, e.g. `["redis-cli", "FLUSHALL"]`. */
+    reset?: string[];
+}
+export interface StubOptions {
+    name: string;
+    /** The provider's OpenAPI spec: the app's calls and the stub's replies are checked against it. */
+    openapi?: string;
+    /** Answer calls no route matches from the spec's examples or schemas. Needs `openapi`. */
+    autoReply?: boolean;
+    /**
+     * The real service's base URL, e.g. `https://api.github.com`. Calls no route
+     * matches are answered from `recordings`; run with `SLICETEST_RECORD=<name>`
+     * (or `=1` for every stub) to forward the ones without a recording to this
+     * URL and record the answers.
+     */
+    upstream?: string;
+    /** Recordings file, relative to the root. Default `recordings/<name>.yaml`. */
+    recordings?: string;
 }
 export interface ServiceOptions extends Omit<AppOptions, "ready"> {
     /** Default: no wait (for workers that don't listen). `{ path }` polls the service's own port. */
@@ -69,10 +101,15 @@ export interface AppOptions {
     readyTimeout?: number;
 }
 export interface DbOptions {
-    /** Postgres image used when no `url` is given. Default `postgres:17-alpine`. */
+    /**
+     * `postgres` (default) or `mysql`. Inferred from `url` when it starts with `mysql://`.
+     * MySQL needs the `mysql2` package, and `@testcontainers/mysql` unless `url` is given.
+     */
+    engine?: "postgres" | "mysql";
+    /** Image used when no `url` is given. Default `postgres:17-alpine`, or `mysql:8.4` for MySQL. */
     image?: string;
     /**
-     * Use an existing Postgres server instead of starting a container. Must point at a superuser-capable database.
+     * Use an existing server instead of starting a container. Must point at a superuser (root) connection.
      * Defaults to the `SLICETEST_DATABASE_URL` environment variable, which is handy in CI.
      */
     url?: string;
@@ -113,7 +150,8 @@ export interface ResolvedOptions {
         ready: ResolvedReady;
     };
     services: Record<string, ResolvedProcess>;
-    db: Required<Pick<DbOptions, "image" | "schemas" | "keep" | "reuse">> & Omit<DbOptions, "image" | "schemas" | "keep" | "reuse">;
+    containers: Record<string, ContainerOptions>;
+    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. */
     openapi: {
@@ -122,6 +160,12 @@ export interface ResolvedOptions {
         stubs: Record<string, string>;
         autoReply: string[];
     };
+    /** Stubs backed by recordings of a real service; `record` when SLICETEST_RECORD selects them. */
+    recordings: Record<string, {
+        file: string;
+        upstream: string;
+        record: boolean;
+    }>;
     http?: RequestOptions;
 }
 export declare function resolveOptions(opts: SlicetestOptions, root: string): ResolvedOptions;

package/dist/config.js

@@ -4,6 +4,7 @@ export function resolveOptions(opts, root) {
         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 ?? {},
         db: resolveDb(opts.db ?? {}),
         stubs: (opts.stubs ?? []).map(stubName),
         openapi: {
@@ -12,21 +13,39 @@ export function resolveOptions(opts, root) {
             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 ?? []),
         http: opts.http,
     };
 }
+function resolveRecordings(stubs) {
+    const withUpstream = stubs.filter((s) => typeof s === "object" && !!s.upstream);
+    const env = (process.env.SLICETEST_RECORD ?? "").trim();
+    const all = ["1", "true", "all", "*"].includes(env.toLowerCase());
+    const names = all || !env ? [] : env.split(",").map((n) => n.trim()).filter(Boolean);
+    for (const n of names) {
+        if (!withUpstream.some((s) => s.name === n)) {
+            throw new Error(`slicetest: SLICETEST_RECORD names "${n}", but no stub of that name has an upstream. Stubs with one: ${withUpstream.map((s) => s.name).join(", ") || "(none)"}`);
+        }
+    }
+    return Object.fromEntries(withUpstream.map((s) => [s.name, { file: s.recordings ?? `recordings/${s.name}.yaml`, upstream: s.upstream, record: all || names.includes(s.name) }]));
+}
 function resolveReady(ready) {
     if (!("log" in ready))
         return ready;
     return typeof ready.log === "string" ? { log: escapeRegExp(ready.log), flags: "" } : { log: ready.log.source, flags: ready.log.flags };
 }
 function resolveDb(db) {
-    const url = db.url ?? (process.env.SLICETEST_DATABASE_URL || undefined);
+    const isMysql = (u) => /^mysql:/i.test(u);
+    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);
     return {
-        image: "postgres:17-alpine",
+        image: engine === "mysql" ? "mysql:8.4" : "postgres:17-alpine",
         schemas: ["public"],
         keep: [],
         ...db,
+        engine,
         url,
         reuse: db.reuse ?? (!url && !process.env.CI),
     };
@@ -52,6 +71,22 @@ function validate(opts) {
             fail(`services.${name}.command is required`);
         checkReady(s.ready, `services.${name}`);
     }
+    for (const [name, c] of Object.entries(opts.containers ?? {})) {
+        if (!/^[\w-]+$/.test(name))
+            fail(`container name "${name}" may only contain letters, digits, "_" and "-"`);
+        if (!c || typeof c.image !== "string" || !c.image)
+            fail(`containers.${name}.image is required, e.g. "redis:7-alpine"`);
+        if (!Number.isInteger(c.port) || c.port <= 0)
+            fail(`containers.${name}.port must be the port the service listens on inside the container, e.g. 6379`);
+        for (const key of ["command", "reset"]) {
+            const v = c[key];
+            if (v !== undefined && !(Array.isArray(v) && v.length > 0 && v.every((x) => typeof x === "string")))
+                fail(`containers.${name}.${key} must be a list of strings, e.g. ["redis-cli", "FLUSHALL"]`);
+        }
+    }
+    const engine = opts.db?.engine;
+    if (engine !== undefined && engine !== "postgres" && engine !== "mysql")
+        fail(`db.engine must be "postgres" or "mysql", got ${JSON.stringify(engine)}`);
     const migrate = opts.db?.migrate;
     if (migrate) {
         const keys = Object.keys(migrate).filter((k) => ["atlas", "sql", "command"].includes(k));
@@ -72,6 +107,10 @@ function validate(opts) {
             fail(`each stub must be a name or { name, openapi }, got ${JSON.stringify(s)}`);
         if (typeof s === "object" && s.autoReply && !s.openapi)
             fail(`stub "${s.name}": autoReply needs an openapi spec to answer from`);
+        if (typeof s === "object" && s.upstream !== undefined && !/^https?:\/\/[^/]/.test(s.upstream))
+            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`);
     }
     const stubs = (opts.stubs ?? []).map(stubName);
     for (const name of stubs) {

package/dist/containers.d.ts

@@ -0,0 +1,22 @@
+import type { ContainerOptions } from "./config.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`.
+ */
+export declare class Dependency {
+    readonly name: string;
+    private readonly container;
+    private readonly opts;
+    private constructor();
+    static start(name: string, opts: ContainerOptions): Promise<Dependency>;
+    get host(): string;
+    /** The host port mapped to the container's `port`. */
+    get port(): number;
+    /** `host:port`, to put after a scheme: `redis://{{container.cache}}`. */
+    get address(): string;
+    /** Run a command inside the container; throws with its output unless it exits with 0. */
+    exec(command: string[]): Promise<string>;
+    /** Start of a scenario: run the `reset` command, if any. */
+    reset(): Promise<void>;
+    stop(): Promise<void>;
+}

package/dist/containers.js

@@ -0,0 +1,59 @@
+import { configureContainerRuntime } from "./container-runtime.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`.
+ */
+export class Dependency {
+    name;
+    container;
+    opts;
+    constructor(name, container, opts) {
+        this.name = name;
+        this.container = container;
+        this.opts = opts;
+    }
+    static async start(name, opts) {
+        configureContainerRuntime();
+        const { GenericContainer, Wait } = await import("testcontainers");
+        let definition = new GenericContainer(opts.image).withExposedPorts(opts.port);
+        if (opts.env)
+            definition = definition.withEnvironment(opts.env);
+        if (opts.command)
+            definition = definition.withCommand(opts.command);
+        if (opts.ready)
+            definition = definition.withWaitStrategy(Wait.forLogMessage(opts.ready.log));
+        try {
+            return new Dependency(name, await definition.start(), opts);
+        }
+        catch (e) {
+            throw new Error(`slicetest: container "${name}" (${opts.image}) didn't start: ${e.message}`);
+        }
+    }
+    get host() {
+        return this.container.getHost();
+    }
+    /** The host port mapped to the container's `port`. */
+    get port() {
+        return this.container.getMappedPort(this.opts.port);
+    }
+    /** `host:port`, to put after a scheme: `redis://{{container.cache}}`. */
+    get address() {
+        return `${this.host}:${this.port}`;
+    }
+    /** Run a command inside the container; throws with its output unless it exits with 0. */
+    async exec(command) {
+        const res = await this.container.exec(command);
+        if (res.exitCode !== 0) {
+            throw new Error(`slicetest: \`${command.join(" ")}\` in container "${this.name}" exited with ${res.exitCode}:\n${res.output.trim()}`);
+        }
+        return res.stdout;
+    }
+    /** Start of a scenario: run the `reset` command, if any. */
+    async reset() {
+        if (this.opts.reset)
+            await this.exec(this.opts.reset);
+    }
+    async stop() {
+        await this.container.stop();
+    }
+}

package/dist/drivers/index.d.ts

@@ -1,5 +1,5 @@
 import type { ResolvedOptions } from "../config.js";
 import type { Engine } from "./driver.js";
 export type { Admin, Driver, Engine, Row, Table } from "./driver.js";
-/** The database engine a run uses. */
-export declare function engineFor(_opts: Pick<ResolvedOptions, "db">): Engine;
+/** The database engine a run uses. MySQL's driver is an optional dependency, loaded only when asked for. */
+export declare function engineFor(opts: Pick<ResolvedOptions, "db">): Promise<Engine>;

package/dist/drivers/index.js

@@ -1,5 +1,14 @@
 import { postgres } from "./postgres.js";
-/** The database engine a run uses. */
-export function engineFor(_opts) {
+/** The database engine a run uses. MySQL's driver is an optional dependency, loaded only when asked for. */
+export async function engineFor(opts) {
+    if (opts.db.engine === "mysql") {
+        const mod = await import("./mysql.js").catch((e) => {
+            if (e.code === "ERR_MODULE_NOT_FOUND") {
+                throw new Error('slicetest: db.engine "mysql" needs the mysql2 package: npm i -D mysql2');
+            }
+            throw e;
+        });
+        return mod.mysqlEngine;
+    }
     return postgres;
 }

package/dist/drivers/mysql.d.ts

@@ -0,0 +1,29 @@
+import type { Driver, Engine, Row, Table } from "./driver.js";
+export declare class MysqlDriver implements Driver {
+    #private;
+    private readonly conn;
+    private constructor();
+    static connect(url: string): Promise<MysqlDriver>;
+    query<T extends Row = Row>(sql: string, params?: unknown[]): Promise<T[]>;
+    queryAll(sqls: string[]): Promise<Row[][]>;
+    exec(script: string): Promise<void>;
+    ident(name: string): string;
+    column(name: string): string;
+    param(_n: number): string;
+    inList(column: string, values: unknown[], params: unknown[]): string;
+    /**
+     * Base tables in the configured schemas. In MySQL a schema is a database;
+     * `public` (the default) stands for the database the URL points at.
+     */
+    listTables(schemas: string[], keep: string[]): Promise<Table[]>;
+    /**
+     * TRUNCATE also restarts AUTO_INCREMENT, but it is DDL and costs a few
+     * milliseconds per table, so only tables that have rows or a used counter are
+     * truncated. Foreign key checks are off for this session only.
+     */
+    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[]>;
+    close(): Promise<void>;
+}
+export declare const mysqlEngine: Engine;