Puck.Test (Puck v0.2.11)

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

Summary

Functions

mock_client(responses, opts \\ [])

Creates a mock client with queued responses.

verify!()

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

verify_on_exit!(context \\ %{})

ExUnit setup callback for automatic verification on test exit.

Functions

mock_client(responses, opts \\ [])

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!(context \\ %{})

ExUnit setup callback for automatic verification on test exit.

setup :verify_on_exit!