slicetest 0.3.0 → 0.5.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. Token issuer settings there (`OIDC_ISSUER`, `AUTH0_DOMAIN`, `JWKS_URL`, `JWT_AUDIENCE`, …) turn on [`auth`](#auth-a-real-openid-issuer-tokens-with-any-claims) and point at slicetest's issuer instead of becoming stubs. 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,15 @@ 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.
+- **Real token verification, any user.** `auth: true` gives the app an OpenID issuer with a JWKS, so JWT checks stay on in tests, and scenarios mint tokens with any claims, including expired or foreign-signed ones.
+- **Webhooks signed like the real sender.** Stripe, GitHub, Slack, Shopify and Standard Webhooks signatures, plus forged and replayed deliveries, so signature checks are tested instead of bypassed.
+- **Reproducible chaos.** Stubs can fail the first calls, drop connections or add latency, from a seed the failure output prints, so a resilience test that fails once fails again on demand.
+- **N+1 detection for any stack.** A wire-protocol proxy records the SQL the app runs, so query counts are asserted at the HTTP boundary, whatever the ORM or language.
+- **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 +65,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 +77,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
@@ -170,6 +191,18 @@ await db.query("UPDATE users SET name = $1", ["b"]);
 
 In `where`, `null` means `IS NULL` and an array means `IN (...)`.
 
+#### `db.make()` — rows from the schema, not from fixtures
+
+Give only the columns the scenario is about. slicetest reads the table's definition and fills in the rest: a value of each required column's type, the first allowed value for enums and `CHECK (status IN (...))`, and a parent row for every required foreign key, made the same way.
+
+```ts
+const order = await db.make("orders", { status: "paid" });   // also creates the customer and the product it references
+await db.makeMany("votes", 3, { poll_id: order.poll_id });
+await db.makeMany("users", 2, (i) => ({ name: `user ${i}` }));
+```
+
+Generated values are numbered per scenario (`title-1`, `orders-2@example.test`, UUIDs, dates from 2026-01-01), so they are unique and identical on every run, which keeps `trace()` snapshots stable. Works the same on Postgres, MySQL and SQLite. When a column needs a value slicetest can't guess (a custom type, a check it can't satisfy), the error names the column to pass.
+
 #### `db.changes()` — assert on everything the app wrote
 
 Instead of guessing which tables to query, ask for the diff. Rows are matched by primary key, so updates show which columns changed:
@@ -188,6 +221,26 @@ expect(await db.changes()).toEqual({
 
 `toEqual` fails if the app wrote to a table you didn't list, which catches unexpected side effects. Each entry in `updated` has `key`, `before`, `after` and `changed`. Tables without a primary key report an update as one deleted row plus one inserted row. `bigint` columns (bigserial ids, `count(*)`) come back as numbers when they fit safely.
 
+#### `db.queries()` — the SQL the app ran, from any language
+
+With `db: { queries: true }`, the app's `{{db.url}}` points at a proxy that reads the Postgres or MySQL wire protocol and records every statement the app runs. Nothing changes in the app, and it works the same for an ORM in Node, Python, Ruby, Go or Java. So you can pin down N+1 queries and query counts at the HTTP boundary:
+
+```ts
+const queries = await db.queries(() => http.get("/posts"));   // only what ran during the request
+expect(queries.repeated()).toEqual([]);                         // no statement shape ran 3+ times
+expect(queries.withoutTransactions()).toHaveLength(2);          // ignore BEGIN / COMMIT that some drivers add
+```
+
+`repeated(min = 3)` and `shapes()` group statements by shape, with literals and parameters replaced by `?`. `db.queries()` without a function returns the whole scenario so far. The test's own `db` calls aren't included. When a scenario fails, the output lists the SQL the app ran, most frequent first, so an N+1 stands out:
+
+```
+SQL the app ran during this scenario (21 statements, most frequent first):
+  ×20 SELECT * FROM authors WHERE id = ?
+  SELECT * FROM posts ORDER BY id
+```
+
+YAML: `expect: { queries: 3 }` on a `request` step fails if the request ran more than 3 statements (not counting transaction control). Connections that switch to TLS are forwarded but not read. SQLite apps open the file directly, so this isn't available for them.
+
 ### `stub(name)` — fake the services the app calls
 
 ```ts
@@ -259,6 +312,21 @@ 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`.
 
+#### Chaos: faults the app must survive
+
+`chaos()` makes a stub misbehave for the rest of the scenario, to test retries, timeouts and fallbacks against the app's real HTTP client:
+
+```ts
+stub("payments").on("POST", "/charges").once().reply(201, { id: "ch_1" });
+stub("payments").chaos({ failFirst: 2, statuses: [503] });   // 503, 503, then the real answer
+await http.post("/orders", { ... });
+expect(stub("payments")).toHaveReceivedTimes(3, "POST", "/charges");
+
+stub("search").chaos({ errorRate: 0.3, networkErrorRate: 0.1, latency: [50, 300] });
+```
+
+Faulted calls don't use up `once()` / `times()` routes, so a retry gets the answer you registered. 429 and 503 come with `Retry-After: 1`. Random faults are drawn from a seeded generator: a failing scenario prints `chaos on search: …; 4 of 12 calls faulted. Replay with SLICETEST_CHAOS_SEED=1840211`, and running with that variable gives the same faults. `stub.faults()` lists the calls that faulted. YAML: `- chaos: payments` with `failFirst`, `errorRate`, `statuses`, `networkErrorRate`, `latency` and `seed`.
+
 ### 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:
@@ -283,6 +351,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 +407,88 @@ 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.
+
+### Auth: a real OpenID issuer, tokens with any claims
+
+Apps that verify JWTs are hard to test from the outside: you either disable verification in tests or copy a production token. With `auth: true`, slicetest runs an OpenID Connect issuer for the app, with a discovery document, a JWKS and RS256 keys made for the run, so the app verifies tokens exactly as it does in production. The scenario mints whatever user it needs.
+
+```ts
+slicetest({
+  auth: { audience: "api://orders", claims: { tenant: "acme" } },   // or just `auth: true`
+  app: { command: "...", env: { OIDC_ISSUER: "{{auth.issuer}}", JWKS_URL: "{{auth.jwks}}", OIDC_AUDIENCE: "{{auth.audience}}" } },
+});
+
+scenario("admins can delete orders", async ({ http, auth }) => {
+  const res = await http.delete("/orders/1", { headers: auth.header({ sub: "alice", roles: ["admin"] }) });
+  expect(res).toHaveStatus(204);
+});
+
+scenario("the app rejects tokens it must not trust", async ({ http, auth }) => {
+  for (const opts of [{ expired: true }, { wrongKey: true }, { audience: "api://other" }, { issuer: "https://evil.example" }]) {
+    expect(await http.get("/orders", { headers: auth.header({}, opts) })).toHaveStatus(401);
+  }
+});
+```
+
+`auth.token(claims, opts)` returns the JWT itself. Tokens get `iss`, `aud`, `sub: "user-1"`, `iat`, `nbf`, `exp` (1 hour, or `expiresIn`) and the configured `claims`, all overridable. `auth.rotate()` switches to a new signing key, to check that the app refetches the JWKS. Apps that fetch tokens themselves can use `POST {{auth.issuer}}/token` with the client-credentials grant: `sub` is the client id, and `scope` and `audience` are carried over. No dependencies: keys and signatures come from `node:crypto`.
+
+In YAML, `auth` on a `request` step sends `Authorization: Bearer` with those claims (`auth: true` for the defaults):
+
+```yaml
+- request: GET /me
+  auth: { sub: alice, roles: [admin] }
+  expect: { status: 200 }
+```
+
+### Webhooks: deliveries signed like the provider's
+
+`http.webhook()` posts a payload the way Stripe, GitHub, Slack, Shopify or any [Standard Webhooks](https://www.standardwebhooks.com/) sender (Svix, Resend, Clerk, …) delivers it, signed with the secret the app is configured with, so the app's real verification code runs. The signatures are checked against the providers' documented examples.
+
+```ts
+const stripe = { provider: "stripe", secret: "whsec_test" } as const;   // the same secret as in app.env
+
+await http.webhook("/webhooks/stripe", { type: "invoice.paid", data: { object: { id: "in_1" } } }, stripe);
+await http.webhook("/webhooks/github", { action: "opened" }, { provider: "github", secret: "s", event: "pull_request" });
+
+// Deliveries the app must refuse:
+expect(await http.webhook("/webhooks/stripe", event, { ...stripe, invalidSignature: true })).toHaveStatus(400);
+expect(await http.webhook("/webhooks/stripe", event, { ...stripe, stale: true })).toHaveStatus(400);   // signed 10 minutes ago
+```
+
+Objects are sent as JSON, `URLSearchParams` as a form (Slack slash commands), strings as they are. Other HMAC schemes: `provider: { header: "X-Signature", prefix: "sha256=", encoding: "hex" }`. `signWebhook(body, opts)` returns just the headers. In YAML, add `webhook: { provider, secret, event, stale, invalidSignature }` to a `request` step; its `json`, `form` or `body` is what gets signed.
+
 ### 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,15 +540,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` 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. |
 | `db.keep` | `[]` | Extra tables (`name` or `schema.name`) never truncated. |
+| `db.queries` | `false` | Point the app at a proxy that records its SQL (Postgres, MySQL), for [`db.queries()`](#dbqueries--the-sql-the-app-ran-from-any-language). |
 | `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` / `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). |
+| `auth` | `false` | `true` or `{ audience, claims }`: an OpenID Connect issuer at `{{auth.issuer}}` (JWKS at `{{auth.jwks}}`) whose tokens scenarios mint with `auth.token()`. See [Auth](#auth-a-real-openid-issuer-tokens-with-any-claims). |
 | `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,18 +606,24 @@ 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`) |
+| `request` with `auth` | `auth: true` or the claims: sends a bearer token from the `auth` issuer |
+| `request` with `webhook` | `{ provider, secret, event, stale, invalidSignature }`: signs the body like that provider's deliveries |
+| `chaos: <stub>` | `failFirst`, `errorRate`, `statuses`, `networkErrorRate`, `latency`, `seed` — like `stub(name).chaos()` |
+| `make: <table>` | `rows` (a mapping, or a list for several rows), `count`, `capture` (from `row` / `rows`) — like `db.make()` |
 | `db: <table>` | `where`, `orderBy`, `expect: { rows, count }`, `capture` |
 | `sql: <query>` | `params`, `expect: { rows, count }`, `capture` |
 | `received: <stub>` | `call: METHOD /path`, `when`, `times` (exact; default at least once) |
 | `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.
@@ -499,8 +659,52 @@ npx slicetest gen --uncovered     # only the documented responses the last run d
 
 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`.
 
+Operations that the spec protects with a bearer token (`http: bearer`, `oauth2` or `openIdConnect` security) get `auth:` on their requests, with the scopes the spec requires in the token's `scope` claim, and their 401 responses become runnable scenarios that send no token. With [`auth`](#auth-a-real-openid-issuer-tokens-with-any-claims) in the config, the generated scenarios run against the app's real token checks.
+
 `--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**:
@@ -516,4 +720,4 @@ npm run test:dist   # the built package, and the CLI with examples/slicetest.con
 
 ## Status
 
-Early. Postgres and MySQL. CI runs on Linux and Windows.
+Early. Postgres, MySQL and SQLite. CI runs on Linux and Windows.

package/dist/auth.d.ts

@@ -0,0 +1,45 @@
+export interface TokenOptions {
+    /** Seconds until the token expires. Default 3600. */
+    expiresIn?: number;
+    /** A token that expired a minute ago. */
+    expired?: boolean;
+    /** Signed by a key the issuer doesn't publish: the app must reject it. */
+    wrongKey?: boolean;
+    /** Override `aud` (default: the configured audience). */
+    audience?: string | string[];
+    /** Override `iss`, e.g. to test that the app checks it. */
+    issuer?: string;
+}
+export interface AuthOptions {
+    /** `aud` of the tokens. Default `"slicetest"`. */
+    audience?: string;
+    /** Claims every token gets unless the scenario overrides them. */
+    claims?: Record<string, unknown>;
+}
+/**
+ * An OpenID Connect issuer for the app under test: it publishes a discovery
+ * document and a JWKS, so the app verifies tokens exactly as it does in
+ * production, and the scenario mints tokens with whatever claims it needs.
+ * `POST /token` answers the client-credentials grant for apps that fetch
+ * tokens themselves.
+ */
+export declare class Issuer {
+    #private;
+    private readonly server;
+    readonly url: string;
+    private readonly opts;
+    private constructor();
+    static start(opts?: AuthOptions): Promise<Issuer>;
+    get audience(): string;
+    get jwksUrl(): string;
+    /** A signed RS256 JWT. `claims` override the defaults (`sub: "user-1"`, `iss`, `aud`, `iat`, `exp`). */
+    token(claims?: Record<string, unknown>, opts?: TokenOptions): string;
+    /** `{ authorization: "Bearer <token>" }`, for `http.get(path, { headers })`. */
+    header(claims?: Record<string, unknown>, opts?: TokenOptions): {
+        authorization: string;
+    };
+    /** Rotate the signing key: tokens minted from now on use a new `kid`, and the JWKS publishes only it. */
+    rotate(): void;
+    reset(): void;
+    close(): Promise<void>;
+}

package/dist/auth.js

@@ -0,0 +1,128 @@
+import { createSign, generateKeyPairSync, randomUUID } from "node:crypto";
+import { createServer } from "node:http";
+const b64url = (data) => Buffer.from(data).toString("base64url");
+function newKey() {
+    const { privateKey, publicKey } = generateKeyPairSync("rsa", { modulusLength: 2048 });
+    const kid = randomUUID();
+    return { kid, privateKey, jwk: { ...publicKey.export({ format: "jwk" }), kid, alg: "RS256", use: "sig" } };
+}
+/**
+ * An OpenID Connect issuer for the app under test: it publishes a discovery
+ * document and a JWKS, so the app verifies tokens exactly as it does in
+ * production, and the scenario mints tokens with whatever claims it needs.
+ * `POST /token` answers the client-credentials grant for apps that fetch
+ * tokens themselves.
+ */
+export class Issuer {
+    server;
+    url;
+    opts;
+    #key = newKey();
+    /** Never published: tokens signed with it must be rejected. */
+    #rogue;
+    #issued = 0;
+    constructor(server, url, opts) {
+        this.server = server;
+        this.url = url;
+        this.opts = opts;
+    }
+    static async start(opts = {}) {
+        let issuer;
+        const server = createServer((req, res) => {
+            issuer.#handle(req).then(([status, body]) => {
+                res.writeHead(status, { "content-type": "application/json", "cache-control": "no-store" });
+                res.end(JSON.stringify(body));
+            }, (e) => {
+                res.writeHead(500, { "content-type": "application/json" });
+                res.end(JSON.stringify({ error: "server_error", error_description: String(e) }));
+            });
+        });
+        await new Promise((resolve) => server.listen(0, "127.0.0.1", resolve));
+        const { port } = server.address();
+        issuer = new Issuer(server, `http://127.0.0.1:${port}`, { audience: opts.audience ?? "slicetest", claims: opts.claims ?? {} });
+        return issuer;
+    }
+    get audience() {
+        return this.opts.audience;
+    }
+    get jwksUrl() {
+        return `${this.url}/.well-known/jwks.json`;
+    }
+    /** A signed RS256 JWT. `claims` override the defaults (`sub: "user-1"`, `iss`, `aud`, `iat`, `exp`). */
+    token(claims = {}, opts = {}) {
+        const now = Math.floor(Date.now() / 1000);
+        const exp = opts.expired ? now - 60 : now + (opts.expiresIn ?? 3600);
+        const key = opts.wrongKey ? (this.#rogue ??= newKey()) : this.#key;
+        const payload = {
+            iss: opts.issuer ?? this.url,
+            aud: opts.audience ?? this.opts.audience,
+            sub: "user-1",
+            iat: opts.expired ? exp - 3600 : now,
+            nbf: opts.expired ? exp - 3600 : now,
+            exp,
+            jti: `slicetest-${++this.#issued}`,
+            ...this.opts.claims,
+            ...claims,
+        };
+        const head = b64url(JSON.stringify({ alg: "RS256", typ: "JWT", kid: key.kid }));
+        const body = b64url(JSON.stringify(payload));
+        const signature = createSign("RSA-SHA256").update(`${head}.${body}`).sign(key.privateKey);
+        return `${head}.${body}.${b64url(signature)}`;
+    }
+    /** `{ authorization: "Bearer <token>" }`, for `http.get(path, { headers })`. */
+    header(claims, opts) {
+        return { authorization: `Bearer ${this.token(claims, opts)}` };
+    }
+    /** Rotate the signing key: tokens minted from now on use a new `kid`, and the JWKS publishes only it. */
+    rotate() {
+        this.#key = newKey();
+    }
+    reset() {
+        this.#issued = 0;
+    }
+    async #handle(req) {
+        const path = new URL(req.url ?? "/", this.url).pathname;
+        if (req.method === "GET" && path === "/.well-known/openid-configuration") {
+            return [
+                200,
+                {
+                    issuer: this.url,
+                    jwks_uri: this.jwksUrl,
+                    token_endpoint: `${this.url}/token`,
+                    response_types_supported: ["token"],
+                    subject_types_supported: ["public"],
+                    id_token_signing_alg_values_supported: ["RS256"],
+                    grant_types_supported: ["client_credentials"],
+                },
+            ];
+        }
+        if (req.method === "GET" && path === "/.well-known/jwks.json")
+            return [200, { keys: [this.#key.jwk] }];
+        if (req.method === "POST" && path === "/token") {
+            const form = new URLSearchParams(await text(req));
+            if (form.get("grant_type") !== "client_credentials")
+                return [400, { error: "unsupported_grant_type" }];
+            const basic = /^Basic\s+(.+)$/i.exec(req.headers.authorization ?? "")?.[1];
+            const client = form.get("client_id") ?? (basic ? decodeURIComponent(Buffer.from(basic, "base64").toString().split(":")[0]) : undefined);
+            if (!client)
+                return [401, { error: "invalid_client" }];
+            const claims = { sub: client, client_id: client };
+            const scope = form.get("scope");
+            if (scope)
+                claims.scope = scope;
+            const audience = form.get("audience") ?? undefined;
+            return [200, { access_token: this.token(claims, { audience }), token_type: "Bearer", expires_in: 3600, ...(scope ? { scope } : {}) }];
+        }
+        return [404, { error: "not_found", error_description: `slicetest's issuer serves /.well-known/openid-configuration, /.well-known/jwks.json and POST /token, not ${req.method} ${path}` }];
+    }
+    async close() {
+        this.server.closeAllConnections();
+        await new Promise((resolve) => this.server.close(resolve));
+    }
+}
+async function text(req) {
+    const chunks = [];
+    for await (const chunk of req)
+        chunks.push(chunk);
+    return Buffer.concat(chunks).toString();
+}

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(() => { });
+}