GenAgent.Backends.Mock (GenAgent v0.8.0)

In-memory GenAgent.Backend for testing application agents without a provider account or CLI. Start an agent with backend: GenAgent.Backends.Mock and pass scripts: through its init_agent/1 backend options.

A mock session holds a list of scripts, one per upcoming turn. Each call to prompt/2 consumes the head of the list and turns it into an event stream.

Script shapes

[%GenAgent.Event{}, ...] -- a static list of events. The last event should be a terminal event (:result or :error).
fun where fun is (String.t() -> Enumerable.t()) -- the prompt is passed in and the function returns the event stream. Useful for asserting on the prompt text or emitting dynamic events.
{:error, reason} -- prompt/2 returns {:error, reason} synchronously, without producing a stream.
{:raise, reason} -- the returned stream raises when consumed, simulating an in-flight backend crash.
gate(tag, events) -- announce {:mock_blocked, tag, task_pid} to the process that constructs the script, then wait for {:mock_release, tag} sent to task_pid before yielding events. The wait has a five-second safety timeout by default.

Scripts are consumed in order. A prompt with no matching script returns {:error, :no_script}.

Helpers

Tests can use history/1 with a running agent's registered name or a session struct to inspect dispatched prompts; remaining/1 counts unconsumed scripts. start_error: reason simulates a backend startup failure without creating a session process.

Summary

Types

script()

t()

Functions

gate(tag, events, timeout \\ 5000)

Return a script that pauses an in-flight turn until the test releases it.

history(name)

Return attempted prompts in order, including attempts after scripts run out.

remaining(mock)

Return the number of unconsumed scripts remaining.

Types

script()

@type script() ::
  [GenAgent.Event.t()]
  | (String.t() -> Enumerable.t())
  | {:error, term()}
  | {:raise, term()}

t()

@type t() :: %GenAgent.Backends.Mock{agent: pid(), session_id: String.t() | nil}

Functions

gate(tag, events, timeout \\ 5000)

@spec gate(term(), [GenAgent.Event.t()], pos_integer()) :: (String.t() ->
                                                        Enumerable.t())

Return a script that pauses an in-flight turn until the test releases it.

Construct the script in the test process and include it in scripts:. After receiving {:mock_blocked, tag, task_pid}, send {:mock_release, tag} to task_pid. The returned stream then yields events. The safety timeout raises in the prompt task if no release arrives; pass a different positive timeout when a test needs one.

history(name)

@spec history(t() | GenAgent.name()) :: [String.t()] | {:error, atom()}

Return attempted prompts in order, including attempts after scripts run out.

Accepts a session struct or a registered GenAgent name. Name lookup returns {:error, :not_found} if the agent is gone and {:error, :not_mock_backend} if it uses another backend.

remaining(mock)

@spec remaining(t()) :: non_neg_integer()

Return the number of unconsumed scripts remaining.