@gfdelarue/testkit 0.6.0 → 0.6.1

package/README.md

@@ -50,13 +50,18 @@ whose empty selection is intentional; it should not be the default CI command.
 
 Testkit writes the immutable, verifiable run bundle under
 `.testkit/results/runs/<run-id>/`. Upload `.testkit/results` with `if: always()`
-when CI evidence should survive a failed job.
+when CI evidence should survive a failed job. If the job can kill Testkit before
+it seals the run, run `testkit cleanup` before the upload, so the run is sealed
+and redacted first. See
+[Read run evidence without the CLI](#read-run-evidence-without-the-cli).
 
 ## Report a run to GitHub or Gitea
 
 `testkit ci report` reads the last run in the checkout and posts it in three
 places: one commit status, the job's step summary, and one pull request comment
-that it updates in place.
+that it updates in place. It updates only a comment that its token's user
+wrote, and posts a new comment when the tracker won't say who that user is. It
+leaves out a CI run or issue link that holds credentials or a secret.
 
 ```yaml
 permissions:
@@ -80,10 +85,17 @@ steps:
   it, as the `env` lines above do. Gitea Actions accepts the same lines.
 - Testkit reads the token from `GITHUB_TOKEN` or `GH_TOKEN` for GitHub, and
   from `GITEA_TOKEN` for Gitea. In a Gitea Actions job it also reads
-  `GITHUB_TOKEN`. With no token set, it asks `git credential fill`. The token
-  that `actions/checkout` keeps in the checkout does not answer that request.
-- Testkit reaches GitHub Enterprise Server only from a GitHub Actions job on
-  that server, so `testkit bug file` works there only in a job.
+  `GITHUB_TOKEN`. Outside such a job, it sends `GITEA_TOKEN` only to the host
+  that `GITEA_SERVER_URL` names, such as `https://gitea.example.com`. With no
+  token set, it asks `git credential fill`. The token that `actions/checkout`
+  keeps in the checkout does not answer that request.
+- Testkit sends a token only over HTTPS. A plain `http://` remote or repository
+  URL works only for a loopback host such as `127.0.0.1`.
+- A job's token reaches only the job's own repository. When `bugs.repository`
+  names another one, give the step a token that may write to it.
+- Testkit reaches GitHub Enterprise Server, and GitHub Enterprise Cloud with
+  data residency (`*.ghe.com`), only from a GitHub Actions job on that host, so
+  `testkit bug file` works there only in a job.
 - GitHub gives a pull request from a fork a read-only token. `ci report` then
   writes the step summary and fails when it posts the status. Add
   `continue-on-error: true` to the step when the repository takes pull requests
@@ -99,7 +111,7 @@ steps:
 Testkit files a confirmed bug as an issue in the repository's GitHub or Gitea.
 The issue names the regression test that fails because of the bug, the commit
 that introduced the faulty lines, and the command that reproduces the failure.
-[Bug records](docs/bug-records.md) gives the issue format.
+[`docs/bug-records.md`](https://app.unpkg.com/@gfdelarue/testkit/files/docs/bug-records.md) gives the issue format.
 
 1. Write a Testkit test that fails because of the bug.
 2. Write the bug record as a JSON file. `testkit bug guide` prints the fields
@@ -111,8 +123,15 @@ that introduced the faulty lines, and the command that reproduces the failure.
 
 `testkit bug file` runs the test at the checked-out commit and files the issue
 only when the test fails. It stops when tracked files have uncommitted changes,
-when no remote branch contains the commit, or when an open issue already covers
-the test. The token needs permission to create issues and labels.
+when no branch on the remote contains the commit, or when an open issue already
+covers the test. It asks the remote which branches hold the commit, with the
+checkout's Git credentials, so a branch that was rewound or deleted there
+doesn't count. When it can't tell, because a remote doesn't answer or a shallow
+clone's history stops short, it stops and says why. After it files, it reads the open issues again. If another checkout
+filed the same test at the same time and its issue is older, Testkit closes its
+own issue and stops, naming the older one. GitHub can list a new issue a few
+seconds late, so Testkit waits up to 7.5 seconds for its own and says so when
+it doesn't appear. The token needs permission to create issues and labels.
 
 `testkit bug record` saves the `--vitest-config`, `--vitest-project`, and
 `--vitest-runner` it was given in the draft, and asks for `--vitest-project`
@@ -131,6 +150,38 @@ fragment. It refuses `--database` and `--env`; pass those values through
 root, so a relative `--environment-file` needs `testkit bug file` run from
 there too.
 
+`testkit bug file --batch` files several drafts in one call: the ids it is
+given, or every unfiled draft under `.testkit/bugs/` when it is given none.
+
+- It checks the checkout once and reads the open issues before it runs the
+  tests. It stops before it files anything when tracked files have uncommitted
+  changes, when no remote branch contains the commit, or when it cannot read
+  the open issues.
+- It runs the drafts' tests in one `testkit run`, or one run for each
+  `--vitest-config`, `--vitest-project`, and `--vitest-runner` the drafts were
+  recorded with. Each draft is judged by its own file's result, so a file that
+  is skipped or fails outside its tests rules out only its own draft.
+- It reads the open issues again before it files, in case another checkout
+  filed one of the tests meanwhile.
+- It reports one line per draft: filed, already filed, rejected with the
+  reason, or not filed.
+  - A draft is rejected when its own checks fail, for example when its test
+    passes or an open issue already covers the test, and the batch carries on.
+  - When the tracker refuses a request, the batch stops filing and reports the
+    drafts it has not reached as not filed.
+- It exits non-zero when any draft is rejected or not filed. `--json` returns
+  the same list.
+
+Each draft records its issue as soon as the tracker returns it, so running the
+batch again files only what is left. An open issue whose facts match the ones a
+draft would file counts as that draft's issue, so a batch stopped between the
+two steps does not file the bug twice. When the tracker creates an issue
+without its labels, the batch stops, the draft stays unfiled, and Testkit
+closes that issue. If it can't, the message says so, and you close the issue.
+Then run the batch again with a token that may label issues. The batch creates
+at most one issue a second. When the tracker limits the rate, it stops and
+says when to run it again.
+
 ### Name the product's areas
 
 Add `areas` to `testkit.config.ts` so that each issue names the part of the
@@ -147,7 +198,7 @@ export default defineConfig({
 
 `testkit bug file` puts an `area:<id>` label on the issue. If no area claims
 the fault's file, it stops and names the file. Without `areas`, Testkit files
-bugs with no area. See [`areas`](testkit-config-schema.md#areas).
+bugs with no area. See the `areas` section of [`testkit-config-schema.md`](https://app.unpkg.com/@gfdelarue/testkit/files/testkit-config-schema.md).
 
 ### Pass a run whose failures are all filed
 
@@ -163,7 +214,8 @@ export default defineConfig({
 A run then passes when an open issue with the `testkit` label covers each
 failure. A new failure still fails the run, and closing an issue makes its
 test count again. When Testkit cannot read the issues, every failure is new.
-[Known failures](docs/bug-records.md#known-failures) gives the exact rule.
+The Known failures section of [`docs/bug-records.md`](https://app.unpkg.com/@gfdelarue/testkit/files/docs/bug-records.md) gives the
+exact rule.
 
 With `"allow"`, the run reads the open issues. In CI, pass the job's token to
 the `testkit run` step as well:
@@ -175,7 +227,9 @@ steps:
       GITHUB_TOKEN: ${{ github.token }}
 ```
 
-The job also needs the `issues: read` permission.
+The job also needs the `issues: read` permission. Testkit reads
+`GITHUB_TOKEN`, `GH_TOKEN` and `GITEA_TOKEN` itself and doesn't pass them to
+services or setup steps. A service that needs one declares it in its `env`.
 
 ### Run a campaign
 
@@ -293,10 +347,10 @@ npx @gfdelarue/testkit setup playwright --with-deps # CI and fresh hosts
 ```
 
 Normal runs never install or download a browser.
-[Installation](docs/engines.md#installation) covers what an install contains,
-the supported platforms, and how to recover a broken one.
-[Typechecking](docs/engines.md#typechecking) covers the supported TypeScript
-versions and `tsconfig.playwright.json`.
+The Installation section of [`docs/engines.md`](https://app.unpkg.com/@gfdelarue/testkit/files/docs/engines.md) covers
+what an install contains, the supported platforms, and how to recover a broken
+one. Its Typechecking section covers the supported TypeScript versions and
+`tsconfig.playwright.json`.
 
 Testkit bounds the output it captures from each command it runs, and asks the
 command and its descendants to stop on cancellation or timeout.
@@ -314,19 +368,20 @@ reserves `APPDATA`, `ComSpec`, `HOME`, `LANG`, `LC_ALL`, `LOCALAPPDATA`, `PATH`,
 
 - Node/Vitest reserves `BASE_URL`, `FORCE_COLOR`, `NODE_OPTIONS`, `NO_COLOR`,
   `UPDATE_SNAPSHOT`, `VITEST_POOL_ID`, `VITEST_WORKER_ID`, and the `TESTKIT_`
-  keys it sets itself, listed in
-  [Environment](docs/engines.md#environment);
+  keys it sets itself, listed in the Environment section of
+  [`docs/engines.md`](https://app.unpkg.com/@gfdelarue/testkit/files/docs/engines.md);
   other `TESTKIT_` and `VITEST_` keys, such as
   `TESTKIT_REQUIRE_COMPLETE_SUITE`, pass through, though Vitest's own `TEST`,
   `VITEST`, `VITEST_MODE`, `FORCE_TTY`, `MODE`, `DEV`, `PROD`, and `SSR`
   replace a group's values;
 - Playwright reserves the `TESTKIT_`, `PLAYWRIGHT_`, `PWTEST_`, and `PW_TEST_`
-  prefixes plus `BASE_URL`, `FORCE_COLOR`, `NODE_OPTIONS`, and `NO_COLOR`.
+  prefixes plus `BASE_URL`, `DBUS_SESSION_BUS_ADDRESS`, `FC_FONTATIONS`,
+  `FORCE_COLOR`, `NODE_OPTIONS`, and `NO_COLOR`.
 
 Case-variant duplicates and invalid names or NUL-containing values fail instead
 of being normalized. Node/Vitest accepts at most 512 entries and
 4 MiB of UTF-8 key/value data. Playwright accepts at most 512 entries and 2 MiB
-of UTF-8 key/value data. [Environment](docs/engines.md#environment) lists the
+of UTF-8 key/value data. The Environment section of [`docs/engines.md`](https://app.unpkg.com/@gfdelarue/testkit/files/docs/engines.md) lists the
 complete limits, and [Named endpoints and databases](#named-endpoints-and-databases)
 covers the environment API.
 
@@ -402,7 +457,7 @@ which `taskConcurrency` doesn't limit.
 `execution.workers`, `presets.nodeNext({ workers })` and `--workers` are
 deprecated aliases. When both names are
 provided in config or on the CLI, their values must match. The CLI value overrides
-config after those checks. See the [execution settings](testkit-config-schema.md#execution).
+config after those checks. See the `execution` section of [`testkit-config-schema.md`](https://app.unpkg.com/@gfdelarue/testkit/files/testkit-config-schema.md).
 
 Batch `run` output stays intentionally short: one line per completed file,
 concise failure blocks, and a final summary. Service logs, captured runtime
@@ -498,7 +553,7 @@ The environment file is JSON:
   "handles": {
     "webhook": {
       "kind": "http-capture",
-      "url": "http://127.0.0.1:41000/webhook",
+      "url": "http://127.0.0.1:41000/__testkit__/<segment>/webhook",
       "requestsUrl": "http://127.0.0.1:41000/__testkit__/<capability>/requests",
       "resetUrl": "http://127.0.0.1:41000/__testkit__/<capability>/requests"
     }
@@ -589,7 +644,7 @@ assertLocalDatabaseUrl(process.env, "seed.ts");
 
 ## Setup
 
-See the [configuration schema](testkit-config-schema.md) for the complete,
+See [`testkit-config-schema.md`](https://app.unpkg.com/@gfdelarue/testkit/files/testkit-config-schema.md) for the complete,
 strict `testkit.config.ts` contract.
 
 Create `testkit.config.ts` at repo root:
@@ -675,7 +730,7 @@ neither:
 import { defineFile } from "@gfdelarue/testkit";
 
 export const testkit = defineFile({
-  engine: "node-vitest",
+  engine: "playwright",
   skip: "Billing is currently unavailable locally",
 });
 ```
@@ -734,6 +789,10 @@ it. Database changes for one product run one at a time; other products don't
 wait for them. Use `cleanup --resources --dry-run` to preview the selected
 product's cleanup.
 
+A run's start and its post-run maintenance don't list or reclaim Docker
+resources. A run stops its retained database by name when it releases the run's
+resources.
+
 `database.template` is the database-side equivalent for reusable template DB
 state. When `database.sourceSchema` is configured, Testkit treats the configured
 source database as the schema source of truth. A normal `testkit run` resolves a
@@ -844,6 +903,8 @@ services: {
 }
 ```
 
+## Run evidence
+
 Every terminal run is sealed under `.testkit/results/runs/<run-id>/` with a
 canonical `run.json`, `provenance.json`, `manifest.json`, and the run's exact
 artifact/log/setup files. Payloads are SHA-256 addressed under
@@ -869,25 +930,56 @@ workspace API.
 Sealing replaces secrets with `<redacted>` in the run record and in every text
 file of the bundle. A key names a secret when it holds `PASSWORD`, `TOKEN`,
 `SECRET`, `PRIVATE_KEY`, `AUTH`, `COOKIE`, `SESSION`, or `API_KEY` in any letter
-case. Sealing redacts:
+case, or when its last word is `PASS`, `PASSWD`, `PAT`, `DSN`, `CREDENTIAL`, or
+`CREDENTIALS`. `AUTH` doesn't count in `AUTHOR` or `AUTHORITY`, so
+`GIT_AUTHOR_NAME` names no secret, though `AUTHORIZATION` still does. `SESSION`
+doesn't count before `COUNT`, `DURATION`, `EXPIR`, `LENGTH`, `LIMIT`, `MAX`,
+`TIMEOUT`, or `TTL`, as in `sessionCount` and `SESSION_TIMEOUT`. A key whose
+last two words are `API`, `PRIVATE`, `SIGNING`, or `ENCRYPTION` and then `KEY`,
+as in `apiKey`, `x-api-key`, and `privateKey`, names a secret too, and so does
+an upper-case key whose last word is `KEY`, such as `STRIPE_KEY`, unless the
+word before it is `PUBLIC` or `PUBLISHABLE`. Words break at any character other
+than a letter or a digit, and before an upper-case letter that follows a
+lower-case letter or a digit. Sealing redacts:
 
 - A `KEY=value` assignment under such a key, an `Authorization`,
-  `Proxy-Authorization`, `Cookie`, or `Set-Cookie` header value, a JSON string
-  value under such a key, even when the key is spelled with escapes, a
-  single-quoted `'password': '…'` value, and a URL's password, wherever they
-  appear. A quoted value ends at its closing quote and keeps its quotes, and a
-  value that starts with an auth scheme such as `Bearer` ends with its line.
-  A secret in one JSON value leaves the record's other values as they are.
+  `Proxy-Authorization`, `Cookie`, `Set-Cookie`, `Api-Key`, or `X-Api-Key`
+  header value, a JSON string value under such a key, even when the key is
+  spelled with escapes, a single-quoted string value under such a key, a token
+  of at least eight characters with a digit after `Bearer`, and a URL's
+  password, wherever they appear. A
+  quoted value ends at its closing quote and keeps its quotes, and a value that
+  starts with an auth scheme such as `Bearer` ends with its line. A secret in
+  one JSON value leaves the record's other values as they are.
+- Every string in a JSON array or object under such a key, unless the key
+  names a secret only through `AUTH`, `COOKIE`, or `SESSION`, so `tokens`,
+  `credentials`, and `privateKey` count and `session` and `auth` settings stay.
+  In an object with a `name` string and a `value` string, only the `value` and
+  members whose own key names a secret count. Numbers and booleans stay.
+- The value after `password:` or `passwd:`, or after a key whose last word is
+  one of those: a quoted value anywhere, as in `{ password: 'hunter2' }`, and
+  an unquoted value at the start of a line, as in YAML, when it is the line's
+  one word. A value that is one word of letters, perhaps followed by
+  punctuation such as `!` or `.`, stays, and so does an unquoted value after
+  other text, so `password: 'Required'`, `password: required!`, and
+  `rejects a password: too short` stay.
+- A token of at least 20 characters with a digit that stands alone as the user
+  of an `http` or `https` URL, as in `https://ghp_…@github.com`. A URL's
+  password may hold `/` and `@`, and sealing also finds it in a directory name,
+  which keeps one slash of the URL, as in `postgres:/app:…@db`.
+- A header or cookie stored as a `{"name": …, "value": …}` pair, as Playwright
+  traces and HAR files store them: the value when the name names a secret, and
+  every value in a `cookies` array.
 - The value of each such key, and of each key that `redact` names, in the
-  environment Testkit runs in. When the value is a URL, its password counts
-  too.
+  environment Testkit runs in. When the value is a URL, its password, or a
+  token that stands alone as its user, counts too.
 - The values the run's environment resolved: each value under such a key or a
-  key that `redact` names, and the password of each URL. A PostgreSQL URL's
-  password may also be a `password` query parameter, as libpq reads it. This
-  covers config `env`, env files, `local.env`, dependency services, base,
-  readiness, UI, and database URLs, `--env`, `--env-from`, and an
-  `--environment-file`. A value under such a key that is a URL counts only for
-  its password.
+  key that `redact` names, and the password or token user of each URL. A
+  PostgreSQL URL's password may also be a `password` query parameter, as libpq
+  reads it. This covers config `env`, env files, `local.env`, dependency
+  services, base, readiness, UI, and database URLs, `--env`, `--env-from`, and
+  an `--environment-file`. A value under such a key that is a URL counts only for
+  its password or token user.
 - The unguessable segment in each [HTTP capture's](#handles) operation URLs,
   from a setup module's capture or an `--environment-file` handle.
 
@@ -909,12 +1001,41 @@ and keys in the free-form data and metadata that tests attach. When output cuts
 the cut with `…` or `...`, sealing redacts the part that shows. `testkit run
 --json` and the run's progress output apply the same redaction.
 
+Sealing also redacts inside `.zip` and `.gz` files, and files that start like
+one, such as a Playwright `trace.zip`. It applies the rules above to each text
+entry, such as a trace's actions, network log, and page and API responses, and
+writes the archive again with the redacted entries. A text entry is valid UTF-8
+without binary control characters, or UTF-16 with a byte order mark. Other
+entries keep their bytes. A ZIP with a comment or extra fields is written again
+without them, and a gzip file is always written again without the name and
+comment in its header. A trace stays readable in the Playwright trace viewer,
+with `<redacted>` where a typed password or a token was.
+
+Sealing refuses an archive it can't redact:
+
+- one it can't read: encrypted, needing ZIP64 sizes, compressed with a method
+  other than deflate, larger than 512 MiB once expanded, or damaged, including
+  a ZIP with bytes that none of its entries account for;
+- one with a binary entry, such as a screenshot, that holds one of the values
+  above, as UTF-8 or UTF-16;
+- one that holds another archive.
+
+Sealing removes each file it refuses from the run's results and fails the run
+with the reason, for example:
+
+```text
+Refusing to archive compressed file whose entry inner/trace.zip is itself an archive, and removed it: …/.testkit/results/artifacts/frontend/task-1-01-bundle.zip
+```
+
+The run, or the `testkit stop`, `testkit cleanup` or next run that seals it
+later, then seals the rest of its results and records the reason.
+
 Some secrets stay visible:
 
 - What a setup module prints goes to the terminal as written.
-- Sealing does not look inside compressed or binary files, such as a Playwright
-  `trace.zip`. It refuses to seal a binary file that holds one of the values
-  above in plain bytes.
+- Sealing does not redact images or video, including the screenshots in a
+  trace. Text typed into a page shows in them. Sealing refuses and removes a
+  binary file that holds one of the values above as UTF-8 or UTF-16.
 - When a run's process is killed before it seals the run, `testkit stop`,
   `testkit cleanup`, or the next run seals it from another process. That
   process does not have the values the run's environment resolved or the
@@ -922,6 +1043,15 @@ Some secrets stay visible:
   values under the words above. The bundle's `archive.redaction.status` is then
   `source-targets-unavailable` instead of `applied`.
 
+Sealing also takes out local paths. In the run record, in every text file of
+the bundle, and in every text entry of a compressed file, a path under the
+product directory becomes relative to it, the product directory itself becomes
+`.`, and a path under your home directory starts with `~`. This covers engine
+reports, failure stacks, logs, and Playwright traces, and happens after
+redaction. Binary files and binary entries keep their paths. When sealing
+changes a file, the file's size and SHA-256 in `run.json` describe the sealed
+file.
+
 Use the artifact archive config to opt into pruning or atomic publication to
 an external directory. Local retention is indefinite by default:
 
@@ -963,6 +1093,73 @@ Programmatic consumers can import `listRunBundles`, `loadRunBundleArtifact`,
 `loadRunBundleManifest`, and `verifyRunBundle` from
 `@gfdelarue/testkit/workspace`.
 
+### Read run evidence without the CLI
+
+Run evidence is plain files, so you can investigate a run with `ls`, `grep`,
+`jq`, and `sha256sum` when `testkit` can't start, for example because the
+config no longer loads. A command that fails to load the config stops before it
+writes to `.testkit/results`, and `testkit artifacts` doesn't need the config.
+
+| Path under `.testkit/results/`  | What it holds                                                                                                                                                                                                          |
+| ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `runs/<run-id>/run.json`        | A sealed run's record: `run.status`, `run.interruptReason`, and each file's `status`, `failureDetails`, and `artifacts`                                                                                                |
+| `runs/<run-id>/manifest.json`   | Every other file in the bundle, with its `sha256` and `bytes`                                                                                                                                                          |
+| `runs/<run-id>/provenance.json` | The run's CI, source, runtime, and redaction facts                                                                                                                                                                     |
+| `runs/<run-id>/files/`          | The run's `logs/`, `artifacts/`, and `setup/` files. Each `artifacts[].path` in `run.json` points here, relative to the product directory                                                                              |
+| `latest.json`                   | The record of the last run that Testkit finished writing up, with its publication and retention results. A run killed after it was sealed can be in `runs/` but not here, so `runs/<run-id>/run.json` is the authority |
+| `live.json`                     | The record of a run that isn't sealed, with `run.status` `running`                                                                                                                                                     |
+| `logs/`, `artifacts/`, `setup/` | The files that unsealed run has written so far                                                                                                                                                                         |
+
+Anything else under `.testkit/` can change between releases, including
+`objects/`, which stores the bytes behind each bundle's files.
+
+A run is sealed once `runs/<run-id>/` exists. Testkit writes the bundle under a
+hidden name in `runs/`, writes `manifest.json` last, and then renames the
+directory, so `runs/<run-id>/` is never partly written. Ignore names in `runs/`
+that start with `.`. A copy of a bundle, such as a CI upload, is whole when
+every file that its `manifest.json` lists has the listed `sha256`. A sealed
+`run.json` has `archive.status` `complete` and `run.status` `passed`, `failed`,
+or `interrupted`.
+
+`live.json` means a run is in progress, or its process died before Testkit
+finished with it. If `runs/<run-id>/` exists for the `run.id` in `live.json`,
+the run was sealed and the bundle is its record: `live.json` and the active
+directories are leftovers, which the next `testkit run`, `cleanup`, or `destroy`
+removes. Testkit replaces `live.json` whole on each update, so it always parses.
+Its `generatedAt` is the time of the last update, and each file's `status` is
+what it was then, so a file that was still running shows `not_run`. The files
+in `logs/`, `artifacts/`, and `setup/` aren't redacted until the run is sealed.
+
+How an unfinished run gets sealed:
+
+- When Ctrl-C, `SIGTERM`, or `testkit stop` interrupts the run, or its process
+  exits early, Testkit seals it straight away. `run.status` is `interrupted`,
+  or `failed` when nothing asked the run to stop, and `run.interruptReason`
+  says why.
+- When the process is killed with `SIGKILL`, by the out-of-memory killer, or
+  with its host, the run stays unsealed until the next `testkit run`,
+  `cleanup`, or `destroy` seals it, before doing anything else, with
+  `run.status` `interrupted` and `run.interruptReason`
+  `stale run process not active`. `testkit stop` seals it too, with its
+  `--reason` or `stop requested`. The sealed `run.finishedAt` is when the
+  command sealed it, not when the process died.
+
+Testkit keeps what reached the disk. It can't keep output that a process hadn't
+written yet, anything written after the disk filled up or became read-only, or
+work that a killed process would have done on its way out. A log can end
+mid-line.
+
+For example, to see what failed in the run that `latest.json` names and check
+its files:
+
+```sh
+cd .testkit/results
+run=runs/$(jq -r .run.id latest.json)
+jq '.run.status, .run.interruptReason' "$run/run.json"
+jq '.groups[].suites[].files[] | select(.status != "passed") | {path, status, failureDetails, artifacts: [.artifacts[].path]}' "$run/run.json"
+jq -r '.files[] | "\(.sha256)  \(.path)"' "$run/manifest.json" | (cd "$run" && sha256sum --check --quiet)
+```
+
 ## Authoring
 
 ### Named endpoints and databases
@@ -1044,6 +1241,14 @@ run's results, artifacts, and events, and the capture refuses any other
 operation. When Testkit releases the file's environment, the capture closes and
 the handle expires. Calling a handle never starts a sidecar or a service.
 
+The capture's `url` holds a second unguessable segment, which Testkit also
+keeps out of the run's records. The capture records a request only when its
+path starts with that segment, and answers any other path with 404. A captured
+request's `path` leaves the segment out: a request to `url` records `/webhook`,
+and one to `url` + `/42` records `/webhook/42`. The capture answers 403 to a
+request whose `Host` header isn't `127.0.0.1:<port>`, which keeps a web page
+from reaching it through DNS rebinding.
+
 - A name with no handle throws `EnvironmentValueMissingError` with `kind`
   `"handle"`, and the test ends as an infrastructure failure, as for a missing
   endpoint.
@@ -1068,7 +1273,8 @@ test, in any order.
   so read them and leave them unchanged.
 - When the test ends, leave its rows in place. Testkit resets the databases it
   provisions. By default, every run starts from a fresh clone of the template
-  database. See [`database.reset`](testkit-config-schema.md#database).
+  database. See `database.reset` in the `database` section of
+  [`testkit-config-schema.md`](https://app.unpkg.com/@gfdelarue/testkit/files/testkit-config-schema.md).
 - Clean up only what Testkit doesn't own, such as an account in a third-party
   sandbox. Register the cleanup as soon as the test creates the account. Give
   the account a unique name, so that a leftover from a cleanup that never ran
@@ -1125,8 +1331,24 @@ Files that name the same lock never run at the same time within one run.
 Testkit doesn't share locks between runs, such as two CI jobs. Two tests that
 need a lock because they share rows need their own rows instead.
 
+A plain Vitest file names its locks in its group's `requirements`:
+
 ```ts
-export const testkit = defineFile({ engine: "node-vitest", locks: ["payments-sandbox-webhook"] });
+groups: {
+  payments: {
+    roots: ["src/payments"],
+    uses: ["api"],
+    requirements: {
+      files: [{ path: "src/payments/webhook.test.ts", locks: ["payments-sandbox-webhook"] }],
+    },
+  },
+},
+```
+
+A browser file can name them in `defineFile`:
+
+```ts
+export const testkit = defineFile({ engine: "playwright", locks: ["payments-sandbox-webhook"] });
 ```
 
 ### Node setup beside a test
@@ -1153,9 +1375,10 @@ invocation. Files without setup still batch.
 
 Setup runs with its own JavaScript state. It can use Node APIs, prepare
 external resources, and start HTTP capture listeners. Tests
-reach a capture by its `id` through [`handle()`](#handles). A capture's
-`requestsUrl` and `resetUrl` hold an unguessable segment that Testkit keeps out
-of the run's records, and its capture `path` may not start with `/__testkit__/`.
+reach a capture by its `id` through [`handle()`](#handles). A capture's `url`,
+`requestsUrl` and `resetUrl` hold unguessable segments that Testkit keeps out
+of the run's records. Its capture `path` may not start with `/__testkit__/` or
+contain `.` or `..` segments.
 The context contains `deadlineMs`, `signal`, `env`, `leaseDir`, `productDir`,
 `serviceName`, `testFile`, and `sidecars`. `serviceName` holds the name of the
 test's group. Setup has the same permissions as the Testkit process. It is not
@@ -1237,11 +1460,182 @@ test("lists one page of orders", async (context) => {
 - A failed budget fails its test when the test finishes. The failure detail has
   the kind `data-flow-budget` and a key made of the test's full title and the
   budget.
-- Testkit writes `data-flow.json` and `data-flow.md` for a file whose tests
+- Testkit writes `data-flow.json` and `data-flow-report.md` for a file whose tests
   recorded something. Each such test is one scenario, from its final attempt. A
   test that records nothing adds nothing, and a file whose tests record
   nothing gets no data-flow artifacts.
 
+### Slow the browser's network and CPU
+
+`emulateNetwork(page, conditions)` and `emulateCpu(page, slowdown)` from
+`@gfdelarue/testkit/playwright` slow a page the way Chrome DevTools'
+throttling does. A `ui` test can use them to fail when a change makes a page
+unusable on a slow connection or a slow device:
+
+```ts
+import { defineFile } from "@gfdelarue/testkit";
+import { emulateCpu, emulateNetwork, expect, test } from "@gfdelarue/testkit/playwright";
+
+export const testkit = defineFile({ engine: "playwright" });
+
+test("the dashboard is usable on a slow connection", async ({ page }) => {
+  await emulateNetwork(page, "slow-4g");
+  await page.goto("/dashboard");
+  await expect(page.getByRole("heading", { name: "Orders" })).toBeVisible({ timeout: 10_000 });
+});
+
+test("the dashboard is usable on a slow phone", async ({ page }) => {
+  await emulateCpu(page, 4);
+  await page.goto("/dashboard");
+  await expect(page.getByRole("heading", { name: "Orders" })).toBeVisible({ timeout: 10_000 });
+});
+```
+
+The assertion's timeout is the time limit. The helpers add no timing or
+metrics API.
+
+`emulateNetwork` takes a profile name or custom values. Each profile has the
+values of the DevTools preset of the same name in the Chromium that Testkit
+runs:
+
+| Profile     | DevTools preset | Download   | Upload     | Latency  |
+| ----------- | --------------- | ---------- | ---------- | -------- |
+| `"fast-4g"` | Fast 4G         | 8,100 kbps | 1,350 kbps | 165 ms   |
+| `"slow-4g"` | Slow 4G         | 1,440 kbps | 675 kbps   | 562.5 ms |
+| `"3g"`      | 3G              | 400 kbps   | 400 kbps   | 2,000 ms |
+
+DevTools renamed two presets in 2024: Slow 4G was Fast 3G, and 3G was Slow 3G.
+Custom values give speeds in kilobits per second and latency in milliseconds:
+
+```ts
+await emulateNetwork(page, { latencyMs: 300, downloadKbps: 400, uploadKbps: 200 });
+```
+
+`emulateCpu` makes the page's main thread, which runs its JavaScript and
+layout, `slowdown` times slower. DevTools' fixed CPU options are 4, 6, and 20.
+Testkit doesn't calibrate the slowdown to the machine, as DevTools' "Mid-tier
+mobile" and "Low-tier mobile" options do. `emulateCpu(page, 1)` restores full
+speed.
+
+- Call the helpers before `page.goto()`. Both settings last across navigations
+  until the page closes.
+- Neither setting reaches a cross-site iframe. Chromium runs one in a process
+  of its own, at full speed.
+- The network conditions apply to that page only. A popup it opens, or another
+  page, loads at full speed. Playwright's `browserContext.setOffline()` clears
+  them.
+- The CPU slowdown applies to the browser process that runs the page. A
+  same-site popup that keeps its `window.opener` shares that process and slows
+  down too, and closing it ends the slowdown. Call `emulateCpu` again after
+  closing one.
+- Like DevTools, `emulateNetwork` also sets `navigator.connection` until the
+  page navigates to another site.
+- An unknown profile name or field, a negative or non-finite value, a speed of
+  0, or a CPU slowdown outside 1 to 100 throws an error that names the value.
+
+Three things to keep in mind:
+
+- Set generous time limits. A CI runner has less CPU than a laptop, and a
+  [campaign](#run-a-campaign) files a failing test as a bug, so a tight limit
+  produces false bug reports.
+- A CPU slowdown multiplies the speed of the machine that runs the test, so 4
+  on a slow CI runner is much slower than 4 on a laptop. A time limit under a
+  CPU slowdown depends on the runner far more than one under network
+  conditions, which are the same on every machine.
+- Chromium holds each response for at least the latency and shares the
+  bandwidth among the page's requests, but it doesn't model TCP. The result
+  approximates a slow connection rather than reproducing one.
+
+### Check a ui test's browser traffic
+
+Testkit records the requests every `ui` test's pages send, with no change to the
+test. The record catches bugs that live in how a frontend uses its API, such as
+a checkout that sends its payment twice or a list page that fetches each row
+separately, even when no assertion checks for them.
+
+For each `ui` file whose tests sent requests, Testkit writes
+`browser-network.json` and `browser-network-report.md` from each test's final
+attempt. A test's section of the report looks like this:
+
+```md
+## checkout › pays for the cart (passed)
+
+21 requests, 452 KB received: script 312 KB, font 48 KB, document 41 KB, fetch 14 KB
+
+| Service | Request           | Count | Sent   | Received | Status |
+| ------- | ----------------- | ----- | ------ | -------- | ------ |
+| web     | GET /cart         | 1     | 0 B    | 41 KB    | 200    |
+| api     | GET /products/:id | 8     | 0 B    | 11 KB    | 200    |
+| api     | POST /payments    | 2     | 1.2 KB | 400 B    | 201    |
+
+Other origins: fonts.gstatic.com, 2 requests, 48 KB
+
+Leads:
+
+- `POST /payments` to api went out 2 times with the same body.
+```
+
+- Rows cover page loads and API calls, which are Playwright's `document`,
+  `fetch`, and `xhr` requests, to the services the test's group uses. A row
+  names the service rather than its URL, because each run gives services
+  different ports. Scripts, styles, images, and fonts count only toward the
+  totals by type. Requests to other origins appear by host name only.
+- A path's numbers, UUIDs, and hex strings of 16 or more characters become
+  `:id`, so eight product fetches make one row with a count of 8.
+- The record never holds query strings, headers, or bodies. Paths pass through
+  Testkit's redaction, and sealing redacts them again with the run's secrets.
+  To spot a repeated write, Testkit hashes each body in memory and keeps only
+  the count.
+- Sizes are body bytes as they crossed the network, so a compressed response
+  counts its compressed size and one that a `page.route()` handler fulfills
+  counts 0. Headers don't count.
+- Each test keeps 200 requests in detail, 100 rows, and 20 other origins. The
+  record counts the rest.
+- The leads point at two patterns: a POST, PUT, PATCH, or DELETE sent more than
+  once to the same URL with the same body, and a page load or API call that
+  failed or got a 4xx or 5xx status in a test that passed. A lead never fails a
+  test.
+- The record covers every context a test opens, including one from
+  `browser.newContext()`. It doesn't cover a context that a `beforeAll` hook
+  opens.
+
+To assert on the traffic, call `browserRequests()` from
+`@gfdelarue/testkit/playwright`. It returns the requests the test's pages have
+sent so far, oldest first:
+
+```ts
+import { browserRequests, expect, test } from "@gfdelarue/testkit/playwright";
+
+test("checkout charges the card once", async ({ page }) => {
+  await page.goto("/cart");
+  await page.getByRole("button", { name: "Pay" }).click();
+  await expect(page.getByText("Payment received")).toBeVisible();
+
+  const payments = (await browserRequests()).filter(
+    (request) => request.service === "api" && request.method === "POST" && request.path === "/payments",
+  );
+  expect(payments).toHaveLength(1);
+});
+```
+
+Each entry has `service`, the name of the service it went to or `null`,
+`method`, `url`, `path`, `resourceType`, `status`, `failure`, `requestBytes`,
+`responseBytes`, and `durationMs`. `path` is the URL's path as sent, without
+`:id`. Add up entries with plain array code, for example to check a page's
+weight:
+
+```ts
+const received = (await browserRequests()).reduce((total, request) => total + request.responseBytes, 0);
+expect(received).toBeLessThan(500_000);
+```
+
+`browserRequests()` waits up to 5 seconds for requests already in flight, so
+their entries have a status and sizes. It doesn't wait for EventSource streams.
+A request still unfinished after that has its status if the response's headers
+arrived, 0 response bytes, and a `durationMs` of `null`. A WebSocket connection
+appears with the `resourceType` `websocket` and no status, sizes, or duration.
+The record counts connections, not their messages.
+
 ## Discovery
 
 Testkit discovers plain Vitest test files and typed suites.
@@ -1373,7 +1767,7 @@ engine.
 Unsupported pairs fail discovery; for example, a `*.ui.testkit.ts` file cannot
 declare `engine: "node-vitest"`.
 
-See [docs/test-types.md](docs/test-types.md) for the canonical type model.
+See [`docs/test-types.md`](https://app.unpkg.com/@gfdelarue/testkit/files/docs/test-types.md) for the canonical type model.
 
 Test groups own test files by directory. Declare them under `groups` in
 `testkit.config.ts`. Each group lists its repo-relative `roots` and the services
@@ -1403,7 +1797,7 @@ export default defineConfig({
   are also available by name; see
   [Named endpoints and databases](#named-endpoints-and-databases).
 - `skip`, `requirements`, and `runtimeIsolation` are group fields. See the
-  [config reference](testkit-config-schema.md#groups).
+  `groups` section of [`testkit-config-schema.md`](https://app.unpkg.com/@gfdelarue/testkit/files/testkit-config-schema.md).
 
 Services own no test files. A config with `services` and no `groups` key
 fails to load when a service's `local.cwd` or `discovery.roots` holds a typed
@@ -1472,11 +1866,16 @@ Testkit ignores an old `.testkit/history/` directory and leaves it in place.
 `@gfdelarue/testkit` provisions Docker-managed local Postgres automatically for
 services that define `database: database.postgres(...)`.
 
-Docker is also the required Postgres client runtime for Testkit-owned database
-operations. Testkit runs `psql` and `pg_dump` inside the configured Postgres
-client image instead of using host-installed binaries, which keeps local runs
-consistent across Linux, macOS, and native Windows. Override the client image
-with `TESTKIT_POSTGRES_CLIENT_IMAGE` when needed.
+Docker is also the required Postgres client runtime. Testkit doesn't use
+host-installed `psql` or `pg_dump`, which keeps local runs consistent across
+Linux, macOS, and native Windows. Testkit's own operations on the database it
+owns, such as declaring roles and taking schema snapshots, run inside the
+database container. So the `image` that `database.postgres()` uses must include
+`psql` and `pg_dump`, with a `pg_dump` at least as new as its server. Your SQL,
+in `sql-file` steps and `database-steps` helpers, runs `psql` in a separate
+client container from `postgres:16`. A `pg_dump` of an external database runs
+in `postgres:<its major version>`. `TESTKIT_POSTGRES_CLIENT_IMAGE` overrides
+the image of those client containers.
 
 Template steps, schema snapshots, and `database.steps` helpers work the same
 under Docker Desktop, rootless Docker, and Docker-in-Docker. Clients for
@@ -1502,7 +1901,7 @@ one with `database(name)` from `@gfdelarue/testkit/environment`. Declared `env`
 `{dbPort}`, `{dbName}`, `{dbUser}`, `{dbPassword}`, and `{dbSsl}` tokens, with
 `:serviceName` to read the database of a service listed in `dependsOn`. Testkit
 resolves them from the database provisioned for the current run. They are
-env-only; see [`env`](testkit-config-schema.md#env).
+env-only; see the `env` section of [`testkit-config-schema.md`](https://app.unpkg.com/@gfdelarue/testkit/files/testkit-config-schema.md).
 
 `db schema refresh` forces a source database dump into the `.testkit` source
 schema cache. `db schema verify` prepares local templates and verifies local