Documentation
¶
Overview ¶
Package mockhost is the scripted ACP client of the testkit (SPEC §5.9). It drives a provider or a router plugin either in-process (plugin.Run / plugin.RunRouter over pipes) or as a started binary, mirrors the protocol methods, collects session/update notifications, auto-answers permission requests, and runs scenario files.
Index ¶
- type Driver
- func (c Driver) Action(id string) (protocol.ActionResult, error)
- func (c Driver) Call(ctx context.Context, method string, params, result any) error
- func (c Driver) Cancel(id string) error
- func (c Driver) Close()
- func (c Driver) CloseWithError() error
- func (c Driver) Initialize(meta protocol.InitMeta) (protocol.InitResultMeta, error)
- func (c Driver) InitializeCtx(ctx context.Context, meta protocol.InitMeta) (protocol.InitResultMeta, error)
- func (c Driver) LoadSession(id string, meta protocol.SessionMeta) error
- func (c Driver) Models(refresh bool) (protocol.ModelsResult, error)
- func (c Driver) NewSession(meta protocol.SessionMeta) (string, error)
- func (c Driver) PermissionsSeen() int
- func (c Driver) Prompt(id string, blocks []acp.ContentBlock) (PromptResult, error)
- func (c Driver) RouteEffort(p protocol.RouteEffortParams) (protocol.RouteEffortResult, error)
- func (c Driver) RouteExplain(p protocol.RoutePlanParams) (protocol.RouteExplainResult, error)
- func (c Driver) RouteMessage(p protocol.RouteMessageParams) (protocol.RouteMessageResult, error)
- func (c Driver) RoutePlan(p protocol.RoutePlanParams) (protocol.RoutePlanResult, error)
- func (c Driver) RunErr() error
- func (d *Driver) RunScenario(sc *scenario.Scenario, opts ScenarioOptions) (ScenarioResult, error)
- func (c Driver) SetConfigOption(id, configID, value string) error
- func (d *Driver) Shutdown() error
- func (d *Driver) ShutdownExit(timeout time.Duration) (int, error)
- func (c Driver) Status() (protocol.Status, error)
- func (c Driver) Stderr() string
- func (c Driver) Stdout() string
- func (c Driver) Updates(id string) []map[string]any
- func (c Driver) Usage() (protocol.Usage, error)
- type Environment
- type EnvironmentOptions
- type Host
- func InProcess(t testing.TB, p plugin.Provider, opts ...plugin.Option) *Host
- func InProcessRouter(t testing.TB, r plugin.Router, opts ...plugin.Option) *Host
- func InProcessRouterWithEnvironment(t testing.TB, r plugin.Router, e *Environment, opts ...plugin.Option) *Host
- func InProcessWithEnvironment(t testing.TB, p plugin.Provider, e *Environment, opts ...plugin.Option) *Host
- func Start(t testing.TB, binaryPath string, opts ...StartOption) *Host
- func (c Host) Action(id string) (protocol.ActionResult, error)
- func (c Host) Call(ctx context.Context, method string, params, result any) error
- func (c Host) Cancel(id string) error
- func (c Host) Close()
- func (c Host) CloseWithError() error
- func (c Host) Initialize(meta protocol.InitMeta) (protocol.InitResultMeta, error)
- func (c Host) InitializeCtx(ctx context.Context, meta protocol.InitMeta) (protocol.InitResultMeta, error)
- func (c Host) LoadSession(id string, meta protocol.SessionMeta) error
- func (c Host) Models(refresh bool) (protocol.ModelsResult, error)
- func (c Host) NewSession(meta protocol.SessionMeta) (string, error)
- func (c Host) PermissionsSeen() int
- func (c Host) Prompt(id string, blocks []acp.ContentBlock) (PromptResult, error)
- func (c Host) RouteEffort(p protocol.RouteEffortParams) (protocol.RouteEffortResult, error)
- func (c Host) RouteExplain(p protocol.RoutePlanParams) (protocol.RouteExplainResult, error)
- func (c Host) RouteMessage(p protocol.RouteMessageParams) (protocol.RouteMessageResult, error)
- func (c Host) RoutePlan(p protocol.RoutePlanParams) (protocol.RoutePlanResult, error)
- func (c Host) RunErr() error
- func (h *Host) RunScenario(t testing.TB, file string)
- func (c Host) SetConfigOption(id, configID, value string) error
- func (h *Host) Shutdown()
- func (c Host) Status() (protocol.Status, error)
- func (c Host) Stderr() string
- func (c Host) Stdout() string
- func (c Host) Updates(id string) []map[string]any
- func (c Host) Usage() (protocol.Usage, error)
- type PrepareOptions
- type PreparedScenario
- func (p *PreparedScenario) Close() error
- func (p *PreparedScenario) Env() map[string]string
- func (p *PreparedScenario) Environment() *Environment
- func (p *PreparedScenario) Initialize() protocol.InitMeta
- func (p *PreparedScenario) Run(ctx context.Context, d *Driver) (ScenarioResult, error)
- func (p *PreparedScenario) RunInitialized(ctx context.Context, d *Driver) (ScenarioResult, error)
- type PromptResult
- type ScenarioOptions
- type ScenarioResult
- type StartOption
- type StepResult
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Driver ¶
type Driver struct {
// contains filtered or unexported fields
}
Driver drives one plugin binary without a testing.TB: every failure is returned as an error, and scenarios return structured results. It is the surface the conformance CLI uses.
func StartDriver ¶
func StartDriver(binaryPath string, opts ...StartOption) (*Driver, error)
StartDriver launches a plugin binary and returns a Driver that drives it.
func (Driver) Action ¶
func (c Driver) Action(id string) (protocol.ActionResult, error)
Action runs one _arvel/action.
func (Driver) Call ¶
Call performs a JSON-RPC call with the given context. The context is the caller's deadline; it is not extended with the host's default timeout.
func (Driver) Close ¶
func (c Driver) Close()
Close tears the connection down. It is idempotent and safe to call from t.Cleanup or defer.
func (Driver) CloseWithError ¶ added in v0.2.0
func (c Driver) CloseWithError() error
CloseWithError stops and joins the driver. Unconfirmed teardown retains files.
func (Driver) Initialize ¶
func (c Driver) Initialize(meta protocol.InitMeta) (protocol.InitResultMeta, error)
Initialize sends initialize and returns the decoded _meta.arvel, using the host's default timeout.
func (Driver) InitializeCtx ¶
func (c Driver) InitializeCtx(ctx context.Context, meta protocol.InitMeta) (protocol.InitResultMeta, error)
InitializeCtx sends initialize under the caller's context (deadline).
func (Driver) LoadSession ¶
func (c Driver) LoadSession(id string, meta protocol.SessionMeta) error
LoadSession resumes a session.
func (Driver) Models ¶
func (c Driver) Models(refresh bool) (protocol.ModelsResult, error)
Models answers _arvel/models.
func (Driver) NewSession ¶
func (c Driver) NewSession(meta protocol.SessionMeta) (string, error)
NewSession creates a session and returns its id.
func (Driver) PermissionsSeen ¶
func (c Driver) PermissionsSeen() int
PermissionsSeen reports how many permission requests arrived on the host.
func (Driver) Prompt ¶
func (c Driver) Prompt(id string, blocks []acp.ContentBlock) (PromptResult, error)
Prompt runs one turn and returns its stop reason and turn metadata.
func (Driver) RouteEffort ¶
func (c Driver) RouteEffort(p protocol.RouteEffortParams) (protocol.RouteEffortResult, error)
RouteEffort calls _arvel/route/effort.
func (Driver) RouteExplain ¶
func (c Driver) RouteExplain(p protocol.RoutePlanParams) (protocol.RouteExplainResult, error)
RouteExplain calls _arvel/route/explain.
func (Driver) RouteMessage ¶
func (c Driver) RouteMessage(p protocol.RouteMessageParams) (protocol.RouteMessageResult, error)
RouteMessage calls _arvel/route/message.
func (Driver) RoutePlan ¶
func (c Driver) RoutePlan(p protocol.RoutePlanParams) (protocol.RoutePlanResult, error)
RoutePlan calls _arvel/route/plan.
func (Driver) RunErr ¶
func (c Driver) RunErr() error
RunErr returns the error plugin.Run / plugin.RunRouter returned, if any.
func (*Driver) RunScenario ¶
func (d *Driver) RunScenario(sc *scenario.Scenario, opts ScenarioOptions) (ScenarioResult, error)
RunScenario runs one scenario against the driver and returns a structured result. The plugin process must already be started (see StartDriver).
func (Driver) SetConfigOption ¶
SetConfigOption changes a session config option.
func (*Driver) Shutdown ¶
Shutdown sends _arvel/shutdown, closes the plugin's stdin and waits for the plugin to exit, returning an error on failure or timeout.
func (*Driver) ShutdownExit ¶
ShutdownExit sends _arvel/shutdown and waits up to timeout for the plugin to exit, returning its exit code. A non-zero exit is not an error; the caller interprets the code.
func (Driver) Stderr ¶
func (c Driver) Stderr() string
Stderr returns the captured stderr text of the plugin process.
func (Driver) Stdout ¶
func (c Driver) Stdout() string
Stdout returns the raw protocol output read from the plugin, including unknown fields and notifications that typed decoding would discard.
type Environment ¶ added in v0.2.0
type Environment struct {
// contains filtered or unexported fields
}
Environment is a stable test context. Only its allocated root is removed.
func NewEnvironment ¶ added in v0.2.0
func NewEnvironment(opts EnvironmentOptions) (*Environment, error)
NewEnvironment allocates private missing paths, preserving explicit metadata.
func (*Environment) Close ¶ added in v0.2.0
func (e *Environment) Close() error
Close removes owned paths only after all drivers have stopped.
func (*Environment) Initialize ¶ added in v0.2.0
func (e *Environment) Initialize() protocol.InitMeta
Initialize returns a cloned snapshot of the defaults.
func (*Environment) Root ¶ added in v0.2.0
func (e *Environment) Root() string
Root returns the owned scratch directory for test resources.
func (*Environment) Workspace ¶ added in v0.2.0
func (e *Environment) Workspace() string
Workspace returns the stable default session cwd.
type EnvironmentOptions ¶ added in v0.2.0
EnvironmentOptions supplies borrowed paths and initialization defaults.
type Host ¶
type Host struct {
// contains filtered or unexported fields
}
Host drives one plugin through the testing.TB surface: a provider or a router, in-process or as a binary. The protocol logic lives on the embedded core; Host only adds t.Fatalf / t.Cleanup behavior.
func InProcessRouter ¶
InProcessRouter starts a router in-process and returns a Host that drives it.
func InProcessRouterWithEnvironment ¶ added in v0.2.0
func InProcessRouterWithEnvironment(t testing.TB, r plugin.Router, e *Environment, opts ...plugin.Option) *Host
InProcessRouterWithEnvironment starts a router with a borrowed test context.
func InProcessWithEnvironment ¶ added in v0.2.0
func InProcessWithEnvironment(t testing.TB, p plugin.Provider, e *Environment, opts ...plugin.Option) *Host
InProcessWithEnvironment starts a provider with a borrowed test context.
func Start ¶
func Start(t testing.TB, binaryPath string, opts ...StartOption) *Host
Start launches a plugin binary and returns a Host that drives it. It works for both provider and router binaries, which share the same stdio transport.
func (Host) Action ¶
func (c Host) Action(id string) (protocol.ActionResult, error)
Action runs one _arvel/action.
func (Host) Call ¶
Call performs a JSON-RPC call with the given context. The context is the caller's deadline; it is not extended with the host's default timeout.
func (Host) Close ¶
func (c Host) Close()
Close tears the connection down. It is idempotent and safe to call from t.Cleanup or defer.
func (Host) CloseWithError ¶ added in v0.2.0
func (c Host) CloseWithError() error
CloseWithError stops and joins the driver. Unconfirmed teardown retains files.
func (Host) Initialize ¶
func (c Host) Initialize(meta protocol.InitMeta) (protocol.InitResultMeta, error)
Initialize sends initialize and returns the decoded _meta.arvel, using the host's default timeout.
func (Host) InitializeCtx ¶
func (c Host) InitializeCtx(ctx context.Context, meta protocol.InitMeta) (protocol.InitResultMeta, error)
InitializeCtx sends initialize under the caller's context (deadline).
func (Host) LoadSession ¶
func (c Host) LoadSession(id string, meta protocol.SessionMeta) error
LoadSession resumes a session.
func (Host) Models ¶
func (c Host) Models(refresh bool) (protocol.ModelsResult, error)
Models answers _arvel/models.
func (Host) NewSession ¶
func (c Host) NewSession(meta protocol.SessionMeta) (string, error)
NewSession creates a session and returns its id.
func (Host) PermissionsSeen ¶
func (c Host) PermissionsSeen() int
PermissionsSeen reports how many permission requests arrived on the host.
func (Host) Prompt ¶
func (c Host) Prompt(id string, blocks []acp.ContentBlock) (PromptResult, error)
Prompt runs one turn and returns its stop reason and turn metadata.
func (Host) RouteEffort ¶
func (c Host) RouteEffort(p protocol.RouteEffortParams) (protocol.RouteEffortResult, error)
RouteEffort calls _arvel/route/effort.
func (Host) RouteExplain ¶
func (c Host) RouteExplain(p protocol.RoutePlanParams) (protocol.RouteExplainResult, error)
RouteExplain calls _arvel/route/explain.
func (Host) RouteMessage ¶
func (c Host) RouteMessage(p protocol.RouteMessageParams) (protocol.RouteMessageResult, error)
RouteMessage calls _arvel/route/message.
func (Host) RoutePlan ¶
func (c Host) RoutePlan(p protocol.RoutePlanParams) (protocol.RoutePlanResult, error)
RoutePlan calls _arvel/route/plan.
func (Host) RunErr ¶
func (c Host) RunErr() error
RunErr returns the error plugin.Run / plugin.RunRouter returned, if any.
func (*Host) RunScenario ¶
RunScenario loads a scenario file, initializes the host from its connection and runs every step, failing the test on the first mismatch.
func (Host) SetConfigOption ¶
SetConfigOption changes a session config option.
func (*Host) Shutdown ¶
func (h *Host) Shutdown()
Shutdown sends _arvel/shutdown and waits for the plugin to exit, failing the test on error or timeout.
func (Host) Stderr ¶
func (c Host) Stderr() string
Stderr returns the captured stderr text of the plugin process.
func (Host) Stdout ¶
func (c Host) Stdout() string
Stdout returns the raw protocol output read from the plugin, including unknown fields and notifications that typed decoding would discard.
type PrepareOptions ¶ added in v0.2.0
type PrepareOptions struct {
Environment *Environment
Tmpdir string
FakevendorDir string
Sandbox *protocol.SandboxInfo
}
PrepareOptions selects borrowed paths and an optional borrowed environment.
type PreparedScenario ¶ added in v0.2.0
type PreparedScenario struct {
// contains filtered or unexported fields
}
PreparedScenario resolves static inputs and builds, but never runs, fake CLIs. Close it after closing every driver using its Environment.
func PrepareScenario ¶ added in v0.2.0
func PrepareScenario(ctx context.Context, sc *scenario.Scenario, opts PrepareOptions) (p *PreparedScenario, err error)
PrepareScenario prepares static initialization and startup environment.
func (*PreparedScenario) Close ¶ added in v0.2.0
func (p *PreparedScenario) Close() error
Close releases prepared resources only after driver termination is confirmed.
func (*PreparedScenario) Env ¶ added in v0.2.0
func (p *PreparedScenario) Env() map[string]string
Env returns a copy of startup overrides, without implicit parent variables.
func (*PreparedScenario) Environment ¶ added in v0.2.0
func (p *PreparedScenario) Environment() *Environment
Environment returns the context to borrow when starting the plugin.
func (*PreparedScenario) Initialize ¶ added in v0.2.0
func (p *PreparedScenario) Initialize() protocol.InitMeta
Initialize returns a cloned resolved initialization snapshot.
func (*PreparedScenario) Run ¶ added in v0.2.0
func (p *PreparedScenario) Run(ctx context.Context, d *Driver) (ScenarioResult, error)
Run initializes the already-started driver and executes dynamic steps.
func (*PreparedScenario) RunInitialized ¶ added in v0.2.0
func (p *PreparedScenario) RunInitialized(ctx context.Context, d *Driver) (ScenarioResult, error)
RunInitialized executes steps after the caller has initialized the driver. This allows a checker to add controlled canary metadata before initialization.
type PromptResult ¶
type PromptResult struct {
StopReason acp.StopReason
Meta protocol.TurnMeta
}
PromptResult is the outcome of a session/prompt call.
type ScenarioOptions ¶
type ScenarioOptions struct {
// Tmpdir is the value of the {{tmpdir}} placeholder.
Tmpdir string
// FakevendorDir is the directory holding fakevendor scripts, resolved as
// <dir>/<name>.yaml for the {{fakevendor:name}} placeholder.
FakevendorDir string
// Sandbox, when non-nil, is injected into initialize._meta.arvel.sandbox
// (PROTOCOL §15). The proxy check uses it to send a sandbox.proxy.
Sandbox *protocol.SandboxInfo
}
ScenarioOptions customize how a scenario is run against a Driver.
type ScenarioResult ¶
type ScenarioResult struct {
Name string `json:"name"`
Pass bool `json:"pass"`
Steps []StepResult `json:"steps"`
// Updates holds every session/update notification collected during the run,
// keyed by session id. It lets the conformance CLI inspect what the plugin
// streamed back (for example a fake vendor's reported environment).
Updates map[string][]map[string]any `json:"updates,omitempty"`
}
ScenarioResult is the outcome of one scenario run.
func (ScenarioResult) Summary ¶
func (r ScenarioResult) Summary() (passed, failed int)
Summary returns the number of passing and failing steps.
type StartOption ¶
type StartOption func(*startOptions)
StartOption configures Start.
func WithArgs ¶
func WithArgs(args ...string) StartOption
WithArgs sets the arguments passed to the plugin binary.
func WithDir ¶
func WithDir(dir string) StartOption
WithDir sets the working directory of the plugin process.
func WithEnv ¶
func WithEnv(env []string) StartOption
WithEnv sets the environment of the plugin process. A nil env means the default minimal environment (see procx.Start).
func WithEnvironment ¶ added in v0.2.0
func WithEnvironment(e *Environment) StartOption
WithEnvironment borrows a context; close the driver before the environment.
type StepResult ¶
type StepResult struct {
Call string `json:"call"`
Pass bool `json:"pass"`
Err string `json:"error,omitempty"`
}
StepResult is the outcome of one scenario step.