slicetest 0.3.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 (or MySQL) 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,7 +38,7 @@ 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`. 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.
+`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
 
@@ -48,7 +48,11 @@ npx slicetest        # starts Postgres, migrates, starts your app, runs scenario
 - **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.
+- **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
@@ -57,7 +61,7 @@ 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
 
@@ -69,6 +73,19 @@ npm i -D mysql2 @testcontainers/mysql   # the second is only needed without db.u
 
 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`.
 
 ## Configure
@@ -283,6 +300,7 @@ 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");
@@ -338,6 +356,39 @@ slicetest({
 
 `{{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:
@@ -389,7 +440,7 @@ 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.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. |
@@ -398,6 +449,7 @@ Scenarios in one file share an app and a database, so they always run one at a t
 | `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?, 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. |
@@ -452,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` |
@@ -460,10 +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.
@@ -501,6 +555,48 @@ writes `scenarios/<resource>.gen.scenario.yaml` with one scenario per documented
 
 `--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**:

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

@@ -13,11 +13,17 @@ const CONFIG_NAMES = ["slicetest.config.yaml", "slicetest.config.yml", "slicetes
 const HELP = `Usage: slicetest [filters...] [options]
        slicetest init [--force]
        slicetest gen [--spec <file>] [--out <dir>] [--uncovered] [--force]
+       slicetest doctor [--config <file>]
+       slicetest record [--out <file>] [--port <n>]
 
 Runs *.scenario.yaml files against your app, as configured in slicetest.config.yaml.
 \`slicetest init\` looks at the project and writes a starting config and scenario.
 \`slicetest gen\` writes scenario skeletons for the documented responses of the
 app's OpenAPI spec; with --uncovered, only for those the last run didn't produce.
+\`slicetest doctor\` checks the config, the container runtime or database server,
+migrations, commands and spec files, and says what to fix.
+\`slicetest record\` starts everything and a proxy in front of the app: use the app
+through it (a browser, curl), press Enter, and get the session as a YAML scenario.
 
 Options:
   -c, --config <file>  Config file (default: ${CONFIG_NAMES.join(" / ")} in the current directory)
@@ -25,6 +31,8 @@ Options:
   -t, --name <pattern> Only run scenarios whose name matches
       --spec <file>    gen: OpenAPI file (default: \`openapi\` from the config)
       --out <dir>      gen: where to write scenarios (default: scenarios)
+                       record: the scenario file (default: scenarios/recorded-<time>.scenario.yaml)
+      --port <n>       record: the proxy's port (default: any free port)
       --uncovered      gen: only responses the last run didn't cover
       --force          init, gen: overwrite existing files
   -h, --help           Show this help
@@ -35,6 +43,7 @@ Config (paths are relative to the config file):
   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}"]
@@ -52,6 +61,7 @@ export async function main(argv = process.argv.slice(2)) {
             spec: { type: "string" },
             out: { type: "string" },
             uncovered: { type: "boolean" },
+            port: { type: "string" },
         },
     });
     if (values.help) {
@@ -67,6 +77,14 @@ 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);
@@ -89,6 +107,11 @@ export async function main(argv = process.argv.slice(2)) {
         return;
     }
     const { include, ...options } = (parse(await readFile(configPath, "utf8")) ?? {});
+    if (positionals[0] === "record") {
+        const { record } = await import("./record-cli.js");
+        await record(configPath, options, { out: values.out, port: values.port ? Number(values.port) : 0 });
+        return;
+    }
     const { startVitest } = await import("vitest/node");
     const { slicetest, YAML_SCENARIOS } = await import("./vitest.js");
     const vitest = await startVitest(positionals, {

package/dist/config.d.ts

@@ -37,6 +37,12 @@ export interface SlicetestOptions {
      * `{{container.<name>.port}}`. `reset` runs inside it before every scenario.
      */
     containers?: Record<string, ContainerOptions>;
+    /**
+     * Catch the mail the app sends. An SMTP server (no TLS, any credentials)
+     * listens at `{{mail.host}}` / `{{mail.port}}` (`{{mail.url}}` is `smtp://host:port`);
+     * scenarios read what arrived with `mail.messages()` / `mail.waitFor()`.
+     */
+    mail?: boolean;
 }
 export interface ContainerOptions {
     image: string;
@@ -102,10 +108,12 @@ export interface AppOptions {
 }
 export interface DbOptions {
     /**
-     * `postgres` (default) or `mysql`. Inferred from `url` when it starts with `mysql://`.
+     * `postgres` (default), `mysql` or `sqlite`. Inferred from `url` when it starts with `mysql://`.
      * MySQL needs the `mysql2` package, and `@testcontainers/mysql` unless `url` is given.
+     * SQLite needs Node.js 22.5+ and nothing else: no server, no container. The app gets
+     * `{{db.url}}` as `sqlite:///path/to/file.db` and `{{db.path}}` as the file path.
      */
-    engine?: "postgres" | "mysql";
+    engine?: "postgres" | "mysql" | "sqlite";
     /** Image used when no `url` is given. Default `postgres:17-alpine`, or `mysql:8.4` for MySQL. */
     image?: string;
     /**
@@ -151,6 +159,7 @@ export interface ResolvedOptions {
     };
     services: Record<string, ResolvedProcess>;
     containers: Record<string, ContainerOptions>;
+    mail: boolean;
     db: Required<Pick<DbOptions, "engine" | "image" | "schemas" | "keep" | "reuse">> & Omit<DbOptions, "engine" | "image" | "schemas" | "keep" | "reuse">;
     stubs: string[];
     /** Spec files, resolved against the root: the app's, and per stub name. */

package/dist/config.js

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

package/dist/doctor.d.ts

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

package/dist/doctor.js

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