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.

  • Abandoned

    The client closed the body before it completed, as a recorded early stop replays.

A request and the reply that answers it.

pub type Exchange =
  @internal Exchange

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

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

  • NotPlayback

    The client was started by http_gun.start or cassette.record.

  • ClientStopped

    The 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 exchanges(script: Script) -> List(Exchange)

The exchanges of a script, in order.

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 reply(exchange: Exchange) -> Reply

The reply of an exchange.

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.

✨ Search Document