A2aEngine.TestPeer (a2a_engine v0.1.0)

Copy Markdown View Source

Scriptable in-process A2A peer for integration tests.

Ships in lib/ (not test/) so consuming hosts can use it in their own test suites without having to reimplement this machinery.

Usage

{:ok, peer} = A2aEngine.TestPeer.start_link()
url = A2aEngine.TestPeer.url(peer)

A2aEngine.TestPeer.script(peer, "message/send", fn _params ->
  {:ok, %{"kind" => "task", "id" => "t1", "contextId" => "c1",
          "status" => %{"state" => "completed"}}}
end)

{:ok, response} = A2aEngine.Transport.Http.send_request(url, request)

# Assert the peer saw what we expected
assert A2aEngine.TestPeer.received(peer) == [{"message/send", %{...}}]

A2aEngine.TestPeer.stop(peer)

Streaming

A2aEngine.TestPeer.script_stream(peer, "message/stream", fn _params, emit ->
  emit.(event1)
  emit.(event2)
  {:ok, :done}
end)

Options

  • :auth — A2aEngine.Auth module. Defaults to Localhost.
  • :auth_opts — keyword list passed to the auth module.
  • :port — fixed port (default 0 → random).

Summary

Types

request_fn()
stream_fn()

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

clear_received(peer)

Clear the received log (useful between assertions in one test).

port(peer)

TCP port the peer is bound to.

received(peer)

List of {method, params} tuples that the peer has received, in order.

script(peer, method, fun)

Install a unary response function for a JSON-RPC method.

script_stream(peer, method, fun)

Install a streaming response function for a JSON-RPC method.

start_link(opts \\ [])

Start a test peer with its own Bandit HTTP server on a random port.

stop(peer)

Stop the peer and its underlying Bandit server.

url(peer)

Full base URL (scheme://host:port) where this peer accepts A2A requests.

Types

request_fn()

@type request_fn() :: (params :: map() -> {:ok, term()} | {:error, map()})

stream_fn()

@type stream_fn() :: (params :: map(), emit :: (map() -> :ok) ->
                  {:ok, term()} | {:error, map()})

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

clear_received(peer)

@spec clear_received(pid()) :: :ok

Clear the received log (useful between assertions in one test).

port(peer)

@spec port(pid()) :: non_neg_integer()

TCP port the peer is bound to.

received(peer)

@spec received(pid()) :: [{String.t(), map() | nil}]

List of {method, params} tuples that the peer has received, in order.

script(peer, method, fun)

@spec script(pid(), String.t(), request_fn()) :: :ok

Install a unary response function for a JSON-RPC method.

The function receives the decoded params map and returns {:ok, result} or {:error, error_map}.

script_stream(peer, method, fun)

@spec script_stream(pid(), String.t(), stream_fn()) :: :ok

Install a streaming response function for a JSON-RPC method.

The function receives (params, emit_fn) and may call emit_fn.(event) zero or more times before returning {:ok, term} or {:error, map}.

start_link(opts \\ [])

@spec start_link(keyword()) :: GenServer.on_start()

Start a test peer with its own Bandit HTTP server on a random port.

stop(peer)

@spec stop(pid()) :: :ok

Stop the peer and its underlying Bandit server.

url(peer)

@spec url(pid()) :: String.t()

Full base URL (scheme://host:port) where this peer accepts A2A requests.