faultline v0.1.0

faultline v0.1.0 is the first release of deterministic simulation testing for Go, inside go test. A test runs a distributed system in virtual time on a simulated network and disk. faultline injects faults such as delayed and dropped messages, crashes and failed syncs, and checks your invariants after every event. Every random choice comes from one seed, so a failing seed replays the identical run, for you or for an AI coding agent.

Install

faultline needs Go 1.26 or newer. The first command adds faultline to your module, the second adds the etcd/raft harness, and the third installs the faultline command:

go get github.com/hmdsefi/faultline@v0.1.0
go get github.com/hmdsefi/faultline/harness/etcdraft@v0.1.0
go install github.com/hmdsefi/faultline/cmd/faultline@v0.1.0

The root module depends only on the standard library and gograph. The harness is a module of its own, so etcd/raft and protobuf stay out of your build unless you add it. Your tests do not need the faultline command; it re-renders an artifact directory.

What v0.1.0 contains

• faultline.Run runs one subtest per seed, checks invariants after every event and final checks after the run, and prints a replay command for a failing seed. Settings come from FAULTLINE_* environment variables, so go test ./... works across packages.
• kernel is the single-threaded simulator: virtual time, a seeded scheduler, named random streams, and nodes that crash, restart and pause, each with its own clock.
• kernel/simnet models links with latency, jitter, loss, duplication and reordering, plus partitions and one-way cuts. kernel/simdisk gives each node a volume with crash models for unsynced writes, failed syncs, capacity limits and corruption.
• kernel/fault treats faults as data. Random rules and scripts plan them, and every fault that ran is recorded in schedule.json. FAULTLINE_SCHEDULE replays a schedule, including one you edited to narrow a failure.
• A failing seed runs a second time and must give the same trace hash. FAULTLINE_CHECK_DETERMINISM=1 also runs every passing seed twice and reports the first record where two runs differ.
• A failing seed leaves an artifact directory: report.json, trace.jsonl, schedule.json, the client history when the test records one, a text timeline, a Mermaid diagram of the events that led to the failure, and timeline.html, an interactive timeline in one file that works offline.
• harness/etcdraft runs clusters of etcd/raft v3.7.0 with a write-ahead log on the simulated disk, a key-value workload, snapshots and membership changes, and checks for raft's safety properties after every event. faultline ran 40,000 seeds of the harness under the default faults, and no seed failed. Five bug switches break the harness on purpose, and the checks caught each one on the first seed.

Documentation

Use faultline with an AI coding agent walks an agent from a failing seed to a pinned regression test, and ends with a block for its AGENTS.md or CLAUDE.md. Get started builds a key-value server and its test from an empty module. The docs index lists the guides and reference pages, and llms.txt lists them for agents.

Compatibility

The API may change between v0.x releases. Every artifact file except report.txt carries a format version, and each one is at version 1. A seed replays the same run while the faultline version, the Go minor version, your code and the options stay the same; a replay warns about each one that changed. CI checks golden trace hashes on Linux on amd64 and macOS on arm64, with Go 1.26 and Go 1.27.

Known limitations

v0.1.0 runs code written against faultline's node API, and etcd/raft through the harness. Code that starts goroutines, uses net or opens files with os needs a port to the node API first. v0.1.0 does not shrink a failing run, and it has no linearizability or isolation checker. A test that calls t.Parallel needs Options.NoCryptoSeed, which leaves crypto/rand out of the replay. Limitations and FAQ has the full list and the issues known at release.

What comes next

The next phase runs existing goroutine code through testing/synctest, with drop-in replacements for net and a filesystem interface. The roadmap lists the phases after it.