Documentation
¶
Overview ¶
Package cmpfixture is the comparison-test harness for go-bash. Each fixture is a JSON file describing a script, optional VFS files, optional env, optional cwd, and the expected stdout / stderr / exit code. Run loads one fixture and asserts a *Bash instance produces the expected output byte-for-byte.
This is a Go-specific regression fixture format, not upstream's ID-keyed comparison fixture format. Upstream fixtures require conversion and recorded expectations need provenance before they establish parity. Future enhancements (Phase 19) will add the RECORD_FIXTURES re-recording path and the locked-fixture skip logic; for Phase 10 we only need the read-side loader so Wave A built-ins can ship with at least one fixture each.
Cited surface: the spec, §19.2.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Run ¶
Run loads the fixture at path and asserts a *Bash configured from its files/env/cwd produces the expected stdout / stderr / exitCode when Exec(fixture.Script) runs. The harness fails the test via t.Errorf for any divergence and t.Fatalf for setup errors.
func RunDir ¶
RunDir runs every *.json fixture in dir as a subtest. Files are sorted by name for deterministic test ordering; non-JSON entries and subdirectories are skipped. An empty fixture directory fails rather than silently reporting successful comparison coverage.
func RunFixture ¶
RunFixture runs an in-memory fixture (useful for tests that generate a fixture programmatically). Caller is responsible for passing a non-nil fx.
Types ¶
type Expected ¶
type Expected struct {
Stdout string `json:"stdout"`
Stderr string `json:"stderr"`
ExitCode int `json:"exitCode"`
}
Expected is the result triple a fixture pins. ExitCode is the script's exit status; Stdout and Stderr are byte-exact.
type Fixture ¶
type Fixture struct {
// Script is the bash source the fixture exercises. Required.
Script string `json:"script"`
// Files seeds the in-memory filesystem before Exec runs. The
// value is the file content as a string (UTF-8). Phase 10 does
// not yet need binary content; if Phase 14+ needs it, add a
// `filesBase64` companion field.
Files map[string]string `json:"files,omitempty"`
// Env seeds the per-Bash environment. Merged on top of the
// default ProcessInfo-derived env.
Env map[string]string `json:"env,omitempty"`
// Cwd overrides the default working directory. Empty leaves the
// gobash.New default (/home/user when Files is empty, / otherwise).
Cwd string `json:"cwd,omitempty"`
// Locked marks a fixture whose expected block has been hand-edited
// (typically to paper over a TS-vs-Go divergence). The Phase 19
// recorder skips locked fixtures unless RECORD_FIXTURES=force.
// Phase 10's loader treats locked fixtures identically to unlocked
// ones — we still run and assert against `expected`.
Locked bool `json:"locked,omitempty"`
// Expected is the recorded result of running Script under real
// bash (or, for hand-locked fixtures, the negotiated expected
// shape). Run asserts BashExecResult equals this block.
Expected Expected `json:"expected"`
}
Fixture is the Go-specific on-disk shape of a regression fixture. It is not directly compatible with just-bash's comparison fixtures.
Source Files