slicetest 0.4.0 → 0.5.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,10 @@ 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.
+- **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.
 
@@ -187,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:
@@ -205,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
@@ -276,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:
@@ -389,6 +440,55 @@ 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`.
+
+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:
@@ -445,11 +545,13 @@ Scenarios in one file share an app and a database, so they always run one at a t
 | `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. |
@@ -506,6 +608,10 @@ scenarios:
 | `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`. `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) |
@@ -553,6 +659,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`
@@ -612,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/cli.js

@@ -39,11 +39,12 @@ Options:
 
 Config (paths are relative to the config file):
   app:      { command, env, cwd, ready: { path } | { log }, readyTimeout }
-  db:       { migrate: { atlas: { dir } } | { sql } | { command, inputs }, engine, seed, url, image, schemas, keep, reuse }
+  db:       { migrate: { atlas: { dir } } | { sql } | { command, inputs }, engine, seed, url, image, schemas, keep, reuse, queries }
   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}}
+  auth:     true | { audience, claims }   OpenID issuer at {{auth.issuer}} / {{auth.jwks}}
   openapi:  file | { spec, minCoverage }
   http:     { headers, query }
   include:  [globs]  default ["**/*.scenario.{yaml,yml}"]
@@ -86,17 +87,21 @@ export async function main(argv = process.argv.slice(2)) {
         return;
     }
     if (positionals[0] === "gen") {
-        const configOpenapi = configPath && existsSync(configPath) ? (parse(await readFile(configPath, "utf8")) ?? {}).openapi : undefined;
+        const config = configPath && existsSync(configPath) ? (parse(await readFile(configPath, "utf8")) ?? {}) : undefined;
+        const configOpenapi = config?.openapi;
         const spec = values.spec ?? (typeof configOpenapi === "object" ? configOpenapi.spec : configOpenapi);
         if (!spec)
             throw new Error("slicetest gen: no OpenAPI spec. Pass --spec openapi.yaml, or set `openapi` in the config.");
         const root = values.spec || !configPath ? process.cwd() : path.dirname(configPath);
         const { gen } = await import("./gen.js");
-        const { written, skipped, count } = await gen(root, { spec, out: values.out, uncovered: values.uncovered, force: values.force });
+        const { written, skipped, count, needsAuth } = await gen(root, { spec, out: values.out, uncovered: values.uncovered, force: values.force });
         const lines = [
             count === 0 ? "Every documented response is already covered; nothing to generate." : `${count} scenario(s) for the responses in ${spec}.`,
             ...written.map((f) => `  wrote   ${f}`),
             ...skipped.map((f) => `  skipped ${f} (exists; --force to overwrite)`),
+            ...(needsAuth && count > 0 && !config?.auth
+                ? ["", "The spec requires bearer tokens: requests carry `auth:`. Add `auth: true` to the config and point the app's JWT settings at {{auth.issuer}} / {{auth.jwks}}."]
+                : []),
         ];
         process.stdout.write(`${lines.join("\n")}\n`);
         return;

package/dist/config.d.ts

@@ -1,3 +1,4 @@
+import type { AuthOptions } from "./auth.js";
 import type { RequestOptions } from "./http.js";
 export interface SlicetestOptions {
     app: AppOptions;
@@ -43,6 +44,12 @@ export interface SlicetestOptions {
      * scenarios read what arrived with `mail.messages()` / `mail.waitFor()`.
      */
     mail?: boolean;
+    /**
+     * An OpenID Connect issuer for apps that verify JWTs. The app gets
+     * `{{auth.issuer}}`, `{{auth.jwks}}` and `{{auth.audience}}`; scenarios mint
+     * tokens with `auth.token({ sub, roles })`. `true`, or `{ audience, claims }`.
+     */
+    auth?: boolean | AuthOptions;
 }
 export interface ContainerOptions {
     image: string;
@@ -135,6 +142,12 @@ export interface DbOptions {
      * Default: on, except when `CI` is set or `url` is given.
      */
     reuse?: boolean;
+    /**
+     * Record the SQL the app runs: `{{db.url}}` points the app at a proxy that
+     * reads the wire protocol (Postgres and MySQL), so `db.queries()` lists every
+     * statement, whatever the app's language or driver. Off by default.
+     */
+    queries?: boolean;
 }
 export type MigrateOptions = {
     atlas: {
@@ -160,6 +173,7 @@ export interface ResolvedOptions {
     services: Record<string, ResolvedProcess>;
     containers: Record<string, ContainerOptions>;
     mail: boolean;
+    auth: AuthOptions | false;
     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

@@ -6,6 +6,7 @@ export function resolveOptions(opts, root) {
         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,
+        auth: opts.auth === true ? {} : (opts.auth ?? false),
         db: resolveDb(opts.db ?? {}),
         stubs: (opts.stubs ?? []).map(stubName),
         openapi: {
@@ -87,9 +88,24 @@ function validate(opts) {
     }
     if (opts.mail !== undefined && typeof opts.mail !== "boolean")
         fail(`mail must be true or false, got ${JSON.stringify(opts.mail)}`);
+    if (opts.auth !== undefined && typeof opts.auth !== "boolean") {
+        if (!opts.auth || typeof opts.auth !== "object" || Array.isArray(opts.auth))
+            fail(`auth must be true or { audience, claims }, got ${JSON.stringify(opts.auth)}`);
+        for (const key of Object.keys(opts.auth))
+            if (key !== "audience" && key !== "claims")
+                fail(`unknown key auth.${key} (expected audience, claims)`);
+        if (opts.auth.audience !== undefined && typeof opts.auth.audience !== "string")
+            fail("auth.audience must be a string");
+        if (opts.auth.claims !== undefined && (!opts.auth.claims || typeof opts.auth.claims !== "object" || Array.isArray(opts.auth.claims)))
+            fail("auth.claims must be a mapping of claim names to values");
+    }
     const engine = opts.db?.engine;
     if (engine !== undefined && engine !== "postgres" && engine !== "mysql" && engine !== "sqlite")
         fail(`db.engine must be "postgres", "mysql" or "sqlite", got ${JSON.stringify(engine)}`);
+    if (opts.db?.queries !== undefined && typeof opts.db.queries !== "boolean")
+        fail(`db.queries must be true or false, got ${JSON.stringify(opts.db.queries)}`);
+    if (engine === "sqlite" && opts.db?.queries)
+        fail("db.queries needs a database server (postgres or mysql): an SQLite app opens the file directly, so there is no connection to read");
     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;

package/dist/db.d.ts

@@ -1,4 +1,5 @@
 import type { Driver, Row } from "./drivers/driver.js";
+import type { QueryList, QueryLog } from "./query-log.js";
 export type { Row } from "./drivers/driver.js";
 /**
  * Column filters. `null` means IS NULL and an array means IN (...);
@@ -48,6 +49,31 @@ export declare class Db {
     count(table: string, where?: Where): Promise<number>;
     /** Insert rows and return them as stored (with defaults and generated ids). */
     insert<T extends Row = Row>(table: string, rows: Row | Row[]): Promise<T[]>;
+    /**
+     * Insert a row that satisfies the schema, giving only the columns the test cares about.
+     * Required columns get a value of their type (enums and `CHECK (... IN (...))` their first
+     * allowed value) and required foreign keys a parent row made the same way.
+     *
+     * ```ts
+     * const order = await db.make("orders", { status: "paid" }); // also creates the customer it needs
+     * ```
+     */
+    make<T extends Row = Row>(table: string, overrides?: Row): Promise<T>;
+    /** `count` rows made like `make()`; `overrides` may depend on the index. */
+    makeMany<T extends Row = Row>(table: string, count: number, overrides?: Row | ((i: number) => Row)): Promise<T[]>;
+    /** @internal Set by the runtime when `db.queries` is on. */
+    attachQueryLog(log: QueryLog): void;
+    /**
+     * SQL the app ran during this scenario, or only while `fn` ran. Needs `db: { queries: true }`.
+     * The test's own `db` calls aren't included.
+     *
+     * ```ts
+     * const queries = await db.queries(() => http.get("/posts"));
+     * expect(queries.repeated()).toEqual([]);   // no statement shape ran 3+ times: no N+1
+     * expect(queries.length).toBeLessThanOrEqual(3);
+     * ```
+     */
+    queries(fn?: () => unknown): Promise<QueryList>;
     /** Empty every data table without dropping the app's connections, then re-apply the seed. */
     reset(): Promise<void>;
     /**

package/dist/db.js

@@ -1,4 +1,5 @@
 import { readFile } from "node:fs/promises";
+import { Factory } from "./factory.js";
 /** Tables that record applied migrations. Truncating them would make tools re-run migrations. */
 const MIGRATION_TABLES = [
     "atlas_schema_revisions",
@@ -29,10 +30,13 @@ export class Db {
     /** Contents right after the reset (and seed); undefined means every table was empty. */
     #start;
     #checkpoint;
+    #factory;
+    #queryLog;
     constructor(driver, url, opts) {
         this.url = url;
         this.opts = opts;
         this.#driver = driver;
+        this.#factory = new Factory((table) => driver.describe(table), (table, row) => driver.insert(table, row));
     }
     static async connect(driver, url, opts) {
         const db = new Db(driver, url, opts);
@@ -80,10 +84,56 @@ export class Db {
             out.push(...(await this.#driver.insert(table, row)));
         return out;
     }
+    /**
+     * Insert a row that satisfies the schema, giving only the columns the test cares about.
+     * Required columns get a value of their type (enums and `CHECK (... IN (...))` their first
+     * allowed value) and required foreign keys a parent row made the same way.
+     *
+     * ```ts
+     * const order = await db.make("orders", { status: "paid" }); // also creates the customer it needs
+     * ```
+     */
+    async make(table, overrides = {}) {
+        return (await this.#factory.make(table, overrides));
+    }
+    /** `count` rows made like `make()`; `overrides` may depend on the index. */
+    async makeMany(table, count, overrides = {}) {
+        const out = [];
+        for (let i = 0; i < count; i++)
+            out.push(await this.make(table, typeof overrides === "function" ? overrides(i) : overrides));
+        return out;
+    }
+    /** @internal Set by the runtime when `db.queries` is on. */
+    attachQueryLog(log) {
+        this.#queryLog = log;
+    }
+    /**
+     * SQL the app ran during this scenario, or only while `fn` ran. Needs `db: { queries: true }`.
+     * The test's own `db` calls aren't included.
+     *
+     * ```ts
+     * const queries = await db.queries(() => http.get("/posts"));
+     * expect(queries.repeated()).toEqual([]);   // no statement shape ran 3+ times: no N+1
+     * expect(queries.length).toBeLessThanOrEqual(3);
+     * ```
+     */
+    async queries(fn) {
+        const log = this.#queryLog;
+        if (!log)
+            throw new Error("slicetest: db.queries() needs `db: { queries: true }` in the config (Postgres or MySQL); the app then connects through a proxy that records its SQL.");
+        if (!fn)
+            return log.queries();
+        const mark = log.mark();
+        await fn();
+        // Let statements already on the wire arrive.
+        await new Promise((r) => setTimeout(r, 10));
+        return log.queries(mark);
+    }
     /** Empty every data table without dropping the app's connections, then re-apply the seed. */
     async reset() {
         this.#tables ??= await this.#listTables();
         await this.#driver.truncate(this.#tables);
+        this.#factory.reset();
         this.#start = undefined;
         this.#checkpoint = undefined;
         if (this.#seed) {

package/dist/drivers/driver.d.ts

@@ -13,6 +13,31 @@ export interface Table {
     /** Primary-key columns, in order; empty when there is none. */
     key: string[];
 }
+export interface Column {
+    name: string;
+    /** The declared type as the engine reports it, e.g. `character varying(20)`, `int`, `TEXT`. */
+    type: string;
+    nullable: boolean;
+    /** Has a default, is generated, an identity or auto-increment column: inserts may leave it out. */
+    hasDefault: boolean;
+    maxLength?: number;
+    /** Labels of an enum type. */
+    values?: string[];
+}
+export interface ForeignKey {
+    columns: string[];
+    /** Referenced table, named like `Table.name`. */
+    table: string;
+    /** Referenced columns; empty means the referenced table's primary key (SQLite). */
+    references: string[];
+}
+/** What `db.make()` needs to build a valid row. */
+export interface TableShape {
+    columns: Column[];
+    foreignKeys: ForeignKey[];
+    /** Bodies of CHECK constraints, as the engine prints them. */
+    checks: string[];
+}
 export interface Driver {
     query<T extends Row = Row>(sql: string, params?: unknown[]): Promise<T[]>;
     /** Several parameterless SELECTs in one round trip. */
@@ -33,6 +58,8 @@ export interface Driver {
     truncate(tables: Table[]): Promise<void>;
     /** Insert one row and return it as stored (defaults and generated ids filled in). */
     insert(table: string, row: Row): Promise<Row[]>;
+    /** Columns, foreign keys and checks of `table`. Throws when there is no such table. */
+    describe(table: string): Promise<TableShape>;
     close(): Promise<void>;
 }
 /** Server-level operations: the databases slicetest creates for templates and workers. */

package/dist/drivers/mysql.d.ts

@@ -1,4 +1,4 @@
-import type { Driver, Engine, Row, Table } from "./driver.js";
+import type { Driver, Engine, Row, Table, TableShape } from "./driver.js";
 export declare class MysqlDriver implements Driver {
     #private;
     private readonly conn;
@@ -24,6 +24,7 @@ export declare class MysqlDriver implements Driver {
     truncate(tables: Table[]): Promise<void>;
     /** MySQL has no RETURNING: insert, then read the row back by its primary key. */
     insert(table: string, row: Row): Promise<Row[]>;
+    describe(table: string): Promise<TableShape>;
     close(): Promise<void>;
 }
 export declare const mysqlEngine: Engine;