# `HTTP.Test`
[🔗](https://github.com/gsmlg-dev/http_fetch/blob/v1.0.0-rc.9/apps/http_test/lib/http/test.ex#L1)

Owner-isolated fixtures for HTTP Family requests.

    HTTP.Test.expect(:service, fn request ->
      HTTP.Test.json(%{path: request.url.path})
    end)
    response = HTTP.fetch("https://service.test/items", adapter: {HTTP.Test, :service})
               |> HTTP.Promise.await()
    HTTP.Test.verify!()

Fixtures belong to the process that registers them. Tasks inherit their caller
chain; authorize an independent GenServer with `allow/3`. Stub and expectation
modes are mutually exclusive per owner/name. Expectations are claimed atomically
in registration order; cancellation does not restore a claimed call.

Call `verify_on_exit!/0` in ExUnit setup. Verification freezes claims, cancels
and joins simulated resources with a finite budget, then checks counts and
callback failures. Callback exceptions retain their cause and stacktrace and
fail verification even when a Promise was never awaited. Intentional
`transport_error/1` fixtures are ordinary client failures.

This adapter performs one request attempt. Manual redirects are exposed; error
redirects fail with `:redirect`; follow candidates fail with
`{:unsupported_test_policy, :redirect_follow}`. Only 301/302/303/307/308 with a
binary Location are candidates. Default nonredirect fixtures work normally.
Default follow completion remains unsupported. Mock resource cleanup cannot
establish socket, TLS or pool behavior.

# `allow`

Authorizes `allowed` to use one fixture belonging to `owner`.

# `expect`

Registers an ordered expectation, consumed exactly `count` times (default one).

# `gate`

Waits at a cooperative response-header gate; abort returns an intentional client failure.

# `headers`

Replaces response headers, preserving duplicate fields and order.

# `html`

Builds a UTF-8 HTML response.

# `json`

Builds a JSON byte response; Fetch does not decode the body into a map.

# `plug`

Invokes an optional buffered Plug bridge with a finite body limit (default 1 MiB).

# `response`

Builds a buffered response, preserving ordered duplicate headers.

# `status`

Builds an empty response with the given status.

# `stream`

Creates a response using a real acknowledged `HTTP.Stream` inside a fixture.

Steps are binary/iodata chunks, `{:gate, observer, tag}`, or `{:error, reason}`.
A gate sends `{:http_test_gate, tag, producer, ref}` and waits for
`{:http_test_release, ref}`. Each following step begins only after the previous
chunk's acknowledgement. `trailers:` preserves field order. `observer:` receives
`{:http_test_stream, stream, producer}` for deterministic cleanup assertions.
The finite `timeout:` bounds each chunk and gate (default 5 seconds).

# `stub`

Registers a repeatable fixture in the current owner's namespace.

# `text`

Builds a UTF-8 text response.

# `transport_error`

Creates an intentional transport failure, subject to Fetch's error mode.

# `verify!`

Verifies and settles this owner's fixtures. Further claims are rejected.

# `verify_on_exit!`

Registers an ExUnit exit verifier with an opaque token that survives owner exit.

---

*Consult [api-reference.md](api-reference.md) for complete listing*