scenario

package
v0.2.0 Latest Latest
Warning

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

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

Documentation

Overview

Package scenario defines the YAML scenario format shared by the SDK tests and arvel-plugin-check (SPEC §5.9). A scenario describes an exchange with a plugin: an optional environment, the initialize connection, and an ordered list of steps, each a call whose result is asserted or partly saved into variables for later steps.

Placeholders {{tmpdir}}, {{name}} and {{fakevendor:name}} are resolved by a Resolver before a step runs. Saves use a dotted JSONPath; expects are recursive JSON-subset matches; expectUpdates matches collected session/update notifications; answerPermissions arms the mock host to auto-answer a session/request_permission during the step.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func JSONPath

func JSONPath(root any, path string) (any, bool)

JSONPath evaluates a dotted path against a decoded JSON value. It supports "$" (the whole value) and dotted paths like "$.sessionId" or "$.a.b".

func MatchUpdates

func MatchUpdates(updates []map[string]any, expects []UpdateExpect) error

MatchUpdates checks that every expected update is satisfied by at least one collected update. updates are decoded ACP SessionUpdate objects (the "update" field of a session/update notification), each with a top-level "sessionUpdate" discriminator and an optional "content" member. Set semantics: no strict ordering, extra updates are fine.

func Subset

func Subset(want, got map[string]any) bool

Subset reports whether want is a recursive JSON subset of got: every key in want exists in got, nested maps recurse, scalars compare equal, and slices compare element-wise. Numbers compare after normalising integer-valued scalars, so 1 (YAML int) equals 1.0 (JSON float64).

Types

type ErrorExpect

type ErrorExpect struct {
	// Code is the numeric JSON-RPC code, e.g. -32601.
	Code int `yaml:"code"`
	// Arvel is the optional data.arvel.code, e.g. "busy".
	Arvel string `yaml:"arvel"`
}

ErrorExpect matches a JSON-RPC error response.

type Initialize

type Initialize struct {
	Connection protocol.ConnectionInfo `yaml:"connection"`
	DataDir    string                  `yaml:"dataDir"`
	// contains filtered or unexported fields
}

Initialize holds the connection sent in _meta.arvel of initialize.

func (Initialize) KindSpecified added in v0.2.0

func (in Initialize) KindSpecified() bool

KindSpecified distinguishes an omitted kind from an explicitly empty YAML kind.

func (*Initialize) UnmarshalYAML added in v0.2.0

func (in *Initialize) UnmarshalYAML(n *yaml.Node) error

UnmarshalYAML preserves field presence without changing production wire types.

type Plugin

type Plugin struct {
	// Env maps variable names to values; values may contain {{...}} placeholders.
	Env map[string]string `yaml:"env"`
}

Plugin holds the environment the scenario gives the plugin process.

type Resolver

type Resolver struct {
	// Vars holds saved variables, referenced as {{name}}.
	Vars map[string]string
	// Tmpdir is the value of {{tmpdir}}.
	Tmpdir string
	// DataDir and Workspace are static owned-directory placeholders.
	DataDir   string
	Workspace string
	// Fakevendor resolves {{fakevendor:name}} to a binary path. It may be nil,
	// in which case a fakevendor placeholder is an error.
	Fakevendor func(name string) (string, error)
}

Resolver resolves {{...}} placeholders in scenario values.

func (Resolver) Resolve

func (r Resolver) Resolve(v any) (any, error)

Resolve walks v recursively, replacing placeholders in every string.

func (Resolver) ResolveString

func (r Resolver) ResolveString(s string) (string, error)

ResolveString replaces every {{...}} placeholder in s. An unknown placeholder or a missing variable is an error. No escaping is supported.

type Scenario

type Scenario struct {
	Name       string     `yaml:"name"`
	Plugin     Plugin     `yaml:"plugin"`
	Initialize Initialize `yaml:"initialize"`
	Workspace  string     `yaml:"workspace"`
	Steps      []Step     `yaml:"steps"`
}

Scenario is one scripted exchange with a plugin (SPEC §5.9).

func Load

func Load(r io.Reader) (*Scenario, error)

Load decodes a scenario from r. Unknown fields are an error.

func LoadFile

func LoadFile(path string) (*Scenario, error)

LoadFile loads a scenario from a file.

func (*Scenario) Validate

func (s *Scenario) Validate() error

Validate checks the fields a run needs to be unambiguous.

type Step

type Step struct {
	// Call is the JSON-RPC method, e.g. "_arvel/status" or "session/new".
	Call string `yaml:"call"`
	// Params are the request params, templated before sending.
	Params map[string]any `yaml:"params"`
	// Save maps a variable name to a JSONPath evaluated on the result.
	Save map[string]string `yaml:"save"`
	// Expect is a recursive JSON subset the result must satisfy.
	Expect map[string]any `yaml:"expect"`
	// ExpectError, when set, matches an RPC error result instead of a value.
	ExpectError *ErrorExpect `yaml:"expectError"`
	// ExpectUpdates matches collected session/update notifications.
	ExpectUpdates []UpdateExpect `yaml:"expectUpdates"`
	// AnswerPermissions auto-answers session/request_permission during the step.
	AnswerPermissions string `yaml:"answerPermissions"`
}

Step is one call in a scenario.

type UpdateExpect

type UpdateExpect struct {
	// SessionUpdate is the ACP update discriminator, e.g. "agent_message_chunk".
	SessionUpdate string `yaml:"sessionUpdate"`
	// Subset is an optional recursive subset of the update object.
	Subset map[string]any `yaml:"subset"`
}

UpdateExpect matches one collected session/update notification.

Jump to

Keyboard shortcuts

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