slicetest 0.7.0 → 0.9.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`, or Bun, pnpm or Yarn from the lockfile), Deno, Phoenix, Django, FastAPI, Flask, Rails, Laravel, Symfony, plain PHP, Spring Boot, ASP.NET Core, Go and Rust apps; Atlas, Prisma, Alembic, Django, Rails, Laravel, Doctrine, EF Core, Ecto, 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.
+`init` recognises Node (`npm start`, or Bun, pnpm or Yarn from the lockfile), Deno, Phoenix, Django, FastAPI, Flask, Rails, Laravel, Symfony, plain PHP, Spring Boot, ASP.NET Core, Go (the main package at the root or in `cmd/<name>`) and Rust apps (both compiled once before the workers start); Atlas, Prisma, Alembic, Django, Rails, Laravel, Doctrine, EF Core, Ecto, Drizzle, Knex and plain SQL migrations (golang-migrate, goose, sqlx, Diesel and dbmate layouts in `migrations/`, `db/migrations/` or `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
 
@@ -175,6 +175,7 @@ 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.post("/orders", http.form({ items: [{ sku: "a" }], tags: ["x", "y"] })); // items[0][sku]=a&tags=x&tags=y
 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
 await http.graphql("query Poll($id: ID!) { poll(id: $id) { title } }", { id: 1 });  // POST /graphql ({ path } for another)
@@ -183,7 +184,7 @@ const admin = http.with({ headers: { authorization: `Bearer ${token}` } }); // s
 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. 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. Cookies follow their `Path` as in browsers.
+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, timeout }` in the plugin config. With `timeout` (ms), a request the app doesn't answer in time fails with its method and path instead of the whole test timing out, and a refused or dropped connection says the app isn't listening or closed it. A list in `query` repeats the parameter (`{ tag: ["a", "b"] }` → `?tag=a&tag=b`). 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. Cookies follow their `Path` as in browsers.
 
 #### Forms: `http.submit()`
 
@@ -200,6 +201,8 @@ await http.submit(await http.get("/settings"), {
 });
 ```
 
+File inputs take a `File` (`fields: { avatar: new File([bytes], "me.png", { type: "image/png" }) }`, YAML `{ file: me.png }` relative to the scenario), and one left alone is sent as the empty file a browser sends; the form must be `multipart/form-data`. An image button (`<input type="image">`) sends its click position.
+
 `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
@@ -243,7 +246,7 @@ 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.
+`toEqual` fails if the app wrote to a table you didn't list, which catches unexpected side effects. Values the app sets on every write would make that brittle, so leave them out: `db.changes({ ignore: ["updated_at", "orders.synced_at", "sessions.*"] })` drops a column in every table, a column in one table, or a whole table, and an update that only touched ignored columns isn't reported. `db: { ignoreChanges: [...] }` in the config does the same for every `changes()`, YAML `changes` step (which also takes `ignore:`), `trace()` snapshot and failure output. 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
 
@@ -284,11 +287,14 @@ stub("pay").on("GET", "/status").replySequence([{ status: 503 }, { status: 200 }
 stub("pay").on("POST", "/charge").delay(5_000).reply(200);    // exercise the app's timeouts
 stub("pay").on("POST", "/charge").networkError();             // drop the connection
 
+stub("stripe").on("POST", "/v1/payment_intents", { form: { amount: 2000, metadata: { order: "7" } } }).reply(200, { id: "pi_1" }); // form-encoded bodies
 stub("slack").on("POST", "/hook").optional().reply(200);      // may go uncalled, even with strictStubs
 stub("slack").calls("POST", "/hook");                         // recorded calls: method, path, params, query, headers, body, json
 ```
 
-Later routes win. `path` may also be a RegExp, and `method` may be `*`. Unanswered calls get a `501` and fail the scenario, with the closest route and why it didn't match (`stub.explain(call)`).
+Form-encoded bodies (Stripe, Twilio, OAuth token requests) are parsed into `call.form`, with bracket keys nested the way those providers read them: `metadata[order]=7&items[0][price]=p_1` is `{ metadata: { order: "7" }, items: [{ price: "p_1" }] }`. `form` conditions match a subset of it, and numbers and booleans compare with the strings sent. `multipart/form-data` bodies are read the same way, with each file as `{ filename, type, size, text }` (`text` for text, JSON, XML and CSV files), so `form: { avatar: { filename: "a.png", type: "image/png" } }` checks an upload the app passed on.
+
+Later routes win. `path` may also be a RegExp, and `method` may be `*`. A query written into the path (`on("GET", "/search?q=tea")`, also in `calls()`, `toHaveReceived()` and YAML stubs) is a condition on those parameters, like `query: { q: "tea" }`; other parameters may come along. A list matches a repeated parameter's values in order: `query: { ids: ["1", "2"] }` for `?ids=1&ids=2`. Unanswered calls get a `501` and fail the scenario, with the closest route and why it didn't match (`stub.explain(call)`).
 
 ### OpenAPI contracts — for your app and for the services you stub
 
@@ -342,7 +348,7 @@ slicetest: OpenAPI coverage (openapi.yaml): 8/9 documented responses (89%)
   POST   /polls/{id}/votes  204 ✓  400 ✓  404 ✓
 ```
 
-To fail the run below a threshold, use `openapi: { spec: "openapi.yaml", minCoverage: 100 }`. Filtered runs (`-t`, a single file) count too, so you may want `minCoverage: process.env.CI ? 100 : undefined`.
+To fail the run below a threshold, use `openapi: { spec: "openapi.yaml", minCoverage: 100 }`. It is checked on full runs only: a run filtered by file, `-t`, `--tag` or a shard still prints the coverage it saw, marked as partial, without failing, and doesn't replace what `gen --uncovered` reads.
 
 The example apps in `examples/` run every scenario against `examples/openapi.yaml` with `minCoverage: 100`, and their Slack calls against `examples/slack.openapi.yaml`.
 
@@ -459,7 +465,7 @@ Record once, with real credentials in the app's environment:
 SLICETEST_RECORD=github npx vitest     # or SLICETEST_RECORD=1 for every stub with an upstream
 ```
 
-Calls no route matches are forwarded to `upstream` (under its path prefix, headers included) and the answers are written to `recordings/github.yaml` (`recordings:` changes the path). Later runs replay them without touching the network. A request is identified by method, path, query and body (JSON key order doesn't matter); identical requests replay their recordings in the order they were made. Only `content-type`, `location`, `retry-after`, `link` and `etag` response headers are kept, and request headers are never stored, so tokens stay out of the file; bodies are stored as sent, so review the file before committing it.
+Calls no route matches are forwarded to `upstream` (under its path prefix, headers included) and the answers are written to `recordings/github.yaml` (`recordings:` changes the path). Later runs replay them without touching the network. A request is identified by method, path, query and body (JSON key order doesn't matter); identical requests replay their recordings in the order they were made. Only `content-type`, `location`, `retry-after`, `link` and `etag` response headers are kept, and request headers are never stored, so tokens stay out of the file. Credentials sent in the query or the body (`api_key`, `key` in the query, `appid`, `access_token`, `client_secret`, `password`, signatures, …) are stored as `[redacted]` and match any value on replay, so the test environment's dummy key replays what the real key recorded. Other values are stored as sent, so review the file before committing it.
 
 #### From a HAR file: `npx slicetest import`
 
@@ -480,10 +486,15 @@ Registered automatically:
 
 ```ts
 expect(res).toHaveStatus(201);                                   // failure shows the response body
+expect(res).toHaveStatus("2xx");                                 // a class, or a list: [200, 204], ["2xx", 304]
+expect(res).toRespondWithin(300);                                // a response-time budget, in ms
+expect(res).toSetCookie("sid", { httpOnly: true, secure: true, sameSite: "Lax" }); // a cookie and its attributes
+expect(res.events).toContainEqual({ event: "message_stop", data: {} }); // text/event-stream responses are parsed into events
 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");
+expect(stub).toHaveReceivedInOrder([["stripe", "POST", "/v1/charges"], ["mail", "POST", "/send"]]); // across stubs, others may come between
 expect(stub("github")).toHaveReceivedGraphQL("CreateIssue", { title: "Bug" });
 expect(await http.graphql(QUERY)).toHaveGraphQLData({ poll: { title: "x" } }); // no errors, data as a subset
 await expect(db).toHaveRow("polls", { title: "x" });             // at least one row
@@ -491,7 +502,7 @@ await expect(db).toHaveRow("votes", { poll_id: 1 }, 3);          // exactly thre
 expect(res).toMatchSchema("openapi.yaml#/components/schemas/Poll"); // a response's JSON, or any value; inline schemas too
 ```
 
-Failure messages list the calls the stub actually received, or the first rows of the table. `toMatchSchema` takes a JSON Schema object or a file with an optional pointer (relative to the working directory; JSON or YAML, OpenAPI 3.0 `nullable` understood, `$ref`s resolved within the file), and lists every mismatch by its JSON path: no OpenAPI setup is needed to check one response's shape.
+Failure messages list the calls the stub actually received, or the first rows of the table. `toHaveReceivedInOrder` is called on the scenario's `stub` accessor and checks the order of calls across stubs ("charge, then send the receipt"), each entry `[stub, method, path, match?]`; on failure it marks which entry didn't follow and lists every call to those stubs in the order they came. `toMatchSchema` takes a JSON Schema object or a file with an optional pointer (relative to the working directory; JSON or YAML, OpenAPI 3.0 `nullable` understood, `$ref`s resolved within the file), and lists every mismatch by its JSON path: no OpenAPI setup is needed to check one response's shape.
 
 ### Services: workers and other processes
 
@@ -608,7 +619,24 @@ In YAML, `auth` on a `request` step sends `Authorization: Bearer` with those cla
 
 ### 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.
+`http.webhook()` posts a payload the way the provider delivers it, signed with the secret the app is configured with, so the app's real verification code runs:
+
+| `provider` | Sends |
+|---|---|
+| `stripe` | `Stripe-Signature: t=…,v1=…` |
+| `github` | `X-Hub-Signature-256`, `X-GitHub-Event` (`event`) |
+| `slack` | `X-Slack-Signature: v0=…`, `X-Slack-Request-Timestamp` |
+| `shopify` | `X-Shopify-Hmac-Sha256`, `X-Shopify-Topic` (`event`) |
+| `standard` | [Standard Webhooks](https://www.standardwebhooks.com/) (Svix, Resend, Clerk, …): `webhook-id`, `webhook-timestamp`, `webhook-signature` |
+| `line` | LINE Messaging API: `X-Line-Signature` (base64, with the channel secret) |
+| `paddle` | Paddle Billing: `Paddle-Signature: ts=…;h1=…` |
+| `linear` | `Linear-Signature`, `Linear-Event` (`event`) |
+| `gitlab` | `X-Gitlab-Token` (the secret token), `X-Gitlab-Event` (`event`, default `Push Hook`) |
+| `zoom` | `x-zm-signature: v0=…`, `x-zm-request-timestamp` |
+| `twilio` | `X-Twilio-Signature` over the URL and the sorted form parameters; objects are sent as a form. The URL is the app's address and the path, or `url` when the app validates against a public URL it's configured with |
+| `twitch` | EventSub: `Twitch-Eventsub-Message-Signature`, `-Id`, `-Timestamp`, `-Type` (`event`, default `notification`) |
+
+The signatures are checked against the providers' documented examples where they publish one.
 
 ```ts
 const stripe = { provider: "stripe", secret: "whsec_test" } as const;   // the same secret as in app.env
@@ -621,7 +649,7 @@ expect(await http.webhook("/webhooks/stripe", event, { ...stripe, invalidSignatu
 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.
+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, url }` to a `request` step; its `json`, `form` or `body` is what gets signed.
 
 ### Asynchronous side effects
 
@@ -676,6 +704,7 @@ sequenceDiagram
 
 ```ts
 scenario("name", async ({ http, db, stub, app, service, container, trace, diagram }) => { ... }, timeoutMs?);
+scenario("refunds a charge", async (ctx) => { ... }, { tags: ["payments", "slow"], timeout: 10_000 });
 scenario.only / scenario.skip / scenario.todo
 scenario.each([{ choice: "a", status: 204 }, { choice: "x", status: 400 }])(
   "voting $choice returns $status",
@@ -685,6 +714,8 @@ scenario.each([{ choice: "a", status: 204 }, { choice: "x", status: 400 }])(
 
 Scenarios in one file share an app and a database, so they always run one at a time; `.concurrent` is rejected.
 
+Tags select scenarios across files: `npx slicetest --tag smoke` (repeat `--tag` for any of several, `--tag '!slow'` to leave some out), or `SLICETEST_TAGS=smoke,!slow npx vitest` with your own Vitest config. Scenarios a filter leaves out are reported as skipped. In YAML, `tags: [smoke, payments]` on a scenario.
+
 ### Configuration reference
 
 | Option | Default | |
@@ -698,10 +729,11 @@ Scenarios in one file share an app and a database, so they always run one at a t
 | `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?, env? }`. The command gets `DATABASE_URL`, and both it and `env` may use the `{{db.*}}` placeholders, for tools that read other variables: `{ command: "php artisan migrate --force", env: { DB_HOST: "{{db.host}}", DB_DATABASE: "{{db.name}}" } }`, `{ command: "dotnet ef database update --connection \"{{db.adoNet}}\"" }`. |
+| `db.migrate` | none | `{ atlas: { dir } }`, `{ sql: "file-or-dir" }` or `{ command, inputs?, env? }`. A `sql` directory is applied in name order with version numbers compared as numbers (`V2__` before `V10__`), leaving out rollbacks: `*.down.sql` (golang-migrate, sqlx, Diesel), Flyway undo files (`U2__…`) and the down section of goose (`-- +goose Down`) and dbmate (`-- migrate:down`) files. The command gets `DATABASE_URL`, and both it and `env` may use the `{{db.*}}` placeholders, for tools that read other variables: `{ command: "php artisan migrate --force", env: { DB_HOST: "{{db.host}}", DB_DATABASE: "{{db.name}}" } }`, `{ command: "dotnet ef database update --connection \"{{db.adoNet}}\"" }`. |
 | `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.ignoreChanges` | `[]` | Columns (`updated_at`, `orders.synced_at`) and tables (`sessions.*`) left out of `db.changes()`, `trace()` and the failure output. |
 | `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. |
@@ -766,9 +798,9 @@ scenarios:
 
 | Step | Keys |
 |---|---|
-| `stub: <name>` | `on: METHOD /path` (`:params` allowed) or `graphql: <operation>`, `when: { query, headers, json, body, variables }`, one of `reply: { status, headers, body }` (`{ data, errors }` for GraphQL) / `sequence: [...]` / `networkError: true`, plus `times`, `delay`. Replies may echo the call: `{{call.params.id}}`, `{{call.json.name}}`, `{{call.variables.id}}`. |
-| `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` / `graphql: { query, variables, operationName }`, `expect.schema` (a JSON Schema, or `../openapi.yaml#/components/schemas/Poll` relative to the file), `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. |
+| `stub: <name>` | `on: METHOD /path` (`:params` allowed) or `graphql: <operation>`, `when: { query, headers, json, form, body, variables }`, one of `reply: { status, headers, body }` (`{ file }` for a fixture file, `{ data, errors }` for GraphQL) / `sequence: [...]` / `networkError: true`, plus `times`, `delay`. Replies may echo the call: `{{call.params.id}}`, `{{call.json.name}}`, `{{call.form.amount}}`, `{{call.variables.id}}`. |
+| `submit: <button>` | `form`, `fields` (`{ file: path }` for a file input), `headers`, `follow`, `expect: { status, headers, json, text }` (`status` may be a class, `2xx`, or a list, `[200, 204]`; `duration: 300` fails a response slower than 300 ms, `duration: { $lt: 300 }` takes matchers; `cookies: { sid: { httpOnly: true, sameSite: Lax }, tracking: null }` checks the cookies it sets and their attributes, `null` for one it must not set; `events: [{ event: message_start }, { data: "[DONE]" }]` checks a `text/event-stream` response's events in order, others allowed between), `capture` (also from `events.0.data.id`). 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` / `multipart` / `body` / `graphql: { query, variables, operationName }`, `expect.schema` (a JSON Schema, or `../openapi.yaml#/components/schemas/Poll` relative to the file), `follow`, `expect: { status, headers, json, text }`, `capture`. `timeout: <ms>` fails it, by name, when the app doesn't answer in time. `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 |
@@ -777,19 +809,49 @@ scenarios:
 | `db: <table>` | `where`, `orderBy`, `expect: { rows, count }`, `capture` |
 | `sql: <query>` | `params`, `expect: { rows, count }`, `capture` |
 | `received: <stub>` | `call: METHOD /path` or `graphql: <operation>`, `when`, `times` (exact; default at least once) |
+| `order: [...]` | Calls to stubs in the order they must have come, others allowed between: `"stripe POST /v1/charges"` or `{ stub, call, when }`. Like `toHaveReceivedInOrder`. |
 | `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. |
+| `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. `ignore: [updated_at, sessions.*]` leaves out columns and tables. |
 | `checkpoint: true` | Later `changes` steps only see what happens after this step. |
+| `set: { name: value }` | Defines variables for later steps, e.g. `{ orderId: "{{$uuid}}", expires: "{{$now+1d}}" }`. |
 | `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. |
 | `use: <definition>` | `with: { param: value }`. Runs the steps of a `define:` entry. |
 | `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.
+`db`, `sql`, `received` and `changes` steps take `within: <ms>` to retry until they pass, for effects the app applies asynchronously. A `request` step with `within` sends the request again (every 200 ms, or `every: <ms>`) until its `expect` passes, for a job the app answers `202` and finishes later:
+
+```yaml
+- request: POST /exports
+  expect: { status: 202 }
+  capture: { job: json.id }
+- request: GET /exports/{{job}}
+  within: 10000
+  expect: { json: { status: done } }
+  capture: { file: json.url }
+```
 
+- `reply: { file: replies/charge.json }` answers with a file relative to the scenario file: `.json` and `.yaml` are sent as JSON and may still use `{{call.*}}`, other files as they are (images, PDFs, CSV), with a content type from the extension unless `headers` set one. Large provider payloads stay out of the scenario.
+- `multipart:` sends `multipart/form-data`: plain values are fields, `{ file: fixtures/avatar.png }` uploads a file (relative to the scenario file, content type from its extension, or `type` / `filename`), `{ content: ..., filename: notes.json }` an inline one, and a list sends a field several times.
 - `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.
+- Built-ins: `{{$uuid}}` (a new one each time), `{{$seq}}` (1, 2, 3… per scenario, the same on every run), `{{$now}}` (ISO time), `{{$today}}` (`YYYY-MM-DD`, UTC), `{{$timestamp}}` (Unix seconds) and `{{$timestampMs}}`; the time ones take an offset: `{{$now+7d}}`, `{{$timestamp-30m}}` (`ms`, `s`, `m`, `h`, `d`). `{{env.NAME}}` reads an environment variable, for tokens a CI job provides. In a stub's reply they're evaluated per call, so `id: "ch_{{$seq}}"` gives each call its own id.
+- Expected `json`, `rows` and `headers` are subsets: extra keys are fine. Values match loosely with:
+
+  | Matcher | Matches |
+  |---|---|
+  | `{ $type: number }` | `string`, `number`, `integer`, `boolean`, `array`, `object`, `null` |
+  | `{ $regex: "^ch_" }` | a string the pattern finds |
+  | `{ $contains: "ok" }` | a string with that substring, or a list with a matching item (`{ $contains: { sku: a } }`) |
+  | `{ $gte: 1, $lt: 10 }` | numbers (also decimals that `numeric` / `DECIMAL` columns return as strings, `"12.50"`), or strings such as ISO dates (`{ $gte: "2026-01-01" }`); also `$gt`, `$lte` |
+  | `{ $closeTo: 9.99 }` | a number within ±0.005 (`[9.99, 0.1]` for another tolerance), for floats and computed totals; decimal strings too |
+  | `{ $len: 3 }` | a string or list of that length; `{ $len: { $gte: 1 } }` |
+  | `{ $oneOf: [paid, pending] }` | any of the values (or matchers) |
+  | `{ $not: "" }` | anything the value or matcher doesn't match |
+  | `{ $format: uuid }` | `uuid`, `email`, `date`, `date-time`, `uri`, `integer` (a string of digits) |
+  | `{ $any: true }` | anything but `null` / missing |
+
+  Several `$` keys in one mapping must all hold.
+- A file-level `setup:` list runs at the start of every scenario. `skip`, `only`, `timeout` and `tags` work per scenario.
 - A file-level `define:` names step lists that `use:` steps run, like functions: `params` are given with `with:` and are `{{variables}}` inside, and what the steps capture is visible after the `use` (see below).
 - Mistakes are reported with the file and line before anything runs (`polls.scenario.yaml:12: unknown key "stauts" in expect`). A failing step reports its file, line and step number. The JSON Schema in `schema/` gives editors completion and inline errors.
 
@@ -839,6 +901,10 @@ stubs: [slack]
 npx slicetest                 # every *.scenario.yaml under the config's directory
 npx slicetest polls -t voting # filter by file and scenario name
 npx slicetest --watch
+npx slicetest list --tag smoke # what would run: file, line, tags, steps (--json for tools)
+npx slicetest -u              # rewrite `snapshot: true` snapshots that no longer match
+npx slicetest --reporter junit --output-file reports/slicetest.xml   # GitLab, Jenkins, CircleCI test reports
+npx slicetest --shard 2/4     # the second of four parts, for parallel CI jobs
 ```
 
 ### Scenarios from your OpenAPI spec: `npx slicetest gen`

package/dist/cli-run.d.ts

@@ -0,0 +1,13 @@
+export interface RunFlags {
+    update?: boolean;
+    reporter?: string[];
+    "output-file"?: string;
+    shard?: string;
+}
+/** Vitest options for the run flags of `npx slicetest`; paths are taken from where the command runs, like `--diagrams`. */
+export declare function runOptions(flags: RunFlags, cwd?: string): {
+    update?: boolean | undefined;
+    reporters?: string[] | undefined;
+    outputFile?: string | undefined;
+    shard?: string | undefined;
+};

package/dist/cli-run.js

@@ -0,0 +1,15 @@
+import path from "node:path";
+/** Vitest options for the run flags of `npx slicetest`; paths are taken from where the command runs, like `--diagrams`. */
+export function runOptions(flags, cwd = process.cwd()) {
+    if (flags.shard !== undefined) {
+        const m = /^(\d+)\/(\d+)$/.exec(flags.shard);
+        if (!m || Number(m[1]) < 1 || Number(m[1]) > Number(m[2]))
+            throw new Error(`slicetest: --shard takes <index>/<count> with 1 ≤ index ≤ count, e.g. --shard 1/3, got "${flags.shard}"`);
+    }
+    return {
+        ...(flags.update ? { update: true } : {}),
+        ...(flags.reporter?.length ? { reporters: flags.reporter } : {}),
+        ...(flags["output-file"] ? { outputFile: path.resolve(cwd, flags["output-file"]) } : {}),
+        ...(flags.shard ? { shard: flags.shard } : {}),
+    };
+}

package/dist/cli.js

@@ -16,6 +16,7 @@ const HELP = `Usage: slicetest [filters...] [options]
        slicetest doctor [--config <file>]
        slicetest record [--out <file>] [--port <n>]
        slicetest import <file.har> [--stub <name>] [--upstream <url>]
+       slicetest list [filters...] [--tag <tag>] [-t <pattern>] [--json]
 
 Runs *.scenario.yaml files against your app, as configured in slicetest.config.yaml.
 \`slicetest init\` looks at the project and writes a starting config and scenario.
@@ -25,6 +26,8 @@ app's OpenAPI spec; with --uncovered, only for those the last run didn't produce
 migrations, commands and spec files, and says what to fix.
 \`slicetest record\` starts everything and a proxy in front of the app: use the app
 through it (a browser, curl), press Enter, and get the session as a YAML scenario.
+\`slicetest list\` shows the YAML scenarios (file, line, tags, steps) and which ones
+--tag / -t / filters select, without starting anything; --json for tools.
 \`slicetest import\` turns a HAR file (the browser's network panel: "Save all as
 HAR"; Charles, mitmproxy, Proxyman) into recordings for the stubs whose
 \`upstream\` it has requests for, so they replay the real service's answers.
@@ -33,6 +36,8 @@ Options:
   -c, --config <file>  Config file (default: ${CONFIG_NAMES.join(" / ")} in the current directory)
   -w, --watch          Re-run on changes
   -t, --name <pattern> Only run scenarios whose name matches
+      --tag <tag>      Only run scenarios with this tag (repeat for any of several;
+                       !tag leaves those out), like SLICETEST_TAGS=smoke,!slow
       --spec <file>    gen: OpenAPI file (default: \`openapi\` from the config)
       --out <dir>      gen: where to write scenarios (default: scenarios)
                        record: the scenario file (default: scenarios/recorded-<time>.scenario.yaml)
@@ -41,20 +46,25 @@ Options:
       --upstream <url> import: the real service's base URL for --stub
       --uncovered      gen: only responses the last run didn't cover
       --force          init, gen: overwrite existing files
+  -u, --update         Rewrite snapshots (\`snapshot: true\` steps) that no longer match
+      --reporter <name> Vitest reporter: default, verbose, dot, junit, json, tap,
+                       github-actions (repeat for several)
+      --output-file <file> Where junit / json / tap reporters write
+      --shard <i/n>    Run the i-th of n parts of the suite (split CI jobs)
       --diagrams <dir> Write a Mermaid sequence diagram of every scenario to <dir>,
                        one Markdown page per scenario file
   -h, --help           Show this help
 
 Config (paths are relative to the config file):
   app:      { command, env, cwd, ready: { path } | { log }, readyTimeout }
-  db:       { migrate: { atlas: { dir } } | { sql } | { command, inputs }, engine, seed, url, image, schemas, keep, reuse, queries }
+  db:       { migrate: { atlas: { dir } } | { sql } | { command, inputs }, engine, seed, url, image, schemas, keep, ignoreChanges, 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 }
+  http:     { headers, query, timeout }
   offline:  true    refuse calls to hosts no stub answers
   strictStubs: true fail scenarios with stub routes the app never called
   include:  [globs]  default ["**/*.scenario.{yaml,yml}"]
@@ -67,6 +77,7 @@ export async function main(argv = process.argv.slice(2)) {
             config: { type: "string", short: "c" },
             watch: { type: "boolean", short: "w" },
             name: { type: "string", short: "t" },
+            tag: { type: "string", multiple: true },
             help: { type: "boolean", short: "h" },
             force: { type: "boolean" },
             spec: { type: "string" },
@@ -76,6 +87,11 @@ export async function main(argv = process.argv.slice(2)) {
             diagrams: { type: "string" },
             stub: { type: "string" },
             upstream: { type: "string" },
+            json: { type: "boolean" },
+            update: { type: "boolean", short: "u" },
+            reporter: { type: "string", multiple: true },
+            "output-file": { type: "string" },
+            shard: { type: "string" },
         },
     });
     if (values.help) {
@@ -149,6 +165,15 @@ export async function main(argv = process.argv.slice(2)) {
             process.exitCode = 1;
         return;
     }
+    if (positionals[0] === "list") {
+        const root = configPath && existsSync(configPath) ? path.dirname(configPath) : process.cwd();
+        const { listScenarios, formatList } = await import("./list.js");
+        const listed = await listScenarios(root, { filters: positionals.slice(1), name: values.name, tags: values.tag?.join(",") });
+        process.stdout.write(values.json ? `${JSON.stringify(listed, null, 2)}\n` : formatList(listed));
+        if (listed.errors.length)
+            process.exitCode = 1;
+        return;
+    }
     if (!configPath || !existsSync(configPath)) {
         process.stderr.write(`slicetest: no config found. Run "npx slicetest init" to create ${CONFIG_NAMES[0]} (see --help).\n`);
         process.exitCode = 1;
@@ -163,6 +188,8 @@ export async function main(argv = process.argv.slice(2)) {
     // Workers inherit the environment; a relative directory is taken from where the command runs.
     if (values.diagrams)
         process.env.SLICETEST_DIAGRAMS = path.resolve(values.diagrams);
+    if (values.tag?.length)
+        process.env.SLICETEST_TAGS = values.tag.join(",");
     const { startVitest, version } = await import("vitest/node");
     if (Number.parseInt(version, 10) < 4) {
         process.stderr.write(`slicetest: needs Vitest 4 or later, and this project has Vitest ${version}. Upgrade it (npm i -D vitest@latest), or run slicetest from a folder with its own package.json.\n`);
@@ -172,6 +199,8 @@ export async function main(argv = process.argv.slice(2)) {
     const { slicetest, YAML_SCENARIOS } = await import("./vitest.js");
     // Vitest 4 takes the mode ("test") first; 5 dropped it.
     const start = (Number.parseInt(version, 10) === 4 ? startVitest.bind(null, "test") : startVitest);
+    const { runOptions } = await import("./cli-run.js");
+    const run = runOptions(values);
     const vitest = await start(positionals, {
         config: false,
         root: path.dirname(configPath),
@@ -179,6 +208,7 @@ export async function main(argv = process.argv.slice(2)) {
         watch: !!values.watch,
         run: !values.watch,
         testNamePattern: values.name,
+        ...run,
     }, { plugins: [slicetest(options)] });
     if (!values.watch)
         await vitest?.close();

package/dist/config.d.ts

@@ -175,6 +175,12 @@ export interface DbOptions {
     schemas?: string[];
     /** Extra tables kept across resets, in addition to known migration bookkeeping tables. */
     keep?: string[];
+    /**
+     * Columns and tables `db.changes()`, YAML `changes` steps, `trace()` and the failure output leave out:
+     * `updated_at` (that column in every table), `orders.synced_at`, `sessions.*` (a whole table).
+     * For values the app sets on every write, so they don't fail a `toEqual` or a snapshot.
+     */
+    ignoreChanges?: string[];
     /**
      * Keep the Postgres container running between runs and cache the migrated
      * template by the contents of the migrations, so a run with unchanged

package/dist/config.js

@@ -59,10 +59,55 @@ function resolveDb(db) {
         reuse: db.reuse ?? (!url && !process.env.CI),
     };
 }
+const TOP_LEVEL_KEYS = ["app", "db", "stubs", "openapi", "http", "services", "containers", "mail", "offline", "strictStubs", "workers", "auth", "include"];
+const APP_KEYS = ["command", "build", "cwd", "env", "ready", "readyTimeout", "scope", "baseEnv"];
+const STUB_KEYS = ["name", "openapi", "autoReply", "upstream", "recordings", "hosts"];
+const CONTAINER_KEYS = ["image", "port", "env", "command", "ready", "reset"];
+const DB_KEYS = ["engine", "image", "url", "migrate", "seed", "schemas", "keep", "ignoreChanges", "reuse", "queries", "neon"];
+function editDistance(a, b) {
+    const row = Array.from({ length: b.length + 1 }, (_, i) => i);
+    for (let i = 1; i <= a.length; i++) {
+        let prev = row[0];
+        row[0] = i;
+        for (let j = 1; j <= b.length; j++) {
+            const tmp = row[j];
+            row[j] = Math.min(row[j] + 1, row[j - 1] + 1, prev + (a[i - 1] === b[j - 1] ? 0 : 1));
+            prev = tmp;
+        }
+    }
+    return row[b.length];
+}
 function validate(opts) {
     const fail = (msg) => {
         throw new Error(`slicetest: invalid config: ${msg}`);
     };
+    // A misspelt key (`stub:`, `strictstubs:`) would otherwise be ignored without a word; YAML configs have no type checker.
+    const checkKeys = (value, allowed, where) => {
+        if (!value || typeof value !== "object" || Array.isArray(value))
+            return;
+        for (const key of Object.keys(value)) {
+            if (allowed.includes(key) || key === "$schema")
+                continue;
+            // Close in spelling, or sharing the first four letters (`servers` / `services`, `migrations` / `migrate`).
+            const near = allowed
+                .map((k) => ({ k, d: editDistance(k.toLowerCase(), key.toLowerCase()) }))
+                .filter(({ k, d }) => d <= Math.max(2, Math.floor(key.length / 3)) || (key.length >= 4 && k.toLowerCase().startsWith(key.slice(0, 4).toLowerCase())))
+                .sort((a, b) => a.d - b.d)[0];
+            const hint = near ? `; did you mean "${near.k}"?` : ` (expected ${allowed.join(", ")})`;
+            fail(`unknown key ${where}${key}${hint}`);
+        }
+    };
+    checkKeys(opts, TOP_LEVEL_KEYS, "");
+    checkKeys(opts?.app, APP_KEYS, "app.");
+    if (opts?.db)
+        checkKeys(opts.db, DB_KEYS, "db.");
+    for (const stub of opts?.stubs ?? [])
+        if (typeof stub === "object" && stub)
+            checkKeys(stub, STUB_KEYS, `stubs.${stub.name ?? "?"}.`);
+    for (const [name, service] of Object.entries(opts?.services ?? {}))
+        checkKeys(service, APP_KEYS, `services.${name}.`);
+    for (const [name, container] of Object.entries(opts?.containers ?? {}))
+        checkKeys(container, CONTAINER_KEYS, `containers.${name}.`);
     if (!opts?.app || typeof opts.app.command !== "string" || !opts.app.command.trim()) {
         fail("app.command is required, e.g. { app: { command: \"node server.js\" } }");
     }
@@ -124,6 +169,9 @@ function validate(opts) {
     const engine = dbOpts?.engine;
     if (engine !== undefined && engine !== "postgres" && engine !== "mysql" && engine !== "sqlite")
         fail(`db.engine must be "postgres", "mysql" or "sqlite", got ${JSON.stringify(engine)}`);
+    if (dbOpts?.ignoreChanges !== undefined && !(Array.isArray(dbOpts.ignoreChanges) && dbOpts.ignoreChanges.every((c) => typeof c === "string" && c && !c.startsWith(".")))) {
+        fail(`db.ignoreChanges must be a list of columns or tables, e.g. [updated_at, orders.synced_at, sessions.*], got ${JSON.stringify(dbOpts.ignoreChanges)}`);
+    }
     if (dbOpts?.queries !== undefined && typeof dbOpts.queries !== "boolean")
         fail(`db.queries must be true or false, got ${JSON.stringify(dbOpts.queries)}`);
     if (dbOpts?.neon !== undefined && typeof dbOpts.neon !== "boolean")

package/dist/db.d.ts

@@ -26,6 +26,10 @@ export interface TableChanges<T extends Row = Row> {
     }[];
     deleted: T[];
 }
+export interface ChangesOptions {
+    /** Columns or tables to leave out: `updated_at` (in every table), `orders.synced_at`, `sessions.*`. Added to `db.ignoreChanges`. */
+    ignore?: string[];
+}
 /** Changed tables only, keyed by table name (`schema.table` outside `public`). */
 export type Changes = Record<string, TableChanges>;
 /** Test-side handle to the database the app under test is using. */
@@ -37,6 +41,7 @@ export declare class Db {
     static connect(driver: Driver, url: string, opts: {
         schemas: string[];
         keep: string[];
+        ignoreChanges?: string[];
         seedFile?: string;
     }): Promise<Db>;
     query<T extends Row = Row>(sql: string, params?: unknown[]): Promise<T[]>;
@@ -86,13 +91,19 @@ export declare class Db {
      * expect(await db.changes()).toEqual({ polls: { inserted: [expect.objectContaining({ title: "x" })], updated: [], deleted: [] } });
      * ```
      */
-    changes(): Promise<Changes>;
+    changes(opts?: ChangesOptions): Promise<Changes>;
     /** Make `changes()` report only what happens from now on. */
     checkpoint(): Promise<void>;
     /** Changes since the scenario started, regardless of checkpoints. Used for failure output. */
     changesSinceStart(): Promise<Changes>;
     close(): Promise<void>;
 }
+/**
+ * What `ignore` leaves out of one table: `"*"` for the whole table, else the columns.
+ * `updated_at` is that column in every table, `orders.synced_at` in one, `sessions.*` the whole table
+ * (the last segment is the column, so `billing.invoices.*` works for other schemas).
+ */
+export declare function ignored(ignore: readonly string[], table: string): "*" | Set<string>;
 /** Short summary of `changes()` for failure output. */
 export declare function formatChanges(changes: Changes, maxRows?: number): string;
 /** The `db` of an app without a database (`db: false`): resetting is a no-op, anything else explains. */

package/dist/db.js

@@ -151,9 +151,9 @@ export class Db {
      * expect(await db.changes()).toEqual({ polls: { inserted: [expect.objectContaining({ title: "x" })], updated: [], deleted: [] } });
      * ```
      */
-    async changes() {
+    async changes(opts = {}) {
         const base = this.#checkpoint === undefined || this.#checkpoint === "start" ? this.#start : this.#checkpoint;
-        return diff(this.#tables ?? [], base, await this.#snapshot());
+        return diff(this.#tables ?? [], base, await this.#snapshot(), [...(this.opts.ignoreChanges ?? []), ...(opts.ignore ?? [])]);
     }
     /** Make `changes()` report only what happens from now on. */
     async checkpoint() {
@@ -161,7 +161,7 @@ export class Db {
     }
     /** Changes since the scenario started, regardless of checkpoints. Used for failure output. */
     async changesSinceStart() {
-        return diff(this.#tables ?? [], this.#start, await this.#snapshot());
+        return diff(this.#tables ?? [], this.#start, await this.#snapshot(), this.opts.ignoreChanges ?? []);
     }
     /** Every tracked table's rows, in one round trip. */
     async #snapshot() {
@@ -201,11 +201,38 @@ export class Db {
         await this.#driver.close();
     }
 }
-function diff(tables, before, after) {
+/**
+ * What `ignore` leaves out of one table: `"*"` for the whole table, else the columns.
+ * `updated_at` is that column in every table, `orders.synced_at` in one, `sessions.*` the whole table
+ * (the last segment is the column, so `billing.invoices.*` works for other schemas).
+ */
+export function ignored(ignore, table) {
+    const columns = new Set();
+    for (const entry of ignore) {
+        const dot = entry.lastIndexOf(".");
+        if (dot === -1) {
+            columns.add(entry);
+            continue;
+        }
+        const t = entry.slice(0, dot);
+        if (t !== table && !(t === table.split(".").pop() && !t.includes(".")))
+            continue;
+        const column = entry.slice(dot + 1);
+        if (column === "*")
+            return "*";
+        columns.add(column);
+    }
+    return columns;
+}
+function diff(tables, before, after, ignore = []) {
     const out = {};
     for (const table of tables) {
-        const a = before?.get(table.name) ?? [];
-        const b = after.get(table.name) ?? [];
+        const skip = ignored(ignore, table.name);
+        if (skip === "*")
+            continue;
+        const strip = (rows) => (skip.size ? rows.map((r) => Object.fromEntries(Object.entries(r).filter(([c]) => !skip.has(c)))) : rows);
+        const a = strip(before?.get(table.name) ?? []);
+        const b = strip(after.get(table.name) ?? []);
         const changes = table.key.length > 0 ? diffByKey(a, b, table.key) : diffAsBags(a, b);
         if (changes.inserted.length || changes.updated.length || changes.deleted.length)
             out[table.name] = changes;

package/dist/form.d.ts

@@ -13,8 +13,11 @@ export interface SubmitOptions {
     button?: string;
     /** The form, by `id`, `name` or position (0-based), when the page has several and no `button` picks one. */
     form?: string | number;
-    /** Values typed into the form, by field name. A name the form doesn't have is an error (a typo, usually). */
-    fields?: Record<string, string | number | boolean | (string | number)[]>;
+    /**
+     * Values typed into the form, by field name. A name the form doesn't have is an error (a typo, usually).
+     * A file input takes a `Blob` / `File` (its name is the file name sent), and the form must be multipart.
+     */
+    fields?: Record<string, string | number | boolean | (string | number)[] | Blob>;
 }
 export interface FormRequest {
     method: "GET" | "POST";
@@ -31,6 +34,7 @@ interface Control {
     options: {
         value: string;
         selected: boolean;
+        disabled: boolean;
     }[];
 }
 interface ParsedForm {
@@ -42,4 +46,6 @@ export declare function decodeEntities(s: string): string;
 export declare function parseForms(html: string): ParsedForm[];
 /** Works out the request a browser would send for this page's form. */
 export declare function formRequest(html: string, opts?: SubmitOptions): FormRequest;
+/** Fields as `application/x-www-form-urlencoded`: lists repeat the key, nested objects use bracket keys (`metadata[order]`). */
+export declare function encodeForm(fields: Record<string, unknown>): URLSearchParams;
 export {};