Documentation
¶
Overview ¶
Package agenttest provides agent environments, platform mocks, and caller contexts for tests of agents built on agentsdk.
Index ¶
- func Executor(config ExecutorConfig) (chatruntime.ExecutorFactory, error)
- func SetCallerHeader(r *http.Request)
- func WithCaller(ctx context.Context, user agentsdk.User, access agentsdk.Access) context.Context
- func WithCallerInfo(ctx context.Context, info CallerInfo) context.Context
- func WithUser(ctx context.Context, user agentsdk.User) context.Context
- type CallerInfo
- type ChatResult
- type Env
- type Events
- func (e *Events) OnAutomaticCompactionFinished(v bus.AutomaticCompactionFinishedPayload)
- func (e *Events) OnAutomaticCompactionStarted(v bus.AutomaticCompactionStartedPayload)
- func (e *Events) OnPermissionAsked(v bus.PermissionAskedPayload)
- func (e *Events) OnSuspension(v *sol.SuspensionContext)
- func (e *Events) OnTextDelta(v stream.TextDeltaEvent)
- func (e *Events) OnToolCall(v stream.ToolCallEvent)
- func (e *Events) OnToolResult(v stream.ToolResultEvent)
- func (e *Events) Snapshot() []any
- type ExecutorConfig
- type MemoryStore
- type MockAirlock
- func (m *MockAirlock) Close()
- func (m *MockAirlock) Requests() []MockRequest
- func (m *MockAirlock) RequestsByPath(prefix string) []MockRequest
- func (m *MockAirlock) Reset()
- func (m *MockAirlock) SetAgentResponse(method, uri string, status int, response any) error
- func (m *MockAirlock) SetConnectorCommandResponse(name string, output any) error
- type MockRequest
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Executor ¶
func Executor(config ExecutorConfig) (chatruntime.ExecutorFactory, error)
Executor returns a lazy factory. It does not connect to Docker or open a transport until an approved run_js call needs an executor. Build local images explicitly with jsexec.BuildImage before running tests that execute scripts.
func SetCallerHeader ¶
SetCallerHeader encodes explicit test caller context for an HTTP delivery. It does not authenticate the request; tests must also set the app bearer token.
func WithCaller ¶
WithCaller returns a context for an authenticated user with the given access. Identity does not determine access, so tests can model any valid combination.
func WithCallerInfo ¶
func WithCallerInfo(ctx context.Context, info CallerInfo) context.Context
WithCallerInfo validates and copies metadata without resolving IDs or doing I/O.
Types ¶
type CallerInfo ¶
type CallerInfo struct {
Kind agentsdk.CallerKind
Access agentsdk.Access
User *agentsdk.User
Initiator *agentsdk.User
Origin agentsdk.Origin
}
CallerInfo explicitly specifies a test execution. Kind, Access, and Origin's Interface and Execution are required. User callers require identical User and Initiator snapshots. Use the explicit Unknown constants for unspecified origins.
type ChatResult ¶
type ChatResult struct {
Run *sol.RunResult
AppCalls []wire.RuntimeInvokeResponse
}
ChatResult includes app invocation telemetry without completing the borrowed run. Run is the actual Sol result, including any permission suspension.
type Env ¶
type Env struct {
Agent *agentsdk.Agent
// Airlock records calls made through the platform API.
Airlock *MockAirlock
// URL is the mock Airlock base URL.
URL string
}
Env is a fully constructed test agent with its mock Airlock server.
func New ¶
New invokes factory first while runtime environment is cleared, then provisions a mock Airlock and test database and starts the agent. Start opens the database, validates migrations with an up, down-to-zero, up cycle from the enclosing Go module, synchronizes declarations, and runs named OnStart hooks before New returns. HTTP requests to Agent.Handler require Authorization: Bearer test-token, including requests with WithUser or WithCaller test contexts. Routes and webhooks also require SetCallerHeader on the test request. TEST_DB_URL is used when explicitly supplied; otherwise New starts a throwaway pgvector container. The factory may wire Agent.DB()'s late-bound handle, but database operations are unavailable until Start. `go tool air build` supplies one shared throwaway database to its serial package tests.
func (*Env) Chat ¶
func (e *Env) Chat(ctx context.Context, scope wire.RuntimeContext, in chatruntime.Input) (*ChatResult, error)
Chat runs the shared chat runtime locally. Input.Backend handles platform capabilities; app capabilities go through the real authenticated SDK handler. Supply mock models, a MemoryStore, an Events sink, and an executor factory. Input.Capabilities is an explicit subset of the manifest-based catalog; app declarations are checked again by the SDK endpoint on every call.
type Events ¶
type Events struct {
// contains filtered or unexported fields
}
Events records typed eventstream.Sink payloads for assertions after Run.
func (*Events) OnAutomaticCompactionFinished ¶
func (e *Events) OnAutomaticCompactionFinished(v bus.AutomaticCompactionFinishedPayload)
func (*Events) OnAutomaticCompactionStarted ¶
func (e *Events) OnAutomaticCompactionStarted(v bus.AutomaticCompactionStartedPayload)
func (*Events) OnPermissionAsked ¶
func (e *Events) OnPermissionAsked(v bus.PermissionAskedPayload)
func (*Events) OnSuspension ¶
func (e *Events) OnSuspension(v *sol.SuspensionContext)
func (*Events) OnTextDelta ¶
func (e *Events) OnTextDelta(v stream.TextDeltaEvent)
func (*Events) OnToolCall ¶
func (e *Events) OnToolCall(v stream.ToolCallEvent)
func (*Events) OnToolResult ¶
func (e *Events) OnToolResult(v stream.ToolResultEvent)
type ExecutorConfig ¶
type ExecutorConfig struct {
Image string
OpenTransport func(context.Context) (io.ReadWriteCloser, error)
Limits jsexec.Limits
// User is the optional caller display context exposed to JavaScript. Use
// the same identity as Chat's RuntimeContext; it does not authorize calls.
User *jsexec.User
}
ExecutorConfig selects exactly one transport. OpenTransport lets a builder inject a socket-free transport to an isolated executor owned by its host; test containers must not mount the Docker socket. Image selects local Docker. Both transports execute the same framed jsexec protocol and Deno runtime.
func ExecutorConfigFromEnv ¶
func ExecutorConfigFromEnv(limits jsexec.Limits) (ExecutorConfig, error)
ExecutorConfigFromEnv explicitly selects the Airlock-provisioned test transport. go tool air build and go test inherit these build-scoped values. Missing configuration is an error, never a Docker or in-process fallback.
func RemoteExecutorConfig ¶
func RemoteExecutorConfig(endpoint, token string, limits jsexec.Limits) (ExecutorConfig, error)
RemoteExecutorConfig uses a scoped test endpoint. Airlock owns the disposable executor; the test process receives only its framed stdin/stdout transport.
type MemoryStore ¶
type MemoryStore struct {
// contains filtered or unexported fields
}
MemoryStore is a test-only conversation store. Production hosts use shared persistence and serialize runs for each conversation across replicas.
type MockAirlock ¶
type MockAirlock struct {
Server *httptest.Server
// LLMResponse is the NDJSON response returned by the model endpoint.
LLMResponse []byte
// contains filtered or unexported fields
}
MockAirlock is an in-process Airlock API used by agent tests.
func NewMockAirlock ¶
func NewMockAirlock() (*MockAirlock, string)
NewMockAirlock creates a mock Airlock server and returns its base URL.
func (*MockAirlock) Requests ¶
func (m *MockAirlock) Requests() []MockRequest
Requests returns all recorded requests.
func (*MockAirlock) RequestsByPath ¶
func (m *MockAirlock) RequestsByPath(prefix string) []MockRequest
RequestsByPath returns requests matching the path prefix.
func (*MockAirlock) SetAgentResponse ¶
func (m *MockAirlock) SetAgentResponse(method, uri string, status int, response any) error
SetAgentResponse configures an exact task-agent HTTP method and request URI (including query). Supply a wire.AgentRunResponse or wire.ListAgentRunsResponse, or an error body with its HTTP status. Missing responses fail explicitly.
func (*MockAirlock) SetConnectorCommandResponse ¶ added in v0.6.0
func (m *MockAirlock) SetConnectorCommandResponse(name string, output any) error
SetConnectorCommandResponse configures the typed JSON output returned for a connector command name.
Source Files