# `Alloy.Provider.Test`
[🔗](https://github.com/alloy-ex/alloy/blob/v0.10.1/lib/alloy/provider/test.ex#L1)

A scripted test provider that returns pre-configured responses in order.

Used for testing agent behavior without making HTTP calls. Start an Agent
process with a list of responses, then pass its pid in the config.

## Usage

    {:ok, pid} = Alloy.Provider.Test.start_link([
      Alloy.Provider.Test.text_response("Hello!"),
      Alloy.Provider.Test.text_response("Goodbye!")
    ])

    config = %{agent_pid: pid}

    {:ok, resp1} = Alloy.Provider.Test.complete([msg], [], config)
    # resp1 contains "Hello!"

    {:ok, resp2} = Alloy.Provider.Test.complete([msg], [], config)
    # resp2 contains "Goodbye!"

# `complete`

Pops the next scripted response from the agent.

Ignores `messages` and `tool_defs` -- they exist only to satisfy the
behaviour callback. Config must contain `:agent_pid`.

Returns `{:error, :no_more_responses}` when all responses have been consumed.

# `error_response`

```elixir
@spec error_response(term()) :: {:error, term()}
```

Builds a scripted `{:error, reason}` response.

# `slow_text_response`

```elixir
@spec slow_text_response(String.t(), non_neg_integer()) ::
  {:with_delay, non_neg_integer(), {:ok, Alloy.Provider.completion_response()}}
```

Builds a scripted response that sleeps for `delay_ms` milliseconds before
returning. Useful for testing that callers remain responsive during long
LLM turns.

# `start_link`

```elixir
@spec start_link(ok: Alloy.Provider.completion_response(), error: term()) ::
  {:ok, pid()}
```

Starts an Agent process holding the list of scripted responses.

Returns `{:ok, pid}` where the pid should be placed in the config
as `:agent_pid`.

# `stream`

Streams the next scripted response, calling `on_chunk` for each character
of text content. For tool_use responses, returns the response without
streaming. Consumes from the same script queue as `complete/3`.

# `text_response`

```elixir
@spec text_response(String.t()) :: {:ok, Alloy.Provider.completion_response()}
```

Builds a scripted `{:ok, completion_response}` with a simple text reply.

# `text_response`

```elixir
@spec text_response(String.t(), map()) :: {:ok, Alloy.Provider.completion_response()}
```

Builds a scripted `{:ok, completion_response}` with text and provider state.

# `thinking_error_response`

```elixir
@spec thinking_error_response(String.t(), term()) ::
  {:thinking_then_error, String.t(), term()}
```

Builds a scripted response that emits a thinking delta via `on_event`, then
returns a retryable error. Used to test that `chunks_emitted?` tracks
`on_event` emissions so retries don't re-emit thinking deltas.

# `tool_use_response`

```elixir
@spec tool_use_response([Alloy.Message.content_block()]) ::
  {:ok, Alloy.Provider.completion_response()}
```

Builds a scripted `{:ok, completion_response}` with tool_use blocks.

---

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