tests

The integration / e2e / robustness module. Source: tests/.

Purpose

go.etcd.io/etcd/tests/v3 is its own module so that test-only dependencies (the framework, mocks, fault injection, large fixtures) do not pollute the production module graph. It is the boundary where the test suite is allowed to import every other workspace module.

Directory layout

tests/
├── go.mod
├── main_test.go             # shared test setup
├── common/                  # tests that run in BOTH integration and e2e modes
├── e2e/                     # forks etcd / etcdctl binaries; talks over real sockets
├── integration/             # in-process multi-member clusters (tests/framework/integration)
├── framework/               # Cluster abstractions
│   ├── interfaces/          # Cluster / Member / Client interfaces
│   ├── integration/         # In-process implementation (cluster.go, 1,703 lines)
│   ├── e2e/                 # Subprocess implementation
│   ├── unit/                # Lightweight in-test fixtures
│   ├── config/              # Shared cluster config
│   ├── testutils/           # Helpers
│   └── testrunner.go        # Wires the chosen framework into TestMain
├── fixtures/                # TLS certs, keys, data files
├── robustness/              # Linearizability / fault-injection harness
└── antithesis/              # Deterministic-simulation tests

Key abstractions

Symbol	File	Description
framework.Cluster interface	tests/framework/interfaces/cluster.go	Common API used by both integration and e2e tests
integration.Cluster	tests/framework/integration/cluster.go	Spawns multiple embed.Etcd instances in one process
e2e.EtcdProcessCluster	tests/framework/e2e/cluster.go	Forks etcd binaries and manages their lifecycle
BeforeTest	tests/integration/main_test.go	Goroutine-leak detection wrapper used by every integration test
robustness Traffic interface	tests/robustness/traffic/traffic.go	Pluggable workload generator
robustness failpoint.Failpoint interface	tests/robustness/failpoint/failpoint.go	Fault-injection primitives
robustness validate.Linearizability	tests/robustness/validate/...	Porcupine-based linearizability checker

How tests are organized

• Unit tests — colocated with the package they test (e.g. server/storage/mvcc/kvstore_test.go).
• Integration tests — under tests/integration/, run via make test-integration.
• e2e tests — under tests/e2e/, depend on actual binaries (make build first), run via make test-e2e.
• Common tests — under tests/common/, parameterized by tests/framework/testrunner.go so the same Go code runs in both integration and e2e mode.
• Robustness tests — under tests/robustness/, run via make test-robustness.
• Coverage harness — tests/robustness/coverage/ for integrating with bbolt's coverage harness.

Antithesis

tests/antithesis/ contains the workloads, validators, and Dockerfiles that run inside Antithesis's deterministic-simulation environment (see .github/workflows/antithesis-*.yml). The runs explore failure scenarios that are statistically unreachable by the local robustness suite.

Integration points

• Imports every other workspace module.
• Uses pkg/expect and pkg/proxy heavily for child-process control and fault injection.
• Uses tools/local-tester/ and tools/benchmark/ for some performance-flavored tests.

Entry points for modification

• New common test (covers integration and e2e) → tests/common/, plus a small adapter in tests/integration/ and tests/e2e/.
• New cluster-level fixture → tests/framework/integration/cluster.go (in-process) and tests/framework/e2e/cluster.go (subprocess).
• New robustness traffic / fault → tests/robustness/traffic/ or tests/robustness/failpoint/, then register in tests/robustness/main_test.go.