Prove It Twice

// internal/sim/gen_test.go
package sim

import "testing"

func TestGenerateRepeatsItself(t *testing.T) {
	first := Generate(12, 8, 5).Render()
	second := Generate(12, 8, 5).Render()

	if first != second {
		t.Fatalf("seed 5 grew two different worlds:\n%s\n%s", first, second)
	}
}

$ go test -v -run TestGenerate ./internal/sim/   (elapsed times measured on the author's machine; yours will differ)
=== RUN   TestGenerateRepeatsItself
--- PASS: TestGenerateRepeatsItself (0.00s)
PASS
ok  	theworld/internal/sim	0.002s

$ go test ./...
?   	theworld/cmd/worldd	[no test files]
ok  	theworld/internal/sim	0.010s

A test reports failure by calling a method on t, and never by returning a value or panicking. t.Fatalf formats a message, marks the test failed, and stops that test function there; its sibling t.Errorf marks the failure and keeps going, for when several independent checks each deserve reporting. Nothing prints on success unless you ask, which is what -v does. The message matters as much as the check: it is written for the version of you who reads it at midnight with no memory of this file, so it says what was compared and shows both sides.

The second command runs every package in the module. cmd/worldd has no tests, and Go says so plainly instead of pretending it passed. The tool is also aggressive about not repeating work: run go test twice without changing anything and the second run answers ok theworld/internal/sim (cached) in no time at all, because the result of a test whose code and inputs are unchanged cannot have changed either. That is a convenience most of the time and a trap when you are chasing something that only fails sometimes, so a chapter about nondeterminism keeps -count=1 within reach.

// internal/sim/run.go
package sim

import (
	"fmt"
	"time"
)

// Config is everything one run of the world needs to know. Every
// field is a decision the caller makes; nothing here is read from the
// machine.
type Config struct {
	Seed  uint64 // names the world and every draw inside it
	Ticks uint64 // how many ticks to take before stopping
	Log   string // where the event log is written
	Paced bool   // deliver ticks at TickRate, or as fast as they compute
}

// Run plays one world from beginning to end and writes its history to
// cfg.Log. It returns when the world has taken cfg.Ticks ticks, or
// when stop is closed, whichever happens first.
func Run(cfg Config, stop <-chan struct{}) error {
	lg, err := OpenLog(cfg.Log)
	if err != nil {
		return err
	}
	defer lg.Close()

	if err := lg.Append(Event{Kind: "start", What: fmt.Sprintf("seed %d", cfg.Seed)}); err != nil {
		return err
	}

	w := NewWorld(Generate(12, 8, cfg.Seed), cfg.Seed)
	w.Record(lg)
	for _, s := range []struct {
		kind EntityKind
		at   Coord
	}{
		{Shrub, Coord{X: 2, Y: 5}},
		{Walker, Coord{X: 10, Y: 6}},
		{Walker, Coord{X: 2, Y: 2}},
	} {
		if _, err := w.Spawn(s.kind, s.at); err != nil {
			return err
		}
	}

	var beat <-chan time.Time
	if cfg.Paced {
		t := time.NewTicker(TickDuration)
		defer t.Stop()
		beat = t.C
	}

	reason := "ticks complete"
	for w.Tick() < cfg.Ticks {
		if beat != nil {
			<-beat
		}
		select {
		case <-stop:
			reason = "stopped"
		default:
		}
		if reason == "stopped" {
			break
		}
		if err := w.Step(); err != nil {
			return err
		}
		if err := w.Faulted(); err != nil {
			return err
		}
	}
	return lg.Append(Event{Tick: w.Tick(), Kind: "stop", What: reason})
}

// cmd/worldd/main.go — flags, signals, and the goroutine
func main() {
	seed := flag.Uint64("seed", 5, "the number that names this world")
	ticks := flag.Uint64("ticks", 600, "how many ticks to take")
	logPath := flag.String("log", "world.jsonl", "where to write the event log")
	fast := flag.Bool("fast", false, "deliver ticks as fast as they compute")
	flag.Parse()

	cfg := sim.Config{Seed: *seed, Ticks: *ticks, Log: *logPath, Paced: !*fast}
	fmt.Printf("worldd %s seed %d ticks %d -> %s\n", version, cfg.Seed, cfg.Ticks, cfg.Log)

	stop := make(chan struct{})
	sig := make(chan os.Signal, 1)
	signal.Notify(sig, os.Interrupt, syscall.SIGTERM)
	go func() {
		<-sig
		close(stop)
	}()

	done := make(chan error, 1)
	go func() { done <- sim.Run(cfg, stop) }()

	if err := <-done; err != nil {
		fmt.Fprintln(os.Stderr, "worldd:", err)
		os.Exit(1)
	}
	fmt.Println("worldd: the world stopped cleanly")
}

$ go run ./cmd/worldd -fast -ticks 600 -log a.jsonl
worldd 0.0.1 seed 5 ticks 600 -> a.jsonl
worldd: the world stopped cleanly

Two decisions in Config are deliberate. The seed and the tick count are inputs a caller supplies, so a run is fully described by a value you can print, store, and paste into a bug report. And Paced separates the delivery of ticks from their content, which is chapter 7's rule finally paying a dividend. Paced, the ticker hands out a tick every hundred milliseconds and 600 ticks take a minute; with -fast the same 600 ticks land as quickly as the processor can compute them, and the resulting world is identical in every respect, because nothing inside the simulation has any way to ask how long a tick took. A minute of world, verifiable in milliseconds.

Run ends by writing a stop line naming why it stopped. Two runs that both finished their tick count agree on that line; a run cut short by a signal records the tick it actually reached, which is a real difference in what happened and belongs in the history.

// internal/sim/replay_test.go
package sim

import (
	"bytes"
	"os"
	"path/filepath"
	"testing"
)

// history plays one world into a file of its own and returns every
// byte the run wrote.
func history(t *testing.T, cfg Config) []byte {
	t.Helper()
	cfg.Log = filepath.Join(t.TempDir(), "world.jsonl")
	if err := Run(cfg, nil); err != nil {
		t.Fatalf("run seed %d: %v", cfg.Seed, err)
	}
	b, err := os.ReadFile(cfg.Log)
	if err != nil {
		t.Fatalf("read log: %v", err)
	}
	return b
}

// firstDiff reports the number of the first line on which two
// histories disagree, and both versions of it.
func firstDiff(a, b []byte) (int, string, string) {
	x := bytes.Split(a, []byte("\n"))
	y := bytes.Split(b, []byte("\n"))
	for i := 0; i < len(x) && i < len(y); i++ {
		if !bytes.Equal(x[i], y[i]) {
			return i + 1, string(x[i]), string(y[i])
		}
	}
	return min(len(x), len(y)) + 1, "", ""
}

// body drops the start line, which names the seed and so is expected
// to differ between two worlds.
func body(b []byte) []byte {
	_, rest, _ := bytes.Cut(b, []byte("\n"))
	return rest
}

func TestSameSeedSameHistory(t *testing.T) {
	cfg := Config{Seed: 5, Ticks: 600}

	first := history(t, cfg)
	second := history(t, cfg)

	if len(first) == 0 {
		t.Fatal("the run wrote no history at all")
	}
	if !bytes.Equal(first, second) {
		n, a, b := firstDiff(first, second)
		t.Fatalf("two runs of seed %d disagree at line %d\n  run 1: %s\n  run 2: %s",
			cfg.Seed, n, a, b)
	}
	t.Logf("seed %d: %d bytes of history, identical twice", cfg.Seed, len(first))
}

func TestDifferentSeedsDifferentHistories(t *testing.T) {
	five := history(t, Config{Seed: 5, Ticks: 600})
	nine := history(t, Config{Seed: 9, Ticks: 600})

	if bytes.Equal(body(five), body(nine)) {
		t.Fatal("seeds 5 and 9 wrote the same history; the seed is being ignored")
	}
	n, _, _ := firstDiff(body(five), body(nine))
	t.Logf("seeds 5 and 9 part company at event %d", n)
}

$ go test -v ./internal/sim/   (elapsed times measured on the author's machine; yours will differ)
=== RUN   TestGenerateRepeatsItself
--- PASS: TestGenerateRepeatsItself (0.00s)
=== RUN   TestSameSeedSameHistory
    replay_test.go:59: seed 5: 65804 bytes of history, identical twice
--- PASS: TestSameSeedSameHistory (0.00s)
=== RUN   TestDifferentSeedsDifferentHistories
    replay_test.go:70: seeds 5 and 9 part company at event 4
--- PASS: TestDifferentSeedsDifferentHistories (0.00s)
PASS
ok  	theworld/internal/sim	0.010s

Sixty-five thousand bytes of world, written twice, with no byte out of place. Three small decisions hold that result up. t.TempDir() hands back a fresh directory per call, which the log's design demands: the file is opened for append, so two runs pointed at one path would stack their histories into one file and the test would compare something other than what it claims. t.Helper() marks history as plumbing, so a failure inside it is reported at the calling line in the test. And the second test stops the first from being a fraud: a Run that ignored its seed, or wrote nothing at all, would sail through an equality check. Something has to insist that different seeds still produce different worlds, and that they diverge at the fourth event, the first move either walker makes.

go build -o worldd ./cmd/worldd
rm -f a.jsonl b.jsonl
./worldd -fast -seed 5 -ticks 600 -log a.jsonl
./worldd -fast -seed 5 -ticks 600 -log b.jsonl
diff -u a.jsonl b.jsonl && echo "identical"

$ ./worldd -fast -seed 5 -ticks 600 -log a.jsonl; ./worldd -fast -seed 5 -ticks 600 -log b.jsonl
worldd 0.0.1 seed 5 ticks 600 -> a.jsonl
worldd: the world stopped cleanly
worldd 0.0.1 seed 5 ticks 600 -> b.jsonl
worldd: the world stopped cleanly

$ diff -u a.jsonl b.jsonl && echo "identical"; wc -l a.jsonl b.jsonl
identical
   953 a.jsonl
   953 b.jsonl
  1906 total

$ sha256sum a.jsonl b.jsonl
4cb81462cf8875fc307dceacba66f8e51fc7b8777866edaf3c271ea06c5d5139  a.jsonl
4cb81462cf8875fc307dceacba66f8e51fc7b8777866edaf3c271ea06c5d5139  b.jsonl

diff printing nothing is the whole result: 953 lines apiece and no line that differs, from two processes that shared no memory and ran at different moments on a machine doing other things in between. The checksums say it in one number each. Two tools, two definitions of "the same", one verdict.