Helpers and testing

session.run result

RunResult dataclass

RunResult(
    session: SessionInfo,
    messages: list[SessionMessageInfo] = list(),
)

What :meth:SessionHelpers.run returns.

session instance-attribute

session: SessionInfo

The session as it was after the run. session.cost and session.tokens cover the whole session.

messages class-attribute instance-attribute

messages: list[SessionMessageInfo] = field(
    default_factory=list
)

Messages this run added, oldest first, starting with the prompt.

assistant_messages property

assistant_messages: list[SessionMessageAssistant]

The assistant messages of this run, oldest first.

text property

text: str

Text of the last assistant message, or "" when the agent produced none.

outcome property

outcome: str | None

succeeded, failed or interrupted, from the run's idle marker or the session.

error property

error: SessionStructuredError | None

Why the run failed, from its idle marker or last assistant message, or None.

cost property

cost: float

Cost of this run in USD, summed over its assistant messages.

tokens property

tokens: TokenUsageInfo

Token usage of this run, summed over its assistant messages.

Fake server

FakeServer

FakeServer(
    *,
    reply: Reply = "OK",
    agents: Iterable[str] = ("build", "plan"),
    mcp_servers: Mapping[str, str] | None = None,
    directory: str = "/fake/project",
    cost: float = 0.001,
    tokens: tuple[int, int] = (10, 5),
)

Bases: MockTransport

An in-memory OpenCode server, usable as the transport of :class:opencode.Opencode and :class:opencode.AsyncOpencode.

Parameters:

Name	Type	Description	Default
reply	Reply	What the assistant answers to each prompt: text, or a function of the prompt text.	'OK'
agents	Iterable[str]	Agent ids :meth:opencode.Opencode.agent.list reports. Add more later with :meth:add_agent.	('build', 'plan')
mcp_servers	Mapping[str, str] | None	MCP server names mapped to their status (connected, pending, failed, ...).	None
directory	str	Project directory reported as every session's location.	'/fake/project'
cost	float	Cost in USD reported for each assistant reply.	0.001
tokens	tuple[int, int]	Input and output tokens reported for each assistant reply.	(10, 5)

Attributes:

Name	Type	Description
sessions	dict[str, SessionInfo]	Sessions by id.
messages	dict[str, list[BaseModel]]	Messages of each session, oldest first.
events	list[BaseModel]	Events the stream replays after server.connected.
requests	list[Request]	Every request received, in order.

prompts property

prompts: list[str]

Text of every prompt received, in order.

add_agent

add_agent(agent: str, *, after_polls: int = 0) -> None

Lists agent once GET /api/agent has been called after_polls more times, like an agent that loads after boot.

set_mcp_status

set_mcp_status(
    name: str,
    status: str = "connected",
    *,
    after_polls: int = 0,
) -> None

Reports MCP server name with status once GET /api/mcp has been called after_polls more times.

fail

fail(
    method: str,
    path: str,
    *,
    status: int = 500,
    body: object = None,
    exception: BaseException | None = None,
    times: int | None = 1,
) -> None

Makes matching requests fail.

Parameters:

Name	Type	Description	Default
method	str	HTTP method, such as POST.	required
path	str	Regular expression matched against the whole request path, such as /api/session/[^/]+/prompt.	required
status	int	Status of the error response.	500
body	object	JSON error body. Defaults to an untagged body, so the error class follows status.	None
exception	BaseException | None	Raise this from the transport instead of answering, for example httpx.ConnectError(...) or KeyboardInterrupt().	None
times	int | None	How many requests fail; None for all of them.	1

DEFAULT_MODEL module-attribute

DEFAULT_MODEL = ModelRef(
    id="fake-model", provider_id="fake"
)

Model reported for sessions created without one.