FakeHttpTransport
A scripted HttpTransport for tests: stubs of a RequestMatch and a script of Steps, a call log with virtual stamps, and the two transport behaviours it mirrors. It is the worked example of the HttpTransport seam, written to be read: the @OptIn(ExperimentalForInheritanceWebToolsApi::class) on this class is exactly the line a consumer's own implementation needs.
Stable Core, source compatibility only. The fixtures and webtools-http are released and versioned together: the fixtures call the module's internal members, and Gradle resolves both from one component. Equality is identity. toString() prints the stub count, the call count and the closed flag, nothing else.
The contract it keeps:
Lookup: the most recently added stub whose match accepts the request wins, so a shared set-up registers defaults and a test overrides one path by adding a stub later.
Script: a stub's steps run in order and the last repeats; each stub has its own cursor.
Recording: every call is recorded under the lock before any delay, with RecordedCall.receivedAt the time elapsed on the injected TimeSource since construction; a request cancelled during its delay still counts. A call that arrives after close is not recorded and consumes no step.
Delay:
delay(step.delay)runs in the caller's context, so it is virtual when the caller runs on the test scheduler (underrunTest, or on VirtualClock.dispatcher) and real otherwise. Cancellation throwsCancellationException, never aResult.Unmatched: the call is recorded with
matched = false, then UnmatchedRequestError is thrown (anError: it passes through a cache loader to each waiter and fails the test with the method, the redacted URL and the stub count). Unmatched.Respond is the opt-in for a lenient fake. Nothing is defaulted to a404.Fidelity: a respond or fixture step builds
HttpResponse(status, request.url) { headers; body }; a lambda step returns its own response. With maxResponseBytes set, a response whose declaredContent-Length(a non-empty run of digits that parses as a non-negativeLong, else ignored) or body is above the cap becomesResult.failure(TransportFailure.BodyTooLarge(cap, declared)). The cap follows the transport's no-body rule: it is not applied to a response toHEADor to a1xx,204or304status. After close every call returnsResult.failure(HttpFailure.Closed("transport")).Not mirrored: URL policy, DNS, TLS, redirects and timeouts belong to the real transport.
Exceptions from the consumer's matcher or lambda propagate out of execute (a test-authoring error); they are not wrapped in the
Result. A matcher that throws leaves the call unrecorded.
Thread-safety: one lock guards the stubs, every cursor, the call log and the closed flag, and is never held across a suspension; a matcher runs under it (re-entrant on the same thread; one that blocks would block other callers). execute may be called concurrently from many coroutines and never blocks a thread (contract point 8). calls, unmatchedCalls and callsMatching return snapshots.
Parameters
the source of RecordedCall.receivedAt; TimeSource.Monotonic by default, VirtualClock.timeSource for virtual stamps.
the body cap to mirror, or null (the default) for none; not negative.
what to do with a request no stub matches; Unmatched.Fail by default.
Throws
if maxResponseBytes is negative.