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 FileStorage
- type MemoryStore
- type MockAirlock
- type MockRequest
- type Options
- type RunOptions
- type RunResult
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Executor ¶ added in v0.7.0
func Executor(config ExecutorConfig) (chatruntime.ExecutorFactory, error)
func SetCallerHeader ¶ added in v0.7.0
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 ¶ added in v0.7.0
func WithCallerInfo(ctx context.Context, info CallerInfo) context.Context
WithCallerInfo validates and copies metadata without resolving IDs or doing I/O.
Types ¶
type CallerInfo ¶ added in v0.7.0
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 ¶ added in v0.7.0
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
Storage *FileStorage
// URL is the recorded local callback host's base URL.
URL string
Runtime *localruntime.Host
// contains filtered or unexported fields
}
Env is a started SDK app with the shared local host and isolated dependencies.
func New ¶
New invokes factory first while runtime environment is cleared, then provisions the shared local host and test database and starts the app. 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 NewWithOptions ¶
NewWithOptions constructs an environment with per-slot mocks and explicit live selections. Models are prepared before Start, including OnStart hooks. Zero options use only in-process mocks. RegisterFlags opts a test package into CLI model selection; no flags or credentials are discovered automatically.
func (*Env) Chat ¶ added in v0.7.0
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 ¶ added in v0.7.0
type Events struct {
// contains filtered or unexported fields
}
Events records typed eventstream.Sink payloads for assertions after Run.
func (*Events) OnAutomaticCompactionFinished ¶ added in v0.7.0
func (e *Events) OnAutomaticCompactionFinished(v bus.AutomaticCompactionFinishedPayload)
func (*Events) OnAutomaticCompactionStarted ¶ added in v0.7.0
func (e *Events) OnAutomaticCompactionStarted(v bus.AutomaticCompactionStartedPayload)
func (*Events) OnPermissionAsked ¶ added in v0.7.0
func (e *Events) OnPermissionAsked(v bus.PermissionAskedPayload)
func (*Events) OnSuspension ¶ added in v0.7.0
func (e *Events) OnSuspension(v *sol.SuspensionContext)
func (*Events) OnTextDelta ¶ added in v0.7.0
func (e *Events) OnTextDelta(v stream.TextDeltaEvent)
func (*Events) OnToolCall ¶ added in v0.7.0
func (e *Events) OnToolCall(v stream.ToolCallEvent)
func (*Events) OnToolResult ¶ added in v0.7.0
func (e *Events) OnToolResult(v stream.ToolResultEvent)
type ExecutorConfig ¶ added in v0.7.0
type ExecutorConfig = localruntime.ExecutorConfig
func ExecutorConfigFromEnv ¶ added in v0.7.0
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 ¶ added in v0.7.0
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 FileStorage ¶
type FileStorage struct {
// contains filtered or unexported fields
}
FileStorage is SDK test support for a real app-local object namespace. Enable it with Options.Storage. Seed only deliberate fixtures through WriteFile; source filenames are never resolved as host paths by model callbacks.
func NewFileStorage ¶
func NewFileStorage(t *testing.T) *FileStorage
NewFileStorage creates an isolated t.TempDir namespace and closes it during test cleanup. It reads neither credentials nor pre-existing host files.
func (*FileStorage) OpenFile ¶
func (s *FileStorage) OpenFile(ctx context.Context, p string) (io.ReadCloser, error)
type MemoryStore ¶ added in v0.7.0
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 ¶
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) 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.
type MockRequest ¶
MockRequest records a request made to the mock Airlock server.
type Options ¶
type Options struct {
// ExecutorFactory supplies an isolated executor for durable task JavaScript.
// Omitted factories use the explicit local agentsdk-jsexecutor:local image.
ExecutorFactory chatruntime.ExecutorFactory
Resources localruntime.Resources
NoAuthResources localruntime.Resources
EnvVars map[string]string
ResourceSession string
Discovery capability.Discovery
Backend chatruntime.Backend
// Storage selects a seeded isolated store. Omission creates an empty store.
// The shared host and model attachment resolver use that same store.
Storage *FileStorage
// Models selects live slug/provider/model references by slot. "" is the unnamed
// default text slot. Unselected slots remain mocked.
Models map[string]string
// Mocks configures responses before startup. Live slots retain these mocks
// without dispatching to them. Omitted ID uses the environment's slot identity.
Mocks map[string]testutil.MockConfig
// Limits overrides test-only mock compaction limits. Live limits come from
// provider resolution. Defaults are Context: 100000, Output: 4096.
Limits map[string]session.ModelLimits
}
Options configures per-environment models. Zero options select an independent configurable mock for every declared text/vision slot and the default text slot.
func RegisterFlags ¶
RegisterFlags explicitly registers agenttest.model on fs. Call once during test package setup, before parsing. It performs no model, environment, credential or network lookup. Pass the returned options to NewWithOptions after parsing; New does not read package flags.
type RunOptions ¶
type RunOptions struct {
Scope wire.RuntimeContext
ExecutorFactory chatruntime.ExecutorFactory
// Backend handles every non-private capability, including app storage and DB.
// Without it these calls fail with an unsupported-service error.
Backend chatruntime.Backend
Discovery capability.Discovery
// Timeout bounds the entire attempt (default one minute). MaxSteps bounds
// model requests (default 150). Registered limits can further restrict both.
Timeout time.Duration
MaxSteps int64
}
RunOptions supplies the host boundaries for an explicit registered-task test. A zero Scope creates a fresh application-owned test run using Env's app ID. An explicit Scope must identify the same app and an application-owned run; Definition is filled from the handle and must match if supplied.
type RunResult ¶
type RunResult[Out any] struct { Reply *agentsdk.AgentReply[Out] Runtime *agentruntime.Result Scope wire.RuntimeContext Steps int64 Tokens int64 Calls []chatruntime.Invocation AppCalls []wire.RuntimeInvokeResponse Events []any Messages []session.Message Checkpoint *agentruntime.Checkpoint }
RunResult retains diagnostics on failed attempts as well as typed completion.
func RunAgent ¶
func RunAgent[In, Out any](t *testing.T, ctx context.Context, env *Env, handle *agentsdk.AgentHandle[In, Out], input In, opts RunOptions) (*RunResult[Out], error)
RunAgent executes a leaf registered task through agentruntime and the supplied Deno executor. Models are selected by the environment's registered slot policy. This diagnostic leaf helper uses attempt-local fixtures. Native Start/Get/Wait exercise Env.Runtime's durable scheduler, including declared child agents.