golden

Documentation

Overview

Package golden records a chaos fault fire-sequence from one test run and replays it deterministically in another, to turn a flaky CI failure into a reproducible local one.

Record installs a recording observer. On test cleanup it writes testdata/<name>.golden (JSON lines) when run with -chaos-update-golden (or CHAOS_UPDATE_GOLDEN=1). Replay reads that file, installs rules that reproduce the record fire/skip sequence via engine.Sequence and asserts the run does not diverge.

Fidelity: latency/jittered fires replay with their recorded duration. Short-circuiting fires (error, panic, connection drop), whose kind the observer cannot see, replay as a generic fault.Error(ErrReplay). Replay assumes a deterministic (effectively single-goroutine) evaluation order and is faithful when each original rule's selector is distinguishable by Op.Kind.

Usage — capture once, replay forever:

func TestCheckoutResilience(t *testing.T) {
	// Record: run `go test -chaos-update-golden` to (re)write testdata/checkout.golden.
	eng := chaostest.New(t, golden.Record(t, "checkout"))
	// ... configure your real chaos rules, run the scenario ...
	_ = eng
}

func TestCheckoutReplay(t *testing.T) {
	// Replay: deterministically reproduce the recorded fire-sequence and assert
	// the run does not diverge from testdata/checkout.golden.
	eng := chaostest.New(t, golden.Replay(t, "checkout"))
	// ... run the same scenario; divergence fails the test on cleanup ...
	_ = eng
}

Index

• Variables
• func Record(t testing.TB, name string) engine.Option
• func Replay(t testing.TB, name string) engine.Option

Variables

var ErrReplay = errors.New("chaotic/golden: replayed fault")

ErrReplay is the fault error injected for replayed short-circuiting fires whose original kind the observer could not see (error, panic, conn drop).

Functions

func Record

func Record(t testing.TB, name string) engine.Option

Record installs a recording observer on the engine and registers a t.Cleanup that writes testdata/<name>.golden when run with -chaos-update-golden (or CHAOS_UPDATE_GOLDEN=1). Without the update flag the cleanup does not write — Record is how you (re)generate a golden, not assert one.

Record occupies the engine's single observer slot for the test; a test that also needs a production observer must fan in manually.

func Replay

func Replay(t testing.TB, name string) engine.Option

Replay reads testdata/<name>.golden, installs rules that reproduce the recorded fire/skip sequence (via engine.Sequence), and on t.Cleanup asserts the run's fired sequence equals the golden (t.Errorf on divergence).

Like Record, it occupies the engine's single observer slot. Replay should be the sole rule source for the engine under test.