FixtureRecorder

class FixtureRecorder(val directory: Path, gate: RecordingGate.Enabled, val redaction: Redaction = Redaction(), val warnAboveBytes: Int = DEFAULT_WARN_ABOVE_BYTES)(source)

Records the responses a live transport returns as .http fixture files, so a later test replays them through FakeHttpTransport (Step.fixture(FixtureLoader().load(...))). wrap decorates any HttpTransport; each successful response (any status) is serialised, redacted, scrubbed and written; a failure is not recorded; the delegate's result is returned untouched.

Stable Core, source compatibility only. Constructible only from a RecordingGate.Enabled, so recording never happens unless WEBTOOLS_HTTP_RECORD allowed it and no CI variable was present (RecordingGate.evaluate); the consumer's build declares that variable as an input of its test tasks (see the gate's KDoc) or Gradle skips the tests as up to date when only the variable changed. Equality is identity. toString() prints the directory, the mode and the three counts.

What is written: one comment # request: <METHOD> <scheme>://<host>[:<port>]<path>[?<redacted, sorted query>], the status line, the response headers in order with Set-Cookie, Set-Cookie2, Transfer-Encoding, Connection and Keep-Alive dropped and the value of every sensitive entry (HttpHeaders.Entry.isSensitive, or a name whose tokens are sensitive: key, token, secret, auth, signature, session, ...) replaced by the placeholder, then the body bytes. Request headers are never written. Every secret of the Redaction is replaced in the whole file; a file in which a form of one survives is refused, never written. The survival search is a backstop over the exact raw and encoded forms (and the full percent-escape of the secret's bytes), not a decoder of transformed forms. Body redaction beyond exact supplied secrets is not done: a key in transformed form (base64, hashed, truncated, or percent-escaped only in part, e.g. SECRET%2dCANARY for SECRET-CANARY) is neither replaced nor detected, and personal data in a recorded body is a review task before the file is committed.

The file is <directory>/<group>/<method>-<path slug>-<8 hex>.http (the hash over the method, the path and the redacted sorted query, so a rotated key or a reordered query lands on the same file) or <directory>/<group>/<name>.http when nameFor names it. RecordMode.New keeps an existing file, RecordMode.Overwrite rewrites it (byte-identical for an unchanged response: no timestamp is written). Writes go to a temporary file in the target directory and are moved into place with an atomic move where the file system supports one (otherwise a plain replace).

Threading: serialisation, scrubbing and the write run in withContext(Dispatchers.IO), so the caller's thread never blocks (transport contract point 8). written, kept and refused are thread-safe snapshots. An I/O failure or a surviving secret never reaches the caller: it lands in refused with a WARN log line, and the delegate's result is still returned. Cancellation is thrown. The recorder logs the target path, a size and, for an I/O failure, the exception's class name with the exception attached to the event for its stack trace (an I/O exception's message is a path); a scrubber refusal attaches nothing. Never a header, body, query or secret.

Parameters

directory

the root directory of the fixture files, for example the consumer's src/test/resources/fixtures.

gate

the gate; obtainable only from RecordingGate.evaluate.

redaction

what to hide; the default redacts by token with no secrets.

warnAboveBytes

the body size above which a WARN suggests a trimmed, hand-edited fixture; DEFAULT_WARN_ABOVE_BYTES by default. The file is still written.

Throws

Constructors

Link copied to clipboard
constructor(directory: Path, gate: RecordingGate.Enabled, redaction: Redaction = Redaction(), warnAboveBytes: Int = DEFAULT_WARN_ABOVE_BYTES)

Types

Link copied to clipboard
object Companion

The defaults.

Properties

Link copied to clipboard

The root directory of the fixture files.

Link copied to clipboard
val kept: List<Path>

The existing files kept untouched under RecordMode.New; a snapshot.

Link copied to clipboard

How an existing file is treated, from the gate.

Link copied to clipboard

What is hidden in the files.

Link copied to clipboard

The files refused (a surviving secret or an I/O failure); a snapshot.

Link copied to clipboard

The body size above which a write is logged at WARN.

Link copied to clipboard

The files written so far; a snapshot.

Functions

Link copied to clipboard
open override fun toString(): String

A diagnostic string for logs: the directory, the mode and the counts of files written, kept and refused. Its format is not part of the API and may change.

Link copied to clipboard
fun wrap(delegate: HttpTransport, group: String, nameFor: (HttpRequest) -> String? = { null }): HttpTransport

Decorates delegate: every successful response it returns is recorded under <directory>/<group>/.