# HTTP fixtures

> How Count Patchula's tests replay recorded HTTP cassettes offline, and how to record and check new fixtures.

Production code accepts a `patchula_http::Transport`, which takes a reqwest `Request` built with `Request::new`, so building a request needs no client. `patchula-testkit` belongs only in dev-dependencies. Replay holds only the cassette data, match options and a consumption cursor, with no reqwest client and no fallback transport. An unmatched request fails as an ordinary transport error, and `assert_finished` catches interactions no request consumed. A test passes a panicking network factory and an unresolvable `.invalid` host to prove replay never reaches the network.

## Cassettes

JSON cassettes live under `fixtures/`, one per scenario, with a schema version, provenance, requests and responses. Bodies are parsed JSON, so they diff well and ignore key order, or UTF-8 text; binary and streaming bodies fail. Requests match on the method, sanitised URL, selected headers and the complete body, including GraphQL query and variables. The default headers are `Accept`, `Content-Type`, `If-None-Match`, `If-Modified-Since` and `X-GitHub-Api-Version`, and callers can replace the list. Repeated identical requests consume successive interactions, and `Replay::assert_finished` catches unused ones.

## Recording

Replay is the default. `from_env` calls the network factory only when `PATCHULA_RECORD=1`, which ordinary tests and CI never set. Recording starts a fresh scenario and saves atomically after each exchange, so a failure can leave a partial recording: review the diff and replay before committing.

```console
mise run test
mise run fixtures:check
# For real GitHub recordings, provide GITHUB_TOKEN in the invoking environment.
# Never put its value in command arguments, fixtures, or logs.
mise run fixtures:record
mise run test
```

Every real cassette must say it was recorded by patchula, with the endpoint URLs. Simulated rate-limit and transport responses are labelled as such. Never import another bot’s fixtures, including Renovate’s.

## Redaction

Redaction happens before anything is written:

- authorization and cookie headers, and sensitive JSON keys;
- URL credentials and token, key and signature query parameters;
- GitHub tokens anywhere: `ghp_`, `ghs_`, `gho_`, `ghu_`, `ghr_` and `github_pat_` values, including dotted [stateless `ghs_` tokens](https://github.blog/changelog/2026-04-24-notice-about-upcoming-new-format-for-github-app-installation-tokens/);
- legacy `v1.` tokens, which need at least 20 characters after the prefix so version tags such as `v1.24.0` survive;
- the recording token itself, as a literal, and any literals or patterns a caller adds through `Redactor`.

The in-memory response a recording test sees is not redacted. The scanner (`mise run fixtures:check`, also part of `mise run ci`) checks raw and parsed JSON, escaped tokens, nested fields and URLs, and accepts extra literals as comma-separated values in `PATCHULA_REDACT`. Failures name the cassette without printing the match.

## Stateful GitHub tests

Tests that simulate GitHub repository state — branches, commits, pulls, discovery listings — share one in-memory fake, `patchula_testkit::github::FakeGitHub`, instead of per-test transport scripts. The fake answers the REST and GraphQL routes the client calls, applies writes to its state, and scripts faults through `on(Matcher)`. Its pulls listing honours `state`, `sort=created`, `direction`, `per_page` and `page` with GitHub’s documented defaults and panics on parameters it does not model, and `repository.pullRequests` resolves `headRefName`/`states`/`orderBy` filtering with `first`/`after` paging. `Hosts` fronts it for a test’s other endpoints — OSV, npm, registries — so one transport covers a whole run.

Every request the fake sees feeds a per-test transcript: the request multiset is normalised, hashed and compared against `tests/transcripts.tsv` beside the suite. `mise run transcripts:snapshot` rewrites the snapshots; a request change that leaves the snapshot stale fails the test, so a port that alters what a suite asks is a deliberate, reviewed diff.

`settings.latency` sleeps a fixed time on Tokio’s paused clock before the fake answers, and `Hosts::set_latency` charges the same latency on the scripted routes, so one knob times a whole run. Virtual elapsed time divided by that latency is the run’s depth — the round trips on its critical path. Depth pins live beside the transcripts in `tests/depth.tsv` (a warm lookup, a no-op real run, and full writes of one and three plans) and the pin is exact: every repetition ends the pinned number of waves after it began, and an elapsed that does not divide by the latency fails too — a wobble means a wait reached the run without the clock seeing it, not noise to tolerate. A deterministic extra request moves the pin a wave and fails it the way a changed request fails a transcript; so does an improvement. `mise run transcripts:snapshot` rewrites both files.

Exactness is a property of the runtime, not a tolerance in the check. Tokio’s paused clock auto-advances when the runtime looks idle, and a wait on a `std::thread` is invisible to it: the cache serves SQLite through worker threads behind a channel, and while a reply was in flight the clock could jump — whether a later request landed before or after an earlier request’s latency then depended on real scheduling, and a measured wave slipped either way. `patchula-cache`’s `paused-clock` feature, enabled only by the dev-dependencies of the crates whose tests pin depth, runs each cache call’s send and reply wait inside `tokio::task::spawn_blocking`, which a current-thread runtime counts as work: the clock holds until the reply arrives, and every wait on the run’s path is either a virtual timer on the latency grid or a held real wait. What depth never changes is the transcript’s job: the request multiset still pins exactly which requests each test makes. And a write pin’s depth is mostly the governor’s one-second write pacing, not round trips — a read that fits inside a pacing window adds no wave.

## mise

A subprocess has no HTTP cassette. mise lookups run through `patchula_process::Executor`, and tests swap in `patchula_testkit::MiseReplay`, which answers from `fixtures/mise/listings.json`: for each command after `mise` (such as `ls-remote --json --prerelease -- jq`), the JSON mise printed or the error it failed with. The replay keeps every command with its environment and working directory, so tests can assert the sandbox. A lookup missing from the fixture fails the test; replay never runs mise.

`mise run fixtures:record-mise` runs the pinned mise through `MiseRecorder` and rewrites the file. It needs the network, a `mise` on `PATH` and `GH_TOKEN`, which mise gets as it would in production and which is never written down. `mise run fixtures:check` scans these files with the cassettes.

## gh-actions-lock

`gh-actions-lock` is a real subprocess with real TLS, not an HTTP client the replay transport can stand in for, so its tests run it behind a loopback HTTPS CONNECT proxy (`GitHubProxy` in `crates/tools/src/lockfiles/tests/real_actions_lock.rs`). The proxy accepts `api.github.com:443` and refuses every other target, terminates TLS with a certificate `rcgen` mints for the test, and answers each request from the same cassette format as everything else, recorded with the same `PATCHULA_RECORD=1` flow and the same redaction — the token reaches the tool as `GH_TOKEN` and is redacted before a cassette is written. The suite also exercises the tool’s real flag contract against a frozen lockfile: `--no-interactive --no-onboard --no-narrow --ignore-local-actions --json=valid,findings` over an already-listed workflow exits 0 with `valid: true` and changes nothing.

## Replaying a webhook to a local server

```sh
mise run server:replay /tmp/push.json push local-push-001
```

The `server:replay` task signs a recorded payload with your webhook secret and posts it to a loopback listener. It prints only the HTTP status and refuses non-loopback targets. Set only one of `PATCHULA_WEBHOOK_SECRET_FILE` and `PATCHULA_WEBHOOK_SECRET` when you use it. A repeated delivery ID is accepted but ignored, so use a new ID to trigger again.
