slicetest 0.4.0 → 0.6.0

package/README.md

@@ -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. 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.
+`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
 
@@ -52,6 +52,12 @@ npx slicetest        # starts Postgres, migrates, starts your app, runs scenario
 - **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.
+- **Forms as a browser sends them.** `http.submit()` presses a button on a server-rendered page, hidden fields included, so CSRF tokens and Next.js server actions work without knowing their internals.
+- **Hard-coded APIs, stubbed anyway.** `hosts: [api.github.com]` catches calls to URLs written in the code or built into a framework, over HTTPS, from Node, Python, Go, Ruby or the JVM, with no change to the app. Redirects to those hosts are followed to the stub, so OAuth logins run end to end.
+- **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.
 
@@ -167,12 +173,30 @@ res.status; res.headers; res.text; res.json; res.durationMs;
 await http.get("/polls", { query: { page: 2 }, headers: { accept: "text/html" } });
 await http.post("/login", http.form({ user: "a", pass: "b" }));  // urlencoded; FormData, Blob and bytes also work
 await http.get("/old-path", { follow: true });                    // redirects are NOT followed by default
+await http.submit(await http.get("/signup"), { button: "Sign up", fields: { email: "a@b.test" } }); // a form, as a browser sends it
 
 const admin = http.with({ headers: { authorization: `Bearer ${token}` } }); // shares cookies with http
 http.cookies.get("session");                                     // cookies persist within a scenario
 ```
 
-Requests may only go to the app under test; absolute URLs to other hosts are rejected. Defaults for every request can be set with `http: { headers }` in the plugin config.
+Requests may only go to the app under test; absolute URLs to other hosts are rejected. Defaults for every request can be set with `http: { headers }` in the plugin config. With `follow`, cookies set by each redirect are kept (a login answering `302` with `Set-Cookie`), `303` and `301`/`302` turn into a `GET` as in browsers, and a redirect to another host is returned instead of followed.
+
+#### Forms: `http.submit()`
+
+`http.submit(page, opts)` sends a form of a page the app returned, the way a browser with JavaScript off does: every field with its value, the hidden ones included, plus the button that was pressed. So the test doesn't need to know about CSRF tokens (Django, Rails, Laravel) or the action ids and bound arguments of **Next.js server actions** — they are hidden inputs, sent along like a browser sends them.
+
+```ts
+const page = await http.get(`/q/${q.id}`);                    // a Next.js page with <button formAction={vote.bind(null, id, "a")}>
+const res = await http.submit(page, { button: "Dogs", follow: true });
+expect(res.text).toContain("Your choice");
+
+await http.submit(await http.get("/settings"), {
+  form: "profile",                                            // by id, name or position, when the page has several
+  fields: { name: "Ada", newsletter: true, tags: ["a", "b"] }, // checkboxes and radios by true / false / value
+});
+```
+
+`button` matches a submit button's text, `value`, `name` or `id`, and picks its form; its `formaction` / `formmethod` / `formenctype` apply. `fields` replace what the page had and must name existing fields, so a typo fails. When nothing matches, the error lists the page's forms and their buttons. In YAML, `submit:` uses the page the previous step requested.
 
 ### `db` — arrange and inspect the real database
 
@@ -187,6 +211,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:
@@ -205,6 +241,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
@@ -276,6 +332,88 @@ 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`.
 
+#### Streaming replies: `sse()`
+
+LLM APIs stream their answers as Server-Sent Events. `sse(events)` makes such a reply, each event as `[event, data]` or `{ event, data, id }`, data that isn't a string as JSON:
+
+```ts
+import { sse } from "slicetest";
+
+stub("anthropic").on("POST", "/v1/messages").reply(sse([
+  ["message_start", { type: "message_start", message: { id: "msg_1", type: "message", role: "assistant", content: [], model: "claude-sonnet-4-6", usage: { input_tokens: 5, output_tokens: 1 } } }],
+  ["content_block_start", { type: "content_block_start", index: 0, content_block: { type: "text", text: "" } }],
+  ["content_block_delta", { type: "content_block_delta", index: 0, delta: { type: "text_delta", text: "Hello" } }],
+  ["content_block_stop", { type: "content_block_stop", index: 0 }],
+  ["message_delta", { type: "message_delta", delta: { stop_reason: "end_turn" }, usage: { output_tokens: 1 } }],
+  ["message_stop", { type: "message_stop" }],
+]));
+```
+
+In YAML, `reply: { sse: [{ event: message_start, data: { ... } }, ...] }` instead of `body`.
+
+#### 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`.
+
+### Hard-coded hosts: `hosts`
+
+Stubs normally take over by giving the app their URL (`{{stub.github}}`) instead of the real one. When the URL is written in the code (`https://api.github.com`), or built into a framework (Spring Security's GitHub login), give the stub the hosts instead:
+
+```yaml
+stubs:
+  - name: github
+    hosts: [github.com]       # OAuth authorize and token endpoints
+  - name: github-api
+    hosts: [api.github.com]
+```
+
+The app is then started with `HTTPS_PROXY` / `HTTP_PROXY` pointing at slicetest and a certificate authority made for the run in the trust settings each runtime reads: `NODE_USE_ENV_PROXY` and `NODE_EXTRA_CA_CERTS` for Node (22.21+ / 24.5+), `SSL_CERT_FILE` / `REQUESTS_CA_BUNDLE` for Python, Ruby, Go and curl, and proxy and trust-store system properties in `JAVA_TOOL_OPTIONS` for the JVM (`HttpURLConnection`, `java.net.http.HttpClient`, Spring's `RestClient` and `RestTemplate`). Calls to those hosts reach the stub with their path and `Host` header, over HTTPS or HTTP; calls to other hosts go to the real ones and are listed in the failure output. Nothing changes in the app. Variables you set in `app.env` win over these, and `{{proxy.url}}`, `{{proxy.ca}}`, `{{proxy.bundle}}` and `{{proxy.truststore}}` are there for clients configured some other way.
+
+`*.connpass.com` covers every subdomain (one stub for `findy.connpass.com`, `mercari.connpass.com`, …); the stub sees the `Host` header, so a reply can depend on it (`{{call.headers.host}}`, or `call.headers.host` in a reply function).
+
+With `offline: true`, the app can only reach localhost and the stubs' hosts. A call anywhere else is refused and fails the scenario with the host's name, so a forgotten stub can't quietly reach a real service, and the first run tells you which hosts to add:
+
+```
+slicetest: offline: the app tried to reach api.lu.ma, which no stub answers. Add it to a stub's `hosts` (or remove `offline`).
+```
+
+Node apps also get a small preload (`NODE_OPTIONS=--require …`) that gives the proxy settings to `http.Agent`s that libraries make themselves (the Stripe SDK, many API clients), which `NODE_USE_ENV_PROXY` alone doesn't reach. A client in any language that ignores proxy settings altogether goes straight to the real host; `offline` can't stop what doesn't pass through it.
+
+The proxy settings reach every process the app command starts. When that command is a build tool (`gradle bootRun`, `mvn spring-boot:run`, `go run`), its own downloads go through the proxy too, and `offline` refuses them; the failure says so when the host is a package registry. Download dependencies in `app.build` (`./gradlew bootJar`, `mvn package`, which `slicetest init` sets up for Spring Boot), or start a built artifact.
+
+A redirect to an intercepted host is followed to its stub, as a browser would follow it to the real site. So a whole OAuth login runs in a scenario: the stub plays the provider's consent page and sends the browser back.
+
+```yaml
+setup:
+  - stub: github
+    on: GET /login/oauth/authorize
+    reply: { status: 302, headers: { location: "{{call.query.redirect_uri}}?code=c1&state={{call.query.state}}" } }
+  - stub: github
+    on: POST /login/oauth/access_token
+    reply: { body: { access_token: gho_test, token_type: bearer } }
+  - stub: github-api
+    on: GET /user
+    reply: { body: { id: 1, login: octocat } }
+scenarios:
+  - name: log in with GitHub
+    steps:
+      - request: GET /oauth2/authorization/github
+        follow: true                       # → github.com (stub) → back to the app's callback
+      - request: GET /api/me
+        expect: { json: { login: octocat } }
+```
+
 ### 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:
@@ -389,6 +527,57 @@ scenario("sign-up sends a confirmation link that works", async ({ http, mail })
 
 `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`.
+
+For libraries that don't take an issuer URL: `{{auth.publicKey}}` is the signing key as a PEM public key, and `auth.jwks` the JWKS document, for a stub to serve at the provider's own URL (see [Clerk](#clerk)).
+
+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:
@@ -436,23 +625,31 @@ Scenarios in one file share an app and a database, so they always run one at a t
 | Option | Default | |
 |---|---|---|
 | `app.command` | (required) | Shell command. May use `{{app.port}}` and the other placeholders. |
-| `app.env` | `{ PORT, DATABASE_URL }` | Values may use `{{app.port}}`, `{{db.url}}`, `{{stub.<name>}}`. The rest of `process.env` is inherited. |
+| `app.build` | none | Shell command run once per run before the app starts, while the database starts, e.g. `npm run build` for `next start`. It gets `app.env`'s literal values (Next.js inlines `NEXT_PUBLIC_*` at build time), not those with placeholders. Not repeated in watch mode. Services take `build` too. |
+| `db` | Postgres in a container | Database options (below), or `false` for an app without a database: nothing is started, `{{db.*}}` aren't set and `db.*` in scenarios explains that it's off. `slicetest init` writes `false` when it finds no migrations, no database service and no database library. |
+| `app.env` | `{ PORT, DATABASE_URL }` | Values may use `{{app.port}}`, `{{db.url}}`, `{{stub.<name>}}`. For apps that don't take one URL: `{{db.jdbcUrl}}` (`jdbc:postgresql://…`), `{{db.host}}`, `{{db.port}}`, `{{db.name}}`, `{{db.user}}`, `{{db.password}}`. The rest of `process.env` is inherited. |
 | `app.cwd` | vitest root | |
 | `app.ready` | `{ path: "/" }` | Poll a path until it answers below 500, or `{ log: "listening" \| /regex/ }`. |
 | `app.readyTimeout` | `30000` | |
+| `app.scope` | `"file"` | `"worker"`: start the app (and stubs, services) once per Vitest worker and keep it for all of that worker's test files, for apps that start slowly. Sets Vitest's `isolate: false`. |
 | `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.neon` | `false` | For Neon's serverless driver over HTTP: `{{db.url}}` is a Neon-style URL and slicetest answers the driver's queries from the test database ([Neon](#neon-and-vercel-postgres)). |
+| `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. |
+| `offline` | `false` | Refuse the app's HTTP(S) calls to hosts no stub intercepts, and fail the scenario naming them. |
+| `workers` | Vitest's default | Most Vitest workers (`maxWorkers`). Each has its own app and database. |
+| `stubs` | `[]` | Names of stubbed services, or `{ name, openapi?, autoReply?, upstream?, recordings?, hosts? }`: check calls against the provider's spec, answer from it, [replay recordings](#recording-a-real-service) of the real service, or answer for [hard-coded hosts](#hard-coded-hosts-hosts). |
+| `openapi` | none | The app's OpenAPI 3 spec, or `{ spec, minCoverage }`, or `{ fromApp: "/v3/api-docs" }` for a spec the running app serves (springdoc, FastAPI's `/openapi.json`, NestJS). Every response must match it; the run ends with a coverage report. |
 | `http` | `{}` | Default `headers` / `query` for every request. |
 
 The config is validated up front: a missing `app.command`, an ambiguous `db.migrate` or a duplicate stub name fails with a clear message instead of a timeout.
@@ -504,8 +701,13 @@ 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}}`. |
+| `submit: <button>` | `form`, `fields`, `headers`, `follow`, `expect: { status, headers, json, text }`, `capture`. Submits a form of the page the last request returned, like `http.submit()`; `submit: true` presses the form's only button. |
 | `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) |
@@ -525,7 +727,7 @@ scenarios:
 
 ### Without any JavaScript: `npx slicetest`
 
-Put the plugin options in `slicetest.config.yaml` and run the CLI. It needs Node, but no `package.json` scripts, TypeScript or Vitest config:
+Put the plugin options in `slicetest.config.yaml` and run the CLI. It needs Node, but no `package.json` scripts, TypeScript or Vitest config. To add TypeScript scenarios later, `slicetest()` without options in a `vitest.config.ts` reads the same file (`slicetest("path/to/config.yaml")` for another one):
 
 ```yaml
 # slicetest.config.yaml
@@ -553,6 +755,8 @@ 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`
@@ -597,6 +801,88 @@ Checks what a run needs before it starts, instead of failing with a timeout half
 1 problem(s) to fix before running.
 ```
 
+## Neon and Vercel Postgres
+
+Apps on Neon's serverless driver (`neon()` from `@neondatabase/serverless`, `drizzle-orm/neon-http`, `@vercel/postgres`'s `sql`) send each query over HTTPS to Neon, not to a Postgres port. With `db: { neon: true }`, `{{db.url}}` is a Neon-style connection string, and slicetest answers the driver's HTTP queries (single statements and `transaction()` batches) from the test database. The driver, its type parsing and its errors (with Postgres's `code`) are the real ones; `db.queries` sees the SQL. `slicetest init` sets it when the driver is a dependency. The driver's WebSocket mode (`Pool`, `Client`) isn't covered.
+
+With Drizzle, `drizzle-kit push` and `migrate` connect through the project's driver; with only Neon's installed, they try a WebSocket a local server doesn't answer, and exit 0 anyway (slicetest stops when a migration leaves the database without tables). Generate the SQL instead (`npx drizzle-kit generate`) and let slicetest apply it: `migrate: { sql: db/migrations }`, which `slicetest init` reads from `drizzle.config`'s `out`.
+
+## Clerk
+
+Clerk verifies session tokens with keys from its Backend API, and reads users from it. Both are stubbed, and the tokens come from slicetest's issuer, so requests run as any user, with no Clerk account:
+
+```yaml
+# slicetest.config.yaml (what `slicetest init` writes when @clerk/nextjs is a dependency)
+app:
+  env:
+    NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY: pk_test_Y2xlcmsuc2xpY2V0ZXN0LnRlc3Qk   # base64 of "clerk.slicetest.test$"
+    CLERK_SECRET_KEY: sk_test_slicetest
+auth: true
+stubs:
+  - name: clerk
+    hosts: [api.clerk.com, clerk.slicetest.test]
+```
+
+```ts
+function signIn({ auth, stub }: ScenarioContext, id = "user_1", email = "ada@example.com") {
+  stub("clerk").on("GET", "/v1/jwks").reply(200, auth.jwks);   // the keys Clerk verifies tokens with
+  stub("clerk").on("GET", `/v1/users/${id}`).reply(200, {
+    object: "user", id, first_name: "Ada", last_name: null, primary_email_address_id: "e1",
+    email_addresses: [{ object: "email_address", id: "e1", email_address: email, verification: { status: "verified" }, linked_to: [] }],
+    phone_numbers: [], web3_wallets: [], external_accounts: [], created_at: 0, updated_at: 0,
+  });
+  return auth.header({ sub: id, sid: "sess_1" });
+}
+
+scenario("checkout as a signed-in user", async (ctx) => {
+  const res = await ctx.http.post("/api/checkout", undefined, { headers: signIn(ctx) });
+  expect(res).toHaveStatus(200);
+});
+```
+
+`CLERK_JWT_KEY` with `{{auth.publicKey}}` would avoid the JWKS stub, but Next.js inlines environment variables into middleware at build time, before the key exists. Without a token, `auth.protect()` in middleware answers API routes with 404.
+
+## Spring Boot and other JVM apps
+
+`slicetest init` recognizes Spring Boot (Gradle or Maven, also in a `backend/` folder) and writes:
+
+```yaml
+app:
+  cwd: backend
+  build: ./gradlew bootJar -q      # built once: workers don't compile at once, bootRun downloads nothing
+  command: ./gradlew bootRun -q
+  env:
+    SERVER_PORT: "{{app.port}}"
+    SPRING_DATASOURCE_URL: "{{db.jdbcUrl}}"       # overrides application.yml
+    SPRING_DATASOURCE_USERNAME: "{{db.user}}"
+    SPRING_DATASOURCE_PASSWORD: "{{db.password}}"
+  ready: { path: /actuator/health }
+  readyTimeout: 120000
+  scope: worker                    # one JVM per worker, kept for all of its test files
+workers: 2
+```
+
+Starting a JVM takes seconds, so by default (`scope: file`, one app per test file) the start-up dominates: 8 test files took 28 s on a Spring Boot 4 app. With `scope: worker` the app is started once per Vitest worker and kept for every file that worker runs, and `workers` caps how many there are: 18 s with the default worker count, 10 s with 2, 8 s with 1. Scenarios stay independent, since the database, stubs and cookies are reset between them either way; what's shared is the app process (and its in-memory state, such as caches).
+
+Springdoc serves the spec at `/v3/api-docs`: `openapi: { fromApp: /v3/api-docs }` checks every response against it and reports its coverage, without a spec file in the repository. Generated specs often miss error responses and nullable fields, which this makes visible.
+
+Apps that run Hibernate with `ddl-auto: validate` against schema-owning migrations (Atlas, or a migration command) work as they are: slicetest migrates, Hibernate validates the result at start-up. For a faster start, build a jar once with `build: ./gradlew bootJar -q` and run `command: java -jar build/libs/app.jar`. Calls to hard-coded hosts (GitHub, Google, …) are caught with [`hosts`](#hard-coded-hosts-hosts).
+
+## Next.js
+
+Nothing Next-specific is needed beyond two settings. `slicetest init` writes both when `package.json` has `build` and `start` scripts:
+
+```yaml
+app:
+  build: npm run build   # `next start` serves the last build; without this, scenarios can pass against old code
+  command: npm start     # next start reads $PORT
+  env: { PORT: "{{app.port}}", DATABASE_URL: "{{db.url}}" }
+```
+
+- **Server actions** are ordinary form posts when JavaScript is off. Request the page, then `submit:` the button; the action id and bound arguments travel in hidden inputs, so scenarios keep working when a build changes the ids.
+- **Route handlers and pages** are plain HTTP: `request: GET /api/...` and `text: { $contains: ... }`. React may put `<!-- -->` between adjacent text nodes, so match on a word rather than on `75%` built from two values.
+- **Rows inserted by migrations** (seed data in an Atlas or Prisma migration) are truncated before every scenario, like everything else. Create what a scenario needs with `make`, or move shared rows to `db.seed`.
+
 ## 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**:
@@ -612,4 +898,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/app.js

@@ -69,11 +69,11 @@ export class App {
         // A restarted service keeps its port, so URLs already handed to other processes stay valid.
         const port = fixedPort ?? (await freePort());
         vars = { ...vars, [`${key}.port`]: String(port) };
-        const env = opts.env ?? { PORT: `{{${key}.port}}`, DATABASE_URL: "{{db.url}}" };
+        const env = opts.env ?? { PORT: `{{${key}.port}}`, ...("db.url" in vars ? { DATABASE_URL: "{{db.url}}" } : {}) };
         const child = spawn(interpolate(opts.command, vars, `${key}.command`), {
             shell: true,
             cwd: path.resolve(root, opts.cwd ?? "."),
-            env: { ...process.env, ...mapValues(env, (v) => interpolate(v, vars, `${key}.env`)) },
+            env: { ...process.env, ...opts.baseEnv, ...mapValues(env, (v) => interpolate(v, vars, `${key}.env`)) },
             stdio: ["ignore", "pipe", "pipe"],
             // POSIX: own process group, so stop() also kills whatever the shell spawned.
             // Windows: detaching would open a console window; taskkill /T walks the tree instead.

package/dist/auth.d.ts

@@ -0,0 +1,55 @@
+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;
+    /**
+     * The signing key as a PEM public key, for libraries that verify tokens with a key
+     * given in the environment instead of fetching a JWKS (Clerk's CLERK_JWT_KEY, …).
+     * The app gets it at start as {{auth.publicKey}}; tokens minted after `rotate()` use a key it doesn't know.
+     */
+    get publicKeyPem(): string;
+    /** The JWKS document itself (`{ keys: [...] }`), for a stub that serves keys at another provider's URL (Clerk's /v1/jwks, …). */
+    get jwks(): {
+        keys: Record<string, unknown>[];
+    };
+    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,140 @@
+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" }, pem: publicKey.export({ type: "spki", format: "pem" }) };
+}
+/**
+ * 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;
+    }
+    /**
+     * The signing key as a PEM public key, for libraries that verify tokens with a key
+     * given in the environment instead of fetching a JWKS (Clerk's CLERK_JWT_KEY, …).
+     * The app gets it at start as {{auth.publicKey}}; tokens minted after `rotate()` use a key it doesn't know.
+     */
+    get publicKeyPem() {
+        return this.#key.pem;
+    }
+    /** The JWKS document itself (`{ keys: [...] }`), for a stub that serves keys at another provider's URL (Clerk's /v1/jwks, …). */
+    get jwks() {
+        return { keys: [this.#key.jwk] };
+    }
+    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/cli.d.ts

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import type { SlicetestOptions } from "./config.js";
+import { type SlicetestOptions } from "./config.js";
 export interface CliConfig extends SlicetestOptions {
     include?: string[];
 }