scenario

Documentation

Overview

Package scenario provides types and functions for loading and validating cli-replay scenario files.

Index

• type CallBounds
  • func (cb *CallBounds) Validate() error
• type GroupRange
• type Match
  • func (m *Match) Validate() error
• type Meta
  • func (m *Meta) Validate() error
• type Response
  • func (r *Response) Validate() error
  • func (r *Response) ValidateDelay(maxDelay time.Duration) error
• type Scenario
  • func Load(r io.Reader) (*Scenario, error)
  • func LoadFile(path string) (*Scenario, error)
  • func (s *Scenario) FlatSteps() []Step
  • func (s *Scenario) GroupRanges() []GroupRange
  • func (s *Scenario) Validate() error
• type Security
  • func (s *Security) Validate() error
• type Session
  • func (s *Session) Validate() error
• type Step
  • func (s *Step) EffectiveCalls() CallBounds
  • func (s *Step) Validate() error
• type StepElement
  • func (se StepElement) MarshalYAML() (interface{}, error)
  • func (se *StepElement) UnmarshalYAML(value *yaml.Node) error
  • func (se *StepElement) Validate() error
• type StepGroup
  • func (sg *StepGroup) UnmarshalYAML(value *yaml.Node) error
  • func (sg *StepGroup) Validate() error

Types

type CallBounds

type CallBounds struct {
	Min int `yaml:"min"`
	Max int `yaml:"max"`
}

CallBounds specifies the allowed invocation range for a step. When nil on a Step, EffectiveCalls() returns {Min: 1, Max: 1}.

func (*CallBounds) Validate

func (cb *CallBounds) Validate() error

Validate checks that the call bounds are valid.

type GroupRange

type GroupRange struct {
	Start    int    // Inclusive flat index of first group child
	End      int    // Exclusive flat index (Start + len(group.Steps))
	Name     string // Group name (resolved, never empty)
	TopIndex int    // Index of the group in the top-level Steps array
}

GroupRange describes the flat-index extent of a single step group.

type Match

type Match struct {
	Argv  []string `yaml:"argv"`
	Stdin string   `yaml:"stdin,omitempty"`
}

Match contains criteria for identifying an incoming CLI command.

func (*Match) Validate

func (m *Match) Validate() error

Validate checks that the match criteria is valid.

type Meta

type Meta struct {
	Name        string            `yaml:"name"`
	Description string            `yaml:"description,omitempty"`
	Vars        map[string]string `yaml:"vars,omitempty"`
	Security    *Security         `yaml:"security,omitempty"`
	Session     *Session          `yaml:"session,omitempty"`
}

Meta contains scenario metadata including identification and template variables.

func (*Meta) Validate

func (m *Meta) Validate() error

Validate checks that the meta section is valid.

type Response

type Response struct {
	Exit       int               `yaml:"exit"`
	Stdout     string            `yaml:"stdout,omitempty"`
	Stderr     string            `yaml:"stderr,omitempty"`
	StdoutFile string            `yaml:"stdout_file,omitempty"`
	StderrFile string            `yaml:"stderr_file,omitempty"`
	Delay      string            `yaml:"delay,omitempty"`
	Capture    map[string]string `yaml:"capture,omitempty"`
}

Response defines the output for a matched command.

func (*Response) Validate

func (r *Response) Validate() error

Validate checks that the response is valid.

func (*Response) ValidateDelay

func (r *Response) ValidateDelay(maxDelay time.Duration) error

ValidateDelay checks that the delay does not exceed the given maximum. A zero maxDelay disables the cap. Returns nil if no delay is set.

type Scenario

type Scenario struct {
	Meta  Meta          `yaml:"meta"`
	Steps []StepElement `yaml:"steps"`
}

Scenario represents a complete test definition loaded from a YAML file.

func Load

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

Load parses a scenario from the given reader with strict field validation. Unknown fields in the YAML will cause an error.

func LoadFile

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

LoadFile loads a scenario from the given file path.

func (*Scenario) FlatSteps

func (s *Scenario) FlatSteps() []Step

FlatSteps returns all leaf steps expanded inline. Groups are replaced by their child steps in order. The result preserves contiguous flat indices.

func (*Scenario) GroupRanges

func (s *Scenario) GroupRanges() []GroupRange

GroupRanges returns the flat-index ranges for all groups in the scenario.

func (*Scenario) Validate

func (s *Scenario) Validate() error

Validate checks that the scenario is valid.

type Security

type Security struct {
	AllowedCommands []string `yaml:"allowed_commands,omitempty"`
	DenyEnvVars     []string `yaml:"deny_env_vars,omitempty"`
}

Security defines constraints on which commands may be intercepted.

func (*Security) Validate

func (s *Security) Validate() error

Validate checks that the security configuration is valid.

type Session

type Session struct {
	TTL string `yaml:"ttl,omitempty"`
}

Session defines session lifecycle configuration.

func (*Session) Validate

func (s *Session) Validate() error

Validate checks that the session configuration is valid.

type Step

type Step struct {
	Match   Match       `yaml:"match"`
	Respond Response    `yaml:"respond"`
	Calls   *CallBounds `yaml:"calls,omitempty"`
	When    string      `yaml:"when,omitempty"`
}

Step represents a single command-response pair within a scenario.

func (*Step) EffectiveCalls

func (s *Step) EffectiveCalls() CallBounds

EffectiveCalls returns the call bounds for this step, applying defaults when the Calls field is nil (backward compatible: exactly one call).

func (*Step) Validate

func (s *Step) Validate() error

Validate checks that the step is valid.

type StepElement

type StepElement struct {
	Step  *Step      `yaml:"-"` // Set when YAML has match/respond (leaf step)
	Group *StepGroup `yaml:"-"` // Set when YAML has group key
}

StepElement is a union type — exactly one of Step or Group is non-nil. It represents either a leaf step or a group container in the steps array.

func (StepElement) MarshalYAML

func (se StepElement) MarshalYAML() (interface{}, error)

MarshalYAML implements custom YAML marshaling for StepElement. It serializes the underlying Step or group wrapper so that fields tagged yaml:"-" are emitted correctly.

func (*StepElement) UnmarshalYAML

func (se *StepElement) UnmarshalYAML(value *yaml.Node) error

UnmarshalYAML implements custom YAML unmarshaling for StepElement. It inspects the mapping keys to determine whether the node represents a leaf step (has "match") or a group (has "group"), then dispatches to the appropriate type.

func (*StepElement) Validate

func (se *StepElement) Validate() error

Validate checks that exactly one of Step or Group is set and validates it.

type StepGroup

type StepGroup struct {
	Mode  string        `yaml:"mode"`
	Name  string        `yaml:"name,omitempty"`
	Steps []StepElement `yaml:"steps"`
}

StepGroup defines a group of steps with unordered matching semantics.

func (*StepGroup) UnmarshalYAML

func (sg *StepGroup) UnmarshalYAML(value *yaml.Node) error

UnmarshalYAML implements custom YAML unmarshaling for StepGroup. It decodes the group's mode, name, and steps fields.

func (*StepGroup) Validate

func (sg *StepGroup) Validate() error

Validate checks that the step group is valid.