livery.forge.testing._cassette¶
livery.forge.testing._cassette ¶
Record and replay HTTP exchanges over urllib, with secrets scrubbed.
A cassette is an ordered list of request and response pairs, stored as JSON. Recording sends real requests through urllib and appends each exchange; replaying answers the same requests from the file, in order, with no network at all. The replayed run therefore proves the caller makes the requests the recording made, byte for byte, and CI needs no credentials and no server.
Secrets never reach disk: the caller names them at record time and every occurrence in the URL and both bodies is replaced before the exchange is stored. Request headers are not stored at all, which is where tokens actually travel.
The seam is any object with open(request, *, timeout): a backend
that takes its opener as a constructor argument records with
livery.forge.testing.RecordingOpener, replays with
livery.forge.testing.ReplayOpener, and cannot tell either from the
real thing. The file format is documented in the package's
docs/fixtures.md.
Classes:
| Name | Description |
|---|---|
CassetteError |
Raised when replay and recording disagree. |
UrlOpener |
Anything that opens a urllib request: the one seam of this module. |
Exchange |
One recorded request and its response, secrets already scrubbed. |
Cassette |
An ordered recording of HTTP exchanges, loadable and savable as JSON. |
RecordingOpener |
An opener that performs real requests and records each exchange. |
ReplayOpener |
An opener that answers from a cassette, in order, with no network. |
Attributes:
| Name | Type | Description |
|---|---|---|
REDACTED |
|
|
VOLATILE |
|
|
FORMAT |
|
CassetteError ¶
Bases: Exception
Raised when replay and recording disagree.
The message names the request that arrived and the exchange the cassette holds, verbatim, so the drift is readable without re-running anything.
UrlOpener ¶
Bases: Protocol
Anything that opens a urllib request: the one seam of this module.
urllib's own OpenerDirector satisfies it, and so do livery.forge.testing.RecordingOpener and livery.forge.testing.ReplayOpener, which is what lets a backend take its opener as a constructor argument and never know whether the network is real.
Methods:
| Name | Description |
|---|---|
open |
Open request and return a urllib response object. |
open ¶
Exchange
dataclass
¶
Exchange(method: str, url: str, request_body: str, status: int, reason: str, content_type: str, response_body: str, location: str = '')
One recorded request and its response, secrets already scrubbed.
Attributes:
| Name | Type | Description |
|---|---|---|
method |
str
|
The HTTP method. |
url |
str
|
The full URL, scrubbed. |
request_body |
str
|
The request body as text, scrubbed. Empty when the request had none. |
status |
int
|
The HTTP status code of the response. |
reason |
str
|
The status line's reason phrase. |
content_type |
str
|
The response's Content-Type header value. |
response_body |
str
|
The response body as text, scrubbed. |
location |
str
|
The Location header of a refused redirect, scrubbed. Empty for every other exchange. Carried so a caller that deliberately follows one refused redirect (a signed log URL) can do so from the replayed refusal too. |
Cassette ¶
An ordered recording of HTTP exchanges, loadable and savable as JSON.
Attributes:
| Name | Type | Description |
|---|---|---|
exchanges |
list[Exchange]
|
The exchanges, in the order they happened. |
Hold exchanges, empty by default for a fresh recording.
Methods:
| Name | Description |
|---|---|
load |
Read the cassette at path. |
save |
Write the cassette to path, creating parent directories. |
Source code in packages/forge/src/livery/forge/testing/_cassette.py
load
classmethod
¶
Read the cassette at path.
Raises livery.forge.testing.CassetteError when the file's format number is not the one this module writes.
Source code in packages/forge/src/livery/forge/testing/_cassette.py
save ¶
save(path: Path) -> None
Write the cassette to path, creating parent directories.
Source code in packages/forge/src/livery/forge/testing/_cassette.py
RecordingOpener ¶
RecordingOpener(cassette: Cassette, *, secrets: tuple[str, ...] = (), volatile_bodies: tuple[str, ...] = (), scrub_fields: tuple[str, ...] = (), inner: UrlOpener | None = None)
An opener that performs real requests and records each exchange.
Wrap the opener a backend would use, run the operations once against the real server, then save the cassette. Every value in secrets is scrubbed from URLs and bodies before an exchange is stored, and request headers are never stored.
HTTP errors are recorded like any other exchange and re-raised, so the recording captures refusals as faithfully as successes.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
cassette
|
Cassette
|
The cassette exchanges are appended to. |
required |
secrets
|
tuple[str, ...]
|
The values that must never reach disk. Pass every token the recorded client holds. |
()
|
scrub_fields
|
tuple[str, ...]
|
JSON field names whose string values are redacted in stored response bodies: the secrets the server mints inside its answers, which no secret list can know in advance. |
()
|
inner
|
UrlOpener | None
|
The opener that actually talks to the network. The redirect-refusing default when omitted, never urllib's stock opener: following a redirect would forward the Authorization header to the new location, and a recording session holds real credentials. |
None
|
Record through inner into cassette, scrubbing secrets.
A request whose URL contains any volatile_bodies substring has a nondeterministic body (an encrypted payload); it is stored as the VOLATILE marker and matched by method and URL alone on replay.
Methods:
| Name | Description |
|---|---|
open |
Send request, record the scrubbed exchange, answer as urllib does. |
Attributes:
| Name | Type | Description |
|---|---|---|
cassette |
|
Source code in packages/forge/src/livery/forge/testing/_cassette.py
open ¶
Send request, record the scrubbed exchange, answer as urllib does.
Source code in packages/forge/src/livery/forge/testing/_cassette.py
ReplayOpener ¶
An opener that answers from a cassette, in order, with no network.
Each request must match the next recorded exchange on method, URL, and body, after the same scrubbing the recording applied. A mismatch or an exhausted cassette raises livery.forge.testing.CassetteError naming both sides, because a drifted request is the finding, not a nuisance.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
cassette
|
Cassette
|
The recording to answer from. |
required |
secrets
|
tuple[str, ...]
|
The values the replaying client holds where the recording held real ones. Scrubbed from incoming requests before matching, so a dummy token replays against a recording made with a real one. |
()
|
Replay cassette, scrubbing secrets from incoming requests.
Methods:
| Name | Description |
|---|---|
verify_exhausted |
Raise unless every recorded exchange was replayed. |
open |
Answer request from the next recorded exchange. |
Attributes:
| Name | Type | Description |
|---|---|---|
remaining |
int
|
How many recorded exchanges have not been replayed yet. |
Source code in packages/forge/src/livery/forge/testing/_cassette.py
verify_exhausted ¶
Raise unless every recorded exchange was replayed.
A leftover exchange means the caller stopped making a request the recording made, which is drift in the quiet direction.
Source code in packages/forge/src/livery/forge/testing/_cassette.py
open ¶
Answer request from the next recorded exchange.