Testing

etcd's tests are organized into tiers. Most production changes need at least a unit test; new features almost always require an integration or e2e test as well.

Tiers

Tier	Location	What it does
Unit	*_test.go next to package source	Pure-Go tests, no IPC, no fork
Integration	tests/integration/	Spawns multi-member clusters in-process via tests/framework/integration/cluster.go; fastest "real" tests
End-to-end	tests/e2e/	Forks the actual etcd / etcdctl binaries, talks gRPC and HTTP over real sockets
Common framework tests	tests/common/ + tests/framework/	Same Go test binaries run in both integration and e2e modes via tests/framework/testrunner.go
Robustness	tests/robustness/	Linearizability + fault-injection harness; spawns clusters, hammers them, checks history
Antithesis	tests/antithesis/	Deterministic-simulation runs in Antithesis; see .github/workflows/antithesis-*.yml
Fuzzing	Native Go fuzz targets, e.g. server/etcdserver/api/v3rpc/validationfuzz_test.go	Driven by make fuzz / scripts/fuzzing.sh

Make targets

Target	Effect
make test-unit	All unit tests in the workspace
make test-integration	tests/integration/...
make test-e2e	tests/e2e/... (depends on make build)
make test-grpcproxy-integration / make test-grpcproxy-e2e	Same, but with the gRPC proxy in front
make test-robustness	tests/robustness/; see tests/robustness/Makefile for sub-targets
make test-coverage	Builds with -cover and aggregates covdir/
make test-release / make test-e2e-release	Asserts release-only invariants

scripts/test.sh is the single entry point; PASSES="unit integration release e2e" etc. select the sub-stage.

Filtering

scripts/test.sh honors the standard Go test flags:

GO_TEST_FLAGS='-run TestPeriodicSkipRevNotChange' make test-unit

For tests/integration/, point the runner at a single subdirectory:

go test -v ./tests/integration/clientv3/lease/...

Robustness tests in detail

tests/robustness/ is a full Jepsen-style harness:

• traffic/ defines the workload (key-value, lease, watch, txn).
• failpoint/ injects crashes, slowdowns, partition events via gofail hooks compiled into etcd via go build -tags=failpoint.
• validate/ checks the recorded history for linearizability and watch invariants.
• report/ produces HTML reports with sequence diagrams.

Running the full suite locally takes hours; CI shards it. See tests/robustness/README.md for invocation examples.

Flake handling

Flakes are tracked under the type/flake GitHub label. The recommended reproduction loop is go install golang.org/x/tools/cmd/stress, then:

cd server/etcdserver/api/v3compactor
go test -v -c -count 1
stress -p=8 ./v3compactor.test -test.run "^TestPeriodicSkipRevNotChange$"

tools/testgrid-analysis/ ingests the testgrid history to surface the most flaky tests over time.

Coverage

make test-coverage produces a covdir/ directory; scripts/codecov_upload.sh uploads to https://codecov.io/gh/etcd-io/etcd. Coverage is informational, not a gating signal.

Failpoints in dev builds

To enable failpoints in your local etcd, build with the failpoint tag:

GO_BUILD_FLAGS='-tags failpoint' make build

The robustness Makefile (tests/robustness/Makefile) automates this when needed.