agenttest

package
v0.8.1-alpha.11 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 11, 2026 License: Apache-2.0 Imports: 40 Imported by: 0

Documentation

Overview

Package agenttest provides agent environments, platform mocks, and caller contexts for tests of agents built on agentsdk.

Index

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

func SetCallerHeader(r *http.Request)

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

func WithCaller(ctx context.Context, user agentsdk.User, access agentsdk.Access) context.Context

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.

func WithUser

func WithUser(ctx context.Context, user agentsdk.User) context.Context

WithUser returns a context for an authenticated user. It implies AccessUser.

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

func New(t *testing.T, factory func() *agentsdk.Agent) *Env

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

func NewWithOptions(t *testing.T, factory func() *agentsdk.Agent, options Options) *Env

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.

func (*Env) MockModel

func (e *Env) MockModel(slot string) *testutil.MockModel

MockModel returns the slot's configurable in-process mock. An empty slot names the default text-generation model. Live slots retain a dormant mock so the same test setup can configure responses in both mocked and live runs. Panics for an unknown or non-streaming slot.

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)

func (*Events) Snapshot added in v0.7.0

func (e *Events) Snapshot() []any

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)

func (*FileStorage) WriteFile

func (s *FileStorage) WriteFile(ctx context.Context, p string, r io.Reader, mime string) (agentsdk.FileInfo, 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.

func (*MemoryStore) Append added in v0.7.0

func (s *MemoryStore) Append(ctx context.Context, messages []session.Message) error

func (*MemoryStore) Compact added in v0.7.0

func (s *MemoryStore) Compact(ctx context.Context, summary []session.Message, _ int) error

func (*MemoryStore) Load added in v0.7.0

func (s *MemoryStore) Load(ctx context.Context) ([]session.Message, error)

type MockAirlock

type MockAirlock struct {
	Server *httptest.Server
	// 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) Close

func (m *MockAirlock) Close()

Close shuts down the mock server.

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) Reset

func (m *MockAirlock) Reset()

Reset clears all recorded requests.

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

type MockRequest struct {
	Method string
	Path   string
	Body   []byte
	Header http.Header
}

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

func RegisterFlags(fs *flag.FlagSet) *Options

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.

Directories

Path Synopsis
examples
csv
Package csvexample declares an app-owned CSV task with a native artifact tool.
Package csvexample declares an app-owned CSV task with a native artifact tool.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL