slicetest 0.2.0 → 0.4.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, or SQLite) 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,21 @@ 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. A mail catcher there (Mailpit, MailHog, MailDev, smtp4dev, …) or a mail library in the dependencies turns on [`mail`](#mail-catch-what-the-app-sends). SQLite is picked up from Prisma's provider, Rails' `database.yml`, Django's settings or a SQLite driver, with `DATABASE_URL` in the form the framework reads (`file:…`, `sqlite3:…`). And third-party API URLs in `.env.example` (`STRIPE_API_BASE=https://api.stripe.com`) become stubs [recorded from that service](#recording-a-real-service), with the variable pointed at the stub, while local addresses, databases and your own URLs are left alone. 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.
+- **Record instead of write.** `npx slicetest record` puts a proxy in front of the app: click through a flow, press Enter, and get a replayable YAML scenario with the stubs' answers, the responses, captured ids and the database changes.
+- **Readable in CI.** On GitHub Actions, failing YAML steps are annotated in the pull request on the line that failed, and the job summary shows the OpenAPI coverage table.
+- **Races on purpose.** `http.concurrently(10, ...)` and `toHaveStatuses({ 201: 1, 409: 9 })` turn "what if two people click at once" into a test against the real database.
+- **Mail as a fourth boundary.** `mail: true` catches the app's SMTP traffic in-process, decoded, with the links pulled out, so a sign-up test can follow the confirmation link.
+- **Postgres, MySQL or SQLite**, with the same scenarios and the same helpers on all three, 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
@@ -54,7 +61,30 @@ npx slicetest        # starts Postgres, migrates, starts your app, runs scenario
 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.
+You also need Docker or Podman (`npx slicetest doctor` checks). 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.
+
+### SQLite
+
+Set `db: { engine: "sqlite" }`. There's nothing to install and no container: slicetest uses Node's built-in `node:sqlite` (Node.js 22.5 or later), creates the database files in a temporary directory, migrates a template once and gives each worker a copy (`VACUUM INTO`). Point the app at the file:
+
+```ts
+slicetest({
+  app: { command: "python app.py", env: { PORT: "{{app.port}}", DATABASE_PATH: "{{db.path}}" } },
+  db: { engine: "sqlite", migrate: { sql: "schema.sql" } },
+});
+```
+
+`{{db.url}}` is `sqlite:///absolute/path.db` (the form SQLAlchemy, dj-database-url and many others read) and `{{db.path}}` the plain path. The files are in WAL mode, so the app keeps its connection while slicetest resets tables between scenarios (`DELETE` plus resetting `AUTOINCREMENT` counters, foreign keys off for that moment only). `db.changes()`, `trace()` and every other helper work the same; SQLite has no boolean type, so booleans you insert are stored and read back as `1` / `0`. Migrations with `sql`, `command` or Atlas (`sqlite://` URLs). `db.url`, `db.image` and `SLICETEST_DATABASE_URL` don't apply. With the default `reuse`, the migrated template stays in the system temp directory between runs.
 
 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`.
 
@@ -246,12 +276,31 @@ 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:
 
 ```ts
 expect(res).toHaveStatus(201);                                   // failure shows the response body
+expect(responses).toHaveStatuses({ 201: 1, 409: 9 });            // an array, e.g. from http.concurrently()
 expect(stub("slack")).toHaveReceived("POST", "/hook", { json: { text: "hi" } });
 expect(stub("slack")).toHaveReceivedTimes(1, "POST", "/hook");
 expect(stub("mail")).not.toHaveReceived("POST", "/send");
@@ -291,6 +340,55 @@ 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.
+
+### Races: many requests at once
+
+Double bookings, lost updates and duplicate charges only show up when requests overlap. `http.concurrently(n, send)` prepares `n` requests and releases them together, against the real database, and `toHaveStatuses` checks how they were answered:
+
+```ts
+scenario("ten people booking the same seat: one gets it", async ({ http, db }) => {
+  const responses = await http.concurrently(10, () => http.post("/bookings", { seat: 7 }));
+  expect(responses).toHaveStatuses({ 201: 1, 409: 9 });
+  await expect(db).toHaveRow("bookings", { seat: 7 }, 1);
+});
+```
+
+`send` gets the request's index, for variations. When the counts are off, the failure shows one response per status. In YAML, `concurrency: 10` on a `request` step does the same, with `expect: { statuses: { 201: 1, 409: 9 } }`.
+
+### Mail: catch what the app sends
+
+`mail: true` starts an SMTP server for the app to send to (plain SMTP, no TLS, any username and password accepted). Point the app's mail settings at it, and read what arrived in the scenario, already decoded (encoded subjects, quoted-printable and base64 parts, multipart text and HTML):
+
+```ts
+slicetest({
+  mail: true,
+  app: { command: "node server.js", env: { SMTP_HOST: "{{mail.host}}", SMTP_PORT: "{{mail.port}}" } },
+});
+
+scenario("sign-up sends a confirmation link that works", async ({ http, mail }) => {
+  await http.post("/signup", { json: { email: "alice@example.com" } });
+  const message = await mail.waitFor({ to: "alice@example.com", subject: "Confirm" });
+  expect((await http.get(message.links[0]!)).status).toBe(200);
+});
+```
+
+`mail.messages(filter?)`, `mail.last(filter?)` and `mail.waitFor(filter?, { within })` take `{ to, from, subject, text, html }`: addresses match exactly, other strings as substrings, and RegExps test the value. Each message has `from`, `to` (the envelope, so Cc and Bcc too), `subject`, `text`, `html`, `headers`, `links` and `raw`. The mailbox is emptied before each scenario, what was sent shows up in the failure output and in `trace()`, and `{{mail.url}}` is `smtp://host:port` for libraries that take a URL. No container is involved, so it works the same for apps in any language and on Windows.
+
 ### 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 +400,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 +440,18 @@ 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`, `mysql` (see [MySQL](#mysql)) or `sqlite` (see [SQLite](#sqlite)). |
 | `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). |
+| `mail` | `false` | Start an SMTP server at `{{mail.host}}` / `{{mail.port}}` and collect the app's mail. See [Mail](#mail-catch-what-the-app-sends). |
 | `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. |
 
@@ -385,7 +504,7 @@ scenarios:
 | Step | Keys |
 |---|---|
 | `stub: <name>` | `on: METHOD /path` (`:params` allowed), `when: { query, headers, json, body }`, one of `reply: { status, headers, body }` / `sequence: [...]` / `networkError: true`, plus `times`, `delay`. Replies may echo the call: `{{call.params.id}}`, `{{call.json.name}}`. |
-| `request: METHOD /path` | `headers`, `query`, one of `json` / `form` / `body`, `follow`, `expect: { status, headers, json, text }`, `capture` |
+| `request: METHOD /path` | `headers`, `query`, one of `json` / `form` / `body`, `follow`, `expect: { status, headers, json, text }`, `capture`. `concurrency: n` sends it `n` times at once; `expect` then applies to each response, and `expect.statuses: { 201: 1, 409: 9 }` counts them. |
 | `insert: <table>` | `rows`, `capture` (from `row` / `rows`) |
 | `db: <table>` | `where`, `orderBy`, `expect: { rows, count }`, `capture` |
 | `sql: <query>` | `params`, `expect: { rows, count }`, `capture` |
@@ -393,9 +512,12 @@ 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. |
+| `mail: { to, from, subject, text, html }` | `times` (exact; default at least one), `within` (ms, default 5000), `capture` from the last match (`subject`, `text`, `links.0`). Waits for mail the app sends. `{}` matches any message. |
+| `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.
 
+- `request:` also takes a captured URL of the app, e.g. `GET {{link}}` after capturing a link from a mail.
 - `{{name}}` inserts a captured value or an `each` field. A string that is only `{{name}}` keeps the value's type, so `id: "{{pollId}}"` compares as a number.
 - Expected `json`, `rows` and `headers` are subsets: extra keys are fine. `{ $type: number }`, `{ $regex: "^ch_" }`, `{ $contains: "..." }` and `{ $any: true }` match loosely.
 - A file-level `setup:` list runs at the start of every scenario. `skip`, `only` and `timeout` work per scenario.
@@ -422,6 +544,59 @@ 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.
+
+### Record a scenario by using the app: `npx slicetest record`
+
+The fastest way to a first scenario is to do the thing once. `record` starts the database, the stubs and the app exactly as a test run would, plus a proxy in front of the app:
+
+```
+$ npx slicetest record
+Recording. Use the app through http://127.0.0.1:52301 (it forwards to http://127.0.0.1:52288).
+Everything it does is captured: responses, calls to stubs, database changes.
+Press Enter (or Ctrl+C) to finish and write the scenario.
+
+Wrote scenarios/recorded-20261001-091500.scenario.yaml: 3 request(s), 1 stub route(s), changes in polls, votes.
+Replay it with: npx slicetest scenarios/recorded-20261001-091500.scenario.yaml
+```
+
+Point a browser, curl, Postman or a mobile build at the proxy URL and go through the flow. The scenario it writes has:
+
+- a `stub` step for every answer a stubbed service gave (from `autoReply`, or a real service with `upstream` and `SLICETEST_RECORD`), so the replay needs neither;
+- a `request` step per request with the status and body to expect, where dates and UUIDs only have to be strings, and a `capture` for any value that a later request reuses (`POST /orders` → `GET /orders/{{id}}`);
+- `received` steps for the calls the app made to stubs, and a closing `changes` step with the rows written per table.
+
+Requests for scripts, styles and images are left out. The file starts with a comment of what to review: it is a starting point, and the assertions that matter to you are yours to tighten. `--out` names the file, `--port` fixes the proxy's port.
+
+### On GitHub Actions
+
+Nothing to configure. When `GITHUB_ACTIONS` is set, a failing YAML step is annotated on its own line of the `.scenario.yaml` file in the pull request (Vitest already does this for TypeScript tests), and the job summary gets a table of the failed steps and the OpenAPI coverage table, with ✅ / ❌ per documented response. A coverage below `minCoverage` is annotated on the spec file.
+
+### Is everything in place? `npx slicetest doctor`
+
+Checks what a run needs before it starts, instead of failing with a timeout halfway: the config, the container runtime (or the database server at `db.url` / `SLICETEST_DATABASE_URL`, with the password hidden), the migrations, seed and working directories, the `atlas` CLI, `mysql2` for MySQL, the programs the app and services start, the OpenAPI files and missing recordings. Each problem says what to do, and the exit code is 1 when something must be fixed, so it also works as the first step of a CI job.
+
+```
+  ✓ Node.js 24.13.0
+  ✓ config slicetest.config.yaml
+  ✗ no container runtime
+      Could not find a working container runtime strategy. Start Docker or a Podman machine (`podman machine start`), or set SLICETEST_DATABASE_URL / db.url to an existing database server
+  ✓ migrations migrations
+  ! stub github: no recordings yet (recordings/github.yaml)
+      run once with SLICETEST_RECORD=github to record https://api.github.com
+
+1 problem(s) to fix before running.
+```
+
 ## 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 +606,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/ci.d.ts

@@ -0,0 +1,29 @@
+/**
+ * GitHub Actions output. Vitest already annotates failing TypeScript tests;
+ * YAML scenarios fail inside slicetest's runtime, so their annotations point at
+ * the `.scenario.yaml` line here instead. The OpenAPI coverage table also goes
+ * to the job summary.
+ */
+export declare const onGitHub: (env?: NodeJS.ProcessEnv) => boolean;
+export interface YamlFailure {
+    /** Absolute path of the scenario file. */
+    file: string;
+    line: number;
+    scenario: string;
+    step: string;
+    message: string;
+}
+/** `::error file=…,line=…,title=…::message`, escaped as the runner expects. */
+export declare function annotation(level: "error" | "warning", message: string, props?: {
+    file?: string;
+    line?: number;
+    title?: string;
+}): string;
+/** Paths in annotations are relative to the repository checkout. */
+export declare function repoPath(file: string, env?: NodeJS.ProcessEnv): string;
+/** Called in a worker: one JSON line per failed YAML step, printed by the main process at the end. */
+export declare function recordYamlFailure(dir: string, failure: YamlFailure): Promise<void>;
+export declare function yamlFailures(dir: string): Promise<YamlFailure[]>;
+export declare function failureAnnotations(failures: YamlFailure[], env?: NodeJS.ProcessEnv): string[];
+export declare function failureSummary(failures: YamlFailure[], env?: NodeJS.ProcessEnv): string;
+export declare function appendSummary(markdown: string, env?: NodeJS.ProcessEnv): Promise<void>;

package/dist/ci.js

@@ -0,0 +1,57 @@
+import { appendFile, readdir, readFile } from "node:fs/promises";
+import path from "node:path";
+/**
+ * GitHub Actions output. Vitest already annotates failing TypeScript tests;
+ * YAML scenarios fail inside slicetest's runtime, so their annotations point at
+ * the `.scenario.yaml` line here instead. The OpenAPI coverage table also goes
+ * to the job summary.
+ */
+export const onGitHub = (env = process.env) => env.GITHUB_ACTIONS === "true";
+/** `::error file=…,line=…,title=…::message`, escaped as the runner expects. */
+export function annotation(level, message, props = {}) {
+    const prop = (v) => v.replace(/%/g, "%25").replace(/\r/g, "%0D").replace(/\n/g, "%0A").replace(/:/g, "%3A").replace(/,/g, "%2C");
+    const data = message.replace(/%/g, "%25").replace(/\r/g, "%0D").replace(/\n/g, "%0A");
+    const list = Object.entries(props)
+        .filter(([, v]) => v !== undefined && v !== "")
+        .map(([k, v]) => `${k}=${prop(String(v))}`)
+        .join(",");
+    return `::${level}${list ? ` ${list}` : ""}::${data}`;
+}
+/** Paths in annotations are relative to the repository checkout. */
+export function repoPath(file, env = process.env) {
+    return path.relative(env.GITHUB_WORKSPACE ?? process.cwd(), file).replace(/\\/g, "/");
+}
+/** Called in a worker: one JSON line per failed YAML step, printed by the main process at the end. */
+export async function recordYamlFailure(dir, failure) {
+    await appendFile(path.join(dir, `${process.pid}.jsonl`), `${JSON.stringify(failure)}\n`);
+}
+export async function yamlFailures(dir) {
+    const out = [];
+    for (const f of await readdir(dir).catch(() => [])) {
+        for (const line of (await readFile(path.join(dir, f), "utf8")).split("\n"))
+            if (line)
+                out.push(JSON.parse(line));
+    }
+    return out;
+}
+export function failureAnnotations(failures, env = process.env) {
+    return failures.map((f) => annotation("error", f.message, { file: repoPath(f.file, env), line: f.line, title: `${f.scenario}: ${f.step}` }));
+}
+export function failureSummary(failures, env = process.env) {
+    if (failures.length === 0)
+        return "";
+    const cell = (s) => s.replace(/\|/g, "\\|").replace(/\r?\n/g, "<br>");
+    return [
+        `### slicetest: ${failures.length} failed YAML step(s)`,
+        "",
+        "| Where | Scenario | Step | Error |",
+        "|---|---|---|---|",
+        ...failures.map((f) => `| \`${repoPath(f.file, env)}:${f.line}\` | ${cell(f.scenario)} | ${cell(f.step)} | ${cell(f.message.split("\n")[0].slice(0, 300))} |`),
+        "",
+    ].join("\n");
+}
+export async function appendSummary(markdown, env = process.env) {
+    if (!markdown || !env.GITHUB_STEP_SUMMARY)
+        return;
+    await appendFile(env.GITHUB_STEP_SUMMARY, `${markdown}\n`).catch(() => { });
+}

package/dist/cli.js

@@ -12,22 +12,38 @@ 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]
+       slicetest doctor [--config <file>]
+       slicetest record [--out <file>] [--port <n>]
 
 Runs *.scenario.yaml files against your app, as configured in slicetest.config.yaml.
 \`slicetest init\` looks at the project and writes a starting config and scenario.
+\`slicetest gen\` writes scenario skeletons for the documented responses of the
+app's OpenAPI spec; with --uncovered, only for those the last run didn't produce.
+\`slicetest doctor\` checks the config, the container runtime or database server,
+migrations, commands and spec files, and says what to fix.
+\`slicetest record\` starts everything and a proxy in front of the app: use the app
+through it (a browser, curl), press Enter, and get the session as a YAML scenario.
 
 Options:
   -c, --config <file>  Config file (default: ${CONFIG_NAMES.join(" / ")} in the current directory)
   -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)
+                       record: the scenario file (default: scenarios/recorded-<time>.scenario.yaml)
+      --port <n>       record: the proxy's port (default: any free port)
+      --uncovered      gen: only responses the last run didn't cover
+      --force          init, gen: overwrite existing files
   -h, --help           Show this help
 
 Config (paths are relative to the config file):
   app:      { command, env, cwd, ready: { path } | { log }, readyTimeout }
-  db:       { migrate: { atlas: { dir } } | { sql } | { command, inputs }, 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 } }
+  mail:     true    SMTP server at {{mail.host}} / {{mail.port}}
   openapi:  file | { spec, minCoverage }
   http:     { headers, query }
   include:  [globs]  default ["**/*.scenario.{yaml,yml}"]
@@ -42,6 +58,10 @@ 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" },
+            port: { type: "string" },
         },
     });
     if (values.help) {
@@ -57,12 +77,41 @@ export async function main(argv = process.argv.slice(2)) {
     const configPath = values.config
         ? path.resolve(values.config)
         : CONFIG_NAMES.map((n) => path.resolve(n)).find((p) => existsSync(p));
+    if (positionals[0] === "doctor") {
+        const { doctor, formatChecks } = await import("./doctor.js");
+        const checks = await doctor(configPath);
+        process.stdout.write(formatChecks(checks));
+        if (checks.some((c) => c.status === "fail"))
+            process.exitCode = 1;
+        return;
+    }
+    if (positionals[0] === "gen") {
+        const configOpenapi = configPath && existsSync(configPath) ? (parse(await readFile(configPath, "utf8")) ?? {}).openapi : undefined;
+        const 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;
         return;
     }
     const { include, ...options } = (parse(await readFile(configPath, "utf8")) ?? {});
+    if (positionals[0] === "record") {
+        const { record } = await import("./record-cli.js");
+        await record(configPath, options, { out: values.out, port: values.port ? Number(values.port) : 0 });
+        return;
+    }
     const { startVitest } = await import("vitest/node");
     const { slicetest, YAML_SCENARIOS } = await import("./vitest.js");
     const vitest = await startVitest(positionals, {

package/dist/config.d.ts

@@ -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,48 @@ 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>;
+    /**
+     * Catch the mail the app sends. An SMTP server (no TLS, any credentials)
+     * listens at `{{mail.host}}` / `{{mail.port}}` (`{{mail.url}}` is `smtp://host:port`);
+     * scenarios read what arrived with `mail.messages()` / `mail.waitFor()`.
+     */
+    mail?: boolean;
+}
+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 +107,17 @@ export interface AppOptions {
     readyTimeout?: number;
 }
 export interface DbOptions {
-    /** Postgres image used when no `url` is given. Default `postgres:17-alpine`. */
+    /**
+     * `postgres` (default), `mysql` or `sqlite`. Inferred from `url` when it starts with `mysql://`.
+     * MySQL needs the `mysql2` package, and `@testcontainers/mysql` unless `url` is given.
+     * SQLite needs Node.js 22.5+ and nothing else: no server, no container. The app gets
+     * `{{db.url}}` as `sqlite:///path/to/file.db` and `{{db.path}}` as the file path.
+     */
+    engine?: "postgres" | "mysql" | "sqlite";
+    /** 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 +158,9 @@ 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>;
+    mail: boolean;
+    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 +169,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;