# `Puck.Test`
[🔗](https://github.com/bradleygolden/puck/blob/v0.2.25/lib/puck/test.ex#L1)

Test utilities for deterministic agent testing.

Creates mock clients with queued responses that work across process
boundaries, with optional verification that all responses were consumed.

## Usage

    defmodule MyAgentTest do
      use ExUnit.Case, async: true

      setup :verify_on_exit!

      test "agent completes workflow" do
        client = Puck.Test.mock_client([
          %{action: "search", query: "test"},
          %{action: "done", result: "found"}
        ])

        assert {:ok, result} = MyAgent.run(client: client)
        assert result.action == "done"
      end
    end

# `mock_client`

Creates a mock client with queued responses.

Each call to `Puck.call/3` or `Puck.stream/3` pops the next response from
the queue. Works across process boundaries.

## Response Types

- Any term (struct, map, string) — returned as response content
- `{:error, reason}` — simulates backend error
- `fn messages -> response end` — dynamic response based on conversation

## Options

- `:default` - Response when queue exhausts (default: `{:error, :mock_responses_exhausted}`)
- `:model` - Model name for introspection (default: `"mock"`)

## Examples

    client = Puck.Test.mock_client([
      %{action: "search"},
      %{action: "done"}
    ])

    client = Puck.Test.mock_client([
      fn messages -> %{echo: length(messages)} end
    ])

    client = Puck.Test.mock_client([
      {:error, :rate_limited},
      %{action: "retry_succeeded"}
    ])

# `verify!`

Verifies all mock clients created by this process consumed all responses.

Raises `ExUnit.AssertionError` if any responses remain unconsumed.
Stops all tracked Agent processes.

## Example

    client = Puck.Test.mock_client([%{action: "done"}])
    Puck.call(client, "test", Puck.Context.new())
    Puck.Test.verify!()

# `verify_on_exit!`

ExUnit setup callback for automatic verification on test exit.

    setup :verify_on_exit!

---

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