FakeHttpTransport

class FakeHttpTransport(timeSource: TimeSource = TimeSource.Monotonic, maxResponseBytes: Long? = null, unmatched: Unmatched = Unmatched.Fail) : HttpTransport(source)

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 (under runTest, or on VirtualClock.dispatcher) and real otherwise. Cancellation throws CancellationException, never a Result.

  • Unmatched: the call is recorded with matched = false, then UnmatchedRequestError is thrown (an Error: 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 a 404.

  • 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 declared Content-Length (a non-empty run of digits that parses as a non-negative Long, else ignored) or body is above the cap becomes Result.failure(TransportFailure.BodyTooLarge(cap, declared)). The cap follows the transport's no-body rule: it is not applied to a response to HEAD or to a 1xx, 204 or 304 status. After close every call returns Result.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

timeSource

the source of RecordedCall.receivedAt; TimeSource.Monotonic by default, VirtualClock.timeSource for virtual stamps.

maxResponseBytes

the body cap to mirror, or null (the default) for none; not negative.

unmatched

what to do with a request no stub matches; Unmatched.Fail by default.

Throws

Constructors

Link copied to clipboard
constructor(timeSource: TimeSource = TimeSource.Monotonic, maxResponseBytes: Long? = null, unmatched: Unmatched = Unmatched.Fail)

Properties

Link copied to clipboard

Every call received so far, in arrival order, matched or not; a snapshot.

Link copied to clipboard

Whether close has been called.

Link copied to clipboard

The recorded calls no stub matched; a snapshot.

Functions

Link copied to clipboard

The recorded calls whose request match accepts.

Link copied to clipboard
open override fun close()

Closes the fake: idempotent, never throws; every later call returns Closed("transport").

Link copied to clipboard
open suspend override fun execute(request: HttpRequest): Result<HttpResponse>

Plays the script for request.

Link copied to clipboard
fun on(match: RequestMatch, vararg steps: Step): FakeHttpTransport

Adds a stub: requests match accepts are answered by steps, in order, the last repeating. A stub added later wins over an earlier one that also matches.

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

A diagnostic string for logs: the stub count, the call count and the closed flag, nothing else. Its format is not part of the API and may change.