e2e

Documentation

Overview

Package e2e provides user-facing scenario-based E2E test infrastructure.

Package e2e provides user-facing scenario-based E2E test infrastructure.

Package e2e provides user-facing scenario-based E2E test infrastructure.

Package e2e provides user-facing scenario-based E2E test infrastructure.

Package e2e provides user-facing scenario-based E2E test infrastructure.

Package e2e provides user-facing scenario-based E2E test infrastructure.

Package e2e provides user-facing scenario-based E2E test infrastructure.

Index

• Variables
• func MissingScenarioRequirements(s Scenario, available []string) []string
• func RenderScenarios(set *ScenarioSet) ([]byte, error)
• func ResolveBuildDir(projectDir string, entry BuildEntry) string
• func ResolveEnv(opts EnvResolveOptions) (map[string]string, error)
• type BuildEntry
  • func MatchBuild(scenario Scenario, builds []BuildEntry) *BuildEntry
  • func ParseBuildLine(line string) []BuildEntry
• type EnvResolveOptions
• type RunOutput
• type Runner
  • func NewRunner(opts RunnerOptions) *Runner
  • func (r *Runner) Run(scenario Scenario) (*RunnerResult, error)
• type RunnerOptions
• type RunnerResult
  • func (r *RunnerResult) WorkDirExists() (bool, error)
• type Scenario
  • func ExtractCobra(dir string) ([]Scenario, error)
• type ScenarioSet
  • func ParseScenarios(content []byte) (*ScenarioSet, error)
  • func SyncScenarios(existing *ScenarioSet, commands []Scenario) (*ScenarioSet, error)
• type VerifyResult
  • func CheckExitCode(expected int, actual int) VerifyResult
  • func CheckFileContains(path string, substr string) VerifyResult
  • func CheckFileExists(path string) VerifyResult
  • func CheckStderrEmpty(stderr string) VerifyResult
  • func CheckStdoutContains(substr string, stdout string) VerifyResult

Variables

var ErrSkipScenario = errors.New("scenario skipped: required env not available")

ErrSkipScenario indicates a scenario should be skipped (e.g., missing API key in CI).

Functions

func MissingScenarioRequirements

func MissingScenarioRequirements(s Scenario, available []string) []string

MissingScenarioRequirements returns the normalized requirements not present in the available capability set.

func RenderScenarios

func RenderScenarios(set *ScenarioSet) ([]byte, error)

@AX:NOTE [AUTO] @AX:REASON: public API boundary — sole serializer for scenarios.md; parse/render must remain symmetric; fan_in=1 (pkg/setup/scenarios.go) RenderScenarios renders a ScenarioSet back to scenarios.md markdown.

func ResolveBuildDir

func ResolveBuildDir(projectDir string, entry BuildEntry) string

ResolveBuildDir resolves a BuildEntry's SubmodulePath to a full directory path. Falls back to projectDir when SubmodulePath is empty.

func ResolveEnv

func ResolveEnv(opts EnvResolveOptions) (map[string]string, error)

@AX:NOTE [AUTO] @AX:REASON: public API boundary — 4-layer env merge contract (project detection → safe defaults → per-scenario override → test.env); layer order must not be changed; fan_in=0 (currently unused outside package tests) ResolveEnv resolves environment variables using the 4-layer hierarchy. Returns merged env map and nil error on success. Returns ErrSkipScenario if a required secret is missing in non-interactive mode.

Types

type BuildEntry

type BuildEntry struct {
	Command       string // e.g., "go build ./cmd/auto/"
	Label         string // e.g., "ADK" (empty for single build)
	SubmodulePath string // e.g., "autopus-adk" (resolved from label)
}

BuildEntry represents a single build command with optional label and submodule mapping.

func MatchBuild

func MatchBuild(scenario Scenario, builds []BuildEntry) *BuildEntry

MatchBuild finds the BuildEntry matching a scenario's section header. Returns nil if no match is found or builds is empty. A single unlabeled build matches any scenario.

func ParseBuildLine

func ParseBuildLine(line string) []BuildEntry

ParseBuildLine parses a comma-separated build line into individual BuildEntries. Each entry may have an optional (Label) suffix that maps to a submodule path.

type EnvResolveOptions

type EnvResolveOptions struct {
	ProjectDir     string            // project root directory
	ScenarioEnv    map[string]string // per-scenario env overrides
	NonInteractive bool              // true if TTY is NOT available (CI mode)
	TestEnvFile    string            // path to .autopus/test.env (optional)
	RequiredVars   []string          // env vars that must be resolved
}

EnvResolveOptions configures the environment resolver.

type RunOutput

type RunOutput struct {
	Stdout   string // captured standard output
	Stderr   string // captured standard error
	ExitCode int    // command exit code
	WorkDir  string // temp directory where command ran
}

RunOutput holds captured command output for verification.

type Runner

type Runner struct {
	// contains filtered or unexported fields
}

Runner executes E2E scenarios.

func NewRunner

func NewRunner(opts RunnerOptions) *Runner

@AX:NOTE [AUTO] @AX:REASON: magic constant — 30s default per-scenario timeout; adjust for slow integration tests or network-dependent scenarios NewRunner creates a new Runner with the given options.

func (*Runner) Run

func (r *Runner) Run(scenario Scenario) (*RunnerResult, error)

@AX:NOTE [AUTO] @AX:REASON: public API boundary — primary scenario execution entry point; fan_in=1 (internal/cli/test.go); sync.Once ensures build runs exactly once per Runner instance Run executes a single scenario and returns the result.

type RunnerOptions

type RunnerOptions struct {
	ProjectDir   string        // project root directory
	AutoBuild    bool          // auto-build binary before first run
	BuildCommand string        // build command (e.g., "go build -o auto .") — legacy single-build
	Builds       []BuildEntry  // multi-build entries; takes precedence over BuildCommand
	Timeout      time.Duration // per-scenario timeout (default: 30s)
}

RunnerOptions configures the scenario runner.

type RunnerResult

type RunnerResult struct {
	ExitCode       int    // command exit code
	Stdout         string // captured stdout
	Stderr         string // captured stderr
	Pass           bool   // true if all verify primitives passed
	FailureDetails string // human-readable failure description
	TimedOut       bool   // true if command exceeded timeout
	BuildOccurred  bool   // true if auto-build was triggered this run
	WorkDir        string // temp directory used for this run
}

RunnerResult holds the result of a scenario execution.

func (*RunnerResult) WorkDirExists

func (r *RunnerResult) WorkDirExists() (bool, error)

WorkDirExists checks if the work directory still exists. Returns an error if the directory has been removed (expected after cleanup).

type Scenario

type Scenario struct {
	Number       int      // S{N}
	ID           string   // unique identifier (e.g., "init", "doctor", "custom-mytest")
	Description  string   // short description
	Command      string   // command to execute
	Precondition string   // comma-separated preconditions
	Env          string   // KEY=value pairs or "N/A"
	Expect       string   // expected result
	Verify       []string // verification primitives
	Depends      string   // dependency (e.g., "S1" or "N/A")
	Requires     string   // comma-separated capabilities or "N/A"
	Status       string   // active | deprecated | skip
	Section      string   // section header (e.g., "ADK CLI Scenarios")
}

Scenario represents a single E2E test scenario.

func ExtractCobra

func ExtractCobra(dir string) ([]Scenario, error)

@AX:NOTE [AUTO] @AX:REASON: public API boundary — go/ast-based Cobra extractor; only leaf commands (HasRun=true) are emitted; fan_in=1 (pkg/setup/scenarios.go) ExtractCobra scans Go source files in the given directory for Cobra command definitions and returns a list of scenarios for leaf commands.

type ScenarioSet

type ScenarioSet struct {
	ProjectName string
	ProjectType string // CLI | API | Frontend | Library
	Binary      string
	Build       string       // raw build line (backward compat)
	Builds      []BuildEntry // parsed build entries
	Scenarios   []Scenario
}

ScenarioSet represents a complete scenarios.md document.

func ParseScenarios

func ParseScenarios(content []byte) (*ScenarioSet, error)

@AX:NOTE [AUTO] @AX:REASON: public API boundary — sole entry point for scenarios.md deserialization; fan_in=1 (internal/cli/test.go) ParseScenarios parses scenarios.md content into a ScenarioSet.

func SyncScenarios

func SyncScenarios(existing *ScenarioSet, commands []Scenario) (*ScenarioSet, error)

@AX:NOTE [AUTO] @AX:REASON: design choice — "custom-" prefix is a reserved namespace for user-written scenarios; auto-sync never modifies or deprecates them; fan_in=0 (no production callers yet — used only in tests) SyncScenarios merges extracted commands into the existing ScenarioSet. Rules:

• New commands not in existing set are added with status "active".
• Existing scenarios whose command was removed are marked "deprecated".
• Scenarios with "custom-" prefix are preserved unchanged.
• Existing scenarios that match a current command retain their status.

type VerifyResult

type VerifyResult struct {
	Primitive string // e.g., "exit_code(0)"
	Pass      bool
	Message   string // human-readable result (e.g., "expected exit_code(0), got 1")
}

VerifyResult represents the outcome of a single verification check.

func CheckExitCode

func CheckExitCode(expected int, actual int) VerifyResult

CheckExitCode verifies that the actual exit code matches the expected value. Returns PASS if codes match, FAIL with descriptive message if they differ.

func CheckFileContains

func CheckFileContains(path string, substr string) VerifyResult

CheckFileContains verifies that a file at the given path contains the expected substring. Returns PASS if the substring is found, FAIL with message if not found or file doesn't exist.

func CheckFileExists

func CheckFileExists(path string) VerifyResult

CheckFileExists verifies that a file exists at the given path. Returns PASS if the file exists, FAIL with message if it does not.

func CheckStderrEmpty

func CheckStderrEmpty(stderr string) VerifyResult

CheckStderrEmpty verifies that stderr output is empty. Returns PASS if stderr is empty, FAIL with message if it contains data.

func CheckStdoutContains

func CheckStdoutContains(substr string, stdout string) VerifyResult

CheckStdoutContains verifies that the given substring is present in stdout. Returns PASS if found, FAIL with a descriptive message if not found.