slicetest 0.7.0 → 0.8.0

package/README.md

@@ -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,10 +287,13 @@ 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
 ```
 
+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 `*`. 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`.
 
@@ -484,6 +490,7 @@ expect(responses).toHaveStatuses({ 201: 1, 409: 9 });            // an array, e.
 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 +498,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 +615,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 +645,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 +700,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 +710,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 | |
@@ -702,6 +729,7 @@ 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.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 +794,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 }`, `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` / `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 +805,48 @@ 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, or strings such as ISO dates (`{ $gte: "2026-01-01" }`); also `$gt`, `$lte` |
+  | `{ $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 +896,7 @@ 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)
 ```
 
 ### Scenarios from your OpenAPI spec: `npx slicetest gen`

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)
@@ -47,14 +52,14 @@ 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, 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 +72,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 +82,7 @@ export async function main(argv = process.argv.slice(2)) {
             diagrams: { type: "string" },
             stub: { type: "string" },
             upstream: { type: "string" },
+            json: { type: "boolean" },
         },
     });
     if (values.help) {
@@ -149,6 +156,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 +179,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`);

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

@@ -124,6 +124,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";
@@ -42,4 +45,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 {};

package/dist/form.js

@@ -37,7 +37,11 @@ export function parseForms(html) {
     let open;
     let select;
     let option;
+    // Controls inside a disabled <fieldset> are disabled too (and not submitted).
+    const fieldsets = [];
     const add = (control) => {
+        if (fieldsets.includes(true))
+            control.attrs.disabled ??= "";
         const formId = control.attrs.form;
         if (formId !== undefined)
             orphans.push({ formId, control });
@@ -62,6 +66,13 @@ export function parseForms(html) {
             TAG.lastIndex = end < 0 ? html.length : end;
             continue;
         }
+        if (tag === "fieldset") {
+            if (closing)
+                fieldsets.pop();
+            else
+                fieldsets.push("disabled" in parseAttrs(m[3] ?? ""));
+            continue;
+        }
         if (tag === "form") {
             if (closing)
                 current = undefined;
@@ -162,12 +173,22 @@ export function formRequest(html, opts = {}) {
         throw new Error(`slicetest: submit: the button ${JSON.stringify(label(button))} is disabled`);
     const names = new Set(form.controls.filter((c) => c.attrs.name !== undefined && !isSubmit(c) && c.tag !== "button").map((c) => c.attrs.name));
     const typed = new Map();
+    const files = new Map();
+    const fileInputs = new Set(form.controls.filter((c) => c.tag === "input" && c.attrs.type?.toLowerCase() === "file").map((c) => c.attrs.name));
     for (const [name, value] of Object.entries(opts.fields ?? {})) {
         if (!names.has(name)) {
             const shown = [...names].filter((n) => !n.startsWith("$ACTION_"));
             throw new Error(`slicetest: submit: the form has no field "${name}". Fields: ${shown.join(", ") || "(none)"}`);
         }
-        typed.set(name, typeof value === "boolean" ? value : (Array.isArray(value) ? value : [value]).map(String));
+        if (fileInputs.has(name) !== value instanceof Blob) {
+            throw new Error(fileInputs.has(name)
+                ? `slicetest: submit: "${name}" is a file input; give it a file (a Blob or File, or { file: path } in YAML)`
+                : `slicetest: submit: "${name}" isn't a file input, so it can't take a file`);
+        }
+        if (value instanceof Blob)
+            files.set(name, value);
+        else
+            typed.set(name, typeof value === "boolean" ? value : (Array.isArray(value) ? value : [value]).map(String));
     }
     // The successful controls, in document order (HTML's "constructing the entry list").
     // A typed value replaces what the page had: text for a field, the checked state for
@@ -176,6 +197,12 @@ export function formRequest(html, opts = {}) {
     const done = new Set();
     for (const c of form.controls) {
         const name = c.attrs.name;
+        if (c === button && c.attrs.type?.toLowerCase() === "image") {
+            // An image button sends the click position, as name.x / name.y (x / y without a name).
+            const prefix = name ? `${name}.` : "";
+            entries.push([`${prefix}x`, "0"], [`${prefix}y`, "0"]);
+            continue;
+        }
         if (name === undefined || "disabled" in c.attrs)
             continue;
         if (c.tag === "button" || isSubmit(c)) {
@@ -184,8 +211,16 @@ export function formRequest(html, opts = {}) {
             continue;
         }
         const type = c.tag === "input" ? (c.attrs.type ?? "text").toLowerCase() : c.tag;
-        if (type === "reset" || type === "button" || type === "file")
+        if (type === "reset" || type === "button")
+            continue;
+        if (type === "file") {
+            // With no file chosen, browsers still send the field: an empty file without a name.
+            const file = files.get(name);
+            if (!done.has(name))
+                entries.push([name, file ?? new File([], "", { type: "application/octet-stream" })]);
+            done.add(name);
             continue;
+        }
         const want = typed.get(name);
         if (type === "checkbox" || type === "radio") {
             const value = c.attrs.value ?? "on";
@@ -214,13 +249,43 @@ export function formRequest(html, opts = {}) {
     const pick = (attr) => (button && button.attrs[`form${attr}`] !== undefined ? button.attrs[`form${attr}`] : form.attrs[attr]);
     const method = (pick("method") ?? "get").toUpperCase() === "POST" ? "POST" : "GET";
     const action = pick("action") ?? "";
+    const multipart = method === "POST" && (pick("enctype") ?? "").toLowerCase() === "multipart/form-data";
+    if (files.size && !multipart) {
+        throw new Error(`slicetest: submit: the form sends ${method === "GET" ? "a GET" : "urlencoded"} data, which can't carry files; a browser would send only the file name. Upload forms need method="post" enctype="multipart/form-data"`);
+    }
+    // Outside multipart, a file field is sent as its file name (empty when none was chosen), as browsers do.
+    const plain = () => new URLSearchParams(entries.map(([k, v]) => [k, typeof v === "string" ? v : (v.name ?? "")]));
     if (method === "GET")
-        return { method, action: `${action.replace(/[?#].*$/, "")}?${new URLSearchParams(entries)}` };
-    const multipart = (pick("enctype") ?? "").toLowerCase() === "multipart/form-data";
+        return { method, action: `${action.replace(/[?#].*$/, "")}?${plain()}` };
     if (!multipart)
-        return { method, action, body: new URLSearchParams(entries) };
+        return { method, action, body: plain() };
     const body = new FormData();
-    for (const [k, v] of entries)
-        body.append(k, v);
+    for (const [k, v] of entries) {
+        if (typeof v === "string")
+            body.append(k, v);
+        else
+            body.append(k, v, v.name ?? "blob");
+    }
     return { method, action, body };
 }
+/** Fields as `application/x-www-form-urlencoded`: lists repeat the key, nested objects use bracket keys (`metadata[order]`). */
+export function encodeForm(fields) {
+    const out = new URLSearchParams();
+    const add = (key, v) => {
+        if (v === null || v === undefined)
+            return;
+        if (Array.isArray(v)) {
+            const nested = v.some((x) => x !== null && typeof x === "object");
+            v.forEach((x, i) => add(nested ? `${key}[${i}]` : key, x));
+        }
+        else if (typeof v === "object" && !(v instanceof Date)) {
+            for (const [k, x] of Object.entries(v))
+                add(`${key}[${k}]`, x);
+        }
+        else
+            out.append(key, v instanceof Date ? v.toISOString() : String(v));
+    };
+    for (const [k, v] of Object.entries(fields))
+        add(k, v);
+    return out;
+}

package/dist/global-setup.d.ts

@@ -3,6 +3,11 @@ import type { ResolvedOptions } from "./config.js";
 import "./provided.js";
 /** Runs once per vitest run: start the database server, migrate a template database, hand its location to the workers. */
 export default function setup(project: TestProject): Promise<() => Promise<void>>;
+/**
+ * Why this run covers only part of the suite (a file or name filter, tags, a shard), or undefined for a full run.
+ * Coverage then says little about the suite, so `minCoverage` isn't enforced and the cache for `gen --uncovered` is kept.
+ */
+export declare function partialRun(project: TestProject): Promise<string | undefined>;
 /**
  * A hash of everything that determines the migrated schema, or undefined when
  * that can't be known (a migration command without `inputs`).