HTTP 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
Section titled “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
Section titled “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.
mise run testmise 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:recordmise run testEvery 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
Section titled “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_andgithub_pat_values, including dotted statelessghs_tokens; - legacy
v1.tokens, which need at least 20 characters after the prefix so version tags such asv1.24.0survive; - 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
Section titled “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.
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
Section titled “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
Section titled “Replaying a webhook to a local server”mise run server:replay /tmp/push.json push local-push-001The 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.
© 2026 Sweepy
