http_gun/testing
Starts offline clients that answer from a script of exchanges, to test
code that takes an http_gun.Client.
let assert Ok(req) = request.to("https://api.example.com/orders/7")
let script =
testing.script([
testing.exchange(
request.set_body(req, <<>>),
testing.Respond(
response.new(200) |> response.set_body([<<"{\"id\":7}">>]),
testing.Finished([]),
),
),
])
let assert Ok(client) = testing.playback(script, config.default())
let assert Ok(buffered) = http_gun.send(client, request.set_body(req, <<>>))
A playback client never opens a connection and ignores the destination
policy. Each request must match the next exchange: a mismatch fails with
PlaybackMismatch(position) and leaves the exchange in place, and a
request after the last fails with PlaybackExhausted. Concurrent
requests are matched in admission order.
Matching compares method, URL, headers and body bytes after the
configuration’s redaction (config.with_redaction) is applied to both
sides, so a redacted query parameter or body field matches any value.
Everything else is compared exactly. ignoring_headers skips headers
such as a timestamp or a signature, and matching replaces the
comparison.
exchange applies redaction.default() to the request it stores: it
drops the credential headers and replaces credential query parameters
and form or JSON body fields, so a script never holds a caller’s
credentials.
Types
How a scripted response body ends.
pub type Ending {
Finished(trailers: List(#(String, String)))
Aborted(error.Failure)
Abandoned
}
Constructors
-
Finished(trailers: List(#(String, String)))The body completed, with these trailers.
-
Aborted(error.Failure)The body failed after its chunks.
-
AbandonedThe client closed the body before it completed, as a recorded early stop replays.
A request that did not match the exchange at position. Both the
exchange’s request and the actual one are as match_key forms them, with
the script’s ignored headers removed, so they differ exactly where
matching saw a difference (unless matching replaced the comparison).
pub type Mismatch {
Mismatch(
position: Int,
expected: request.Request(BitArray),
actual: request.Request(BitArray),
)
}
Constructors
-
Mismatch( position: Int, expected: request.Request(BitArray), actual: request.Request(BitArray), )
How a scripted exchange answers.
pub type Reply {
Respond(
response: response.Response(List(BitArray)),
ending: Ending,
)
Reject(error.Failure)
}
Constructors
-
Respond( response: response.Response(List(BitArray)), ending: Ending, )Respond with a status, headers and body chunks, then end.
-
Reject(error.Failure)Fail before any response, for example with a connection failure.
Ordered exchanges and the way requests are matched against them.
pub type Script =
@internal Script
What a playback client met that did not match its script. A client whose
requests all matched and whose exchanges were all used reports
Verdict([], [], [], 0).
pub type Verdict {
Verdict(
mismatched: List(Mismatch),
exhausted: List(request.Request(BitArray)),
unused: List(Exchange),
dropped: Int,
)
}
Constructors
-
Verdict( mismatched: List(Mismatch), exhausted: List(request.Request(BitArray)), unused: List(Exchange), dropped: Int, )Arguments
- mismatched
-
Requests that did not match the next exchange, oldest first: the first 64.
- exhausted
-
Requests that arrived after the last exchange, oldest first, in the same form: the first 64.
- unused
-
Exchanges not used yet, in order; none once a repeating script has completed a pass.
- dropped
-
Refusals of either kind beyond the first 64 of each, which the client counted but did not keep.
Why verify has no verdict.
pub type VerifyError {
NotPlayback
ClientStopped
}
Constructors
-
NotPlaybackThe client was started by
http_gun.startorcassette.record. -
ClientStoppedThe client has stopped; ask before
http_gun.stop.
Values
pub fn exchange(
request: request.Request(BitArray),
reply: Reply,
) -> Exchange
Pair an expected request with its reply.
pub fn ignoring_headers(
script: Script,
names: List(String),
) -> Script
Leave these headers, compared without case, out of matching on both sides, for values that change on every run such as a date or a signature.
pub fn match_key(
redaction: redaction.Redaction,
request: request.Request(BitArray),
) -> request.Request(BitArray)
The form of a request that playback compares: redaction applied, the
method in one spelling (Other("GET") as Get), the host lowercased, an
empty path as /, header names lowercased and headers sorted by name.
pub fn matching(
script: Script,
compare: fn(
request.Request(BitArray),
request.Request(BitArray),
) -> Bool,
) -> Script
Replace the exact comparison. compare receives the expected and the
actual request as match_key forms them: redacted, normalised, without
ignored headers.
pub fn playback(
script: Script,
settings: config.Config,
) -> Result(http_gun.Client, http_gun.StartError)
Start an offline client that answers from script. The script is checked
first: statuses must be 200..599, bodies whole bytes, and the whole
script within 16 MiB.
Each call starts a client with its own cursor at the first exchange.
The immutable Script can be reused to start independent clients. Views
made from one client share its cursor; changing correlation does not create
another replay or affect matching. Stop each started client separately.
pub fn repeating(script: Script) -> Script
Start again at the first exchange after the last, so a non-empty script
is never exhausted: a test that answers every request with the same built
failure needs one exchange, with matching accepting any request.
Positions stay within the script, and once a pass has completed verify
reports no unused exchange. Like ignoring_headers, this is a playback
setting that cassette.encode does not store.
pub fn request(exchange: Exchange) -> request.Request(BitArray)
The expected request of an exchange, as stored.
pub fn script(exchanges: List(Exchange)) -> Script
A script of exchanges, matched in order and exactly.
pub fn verify(
client: http_gun.Client,
) -> Result(Verdict, VerifyError)
Report what this playback client met so far that did not match its
script. The caller’s code sees PlaybackMismatch and PlaybackExhausted
as before; verify lets a test fail on them even when that code handled
the failure, and on exchanges it never used. Views of one client share
one report. The client keeps the first 64 refused requests of each kind
until it stops and counts the rest in dropped.