Testing

Consul's test suite is large and layered. This page is a map of what runs where.

Layers

Layer	Lives in	Run with
Unit tests	*_test.go next to the code	go test ./..., make test-internal
Race tests	Same files, -race	make test-race
FSM and state-store tests	agent/consul/state/*_test.go, agent/consul/fsm/*_test.go	go test ./agent/consul/state/...
xDS golden tests	agent/xds/*_test.go + agent/xds/testdata/	go test ./agent/xds/...
API client tests	api/*_test.go	go test ./api/...
Connect/Envoy integration	test/integration/connect/envoy/	make test-envoy-integ
Deployer-based integration	test-integ/ + testing/deployer/	make test-deployer, make test-compat-integ
Metrics integration	test-integ/metricsintegration/	make test-metrics-integ
CLI tests	command/*/command_test.go	go test ./command/...

make test runs lint plus the root module's internal tests. make test-all walks every Go module.

Running selectively

# Whole package
go test -v ./agent/consul

# A single test or pattern
go test -v -run TestRetryJoin ./command/agent

# Use -short to skip slow tests where the package supports it
go test -short ./agent/...

Many packages register testing.Short() checks; honor them when adding new tests.

Test helpers

• testagent.go — agent.NewTestAgent boots an in-process agent with a freeport-allocated port set. Used by most agent tests.
• agent/consul/testserver.go (in older versions) and agent/consul/server_test.go helpers — boot a Raft + state store under test.
• sdk/testutil/ — public helpers (TestServer, TestServerConfigCallback) for code that integrates with Consul.
• sdk/freeport/ — race-free port allocator used everywhere.
• agent/consul/testdata/ — shared certs, keys, and fixtures.
• agent/proxycfg/testing*.go — fixture builders for proxy snapshots.
• agent/xds/testdata/ — golden Envoy resource JSON files for the xDS server tests.

Golden tests

The xDS server (agent/xds/) and proxy config snapshots are tested by comparing serialized output to checked-in JSON files under agent/xds/testdata/. To regenerate:

go test ./agent/xds -update

Inspect the diff carefully — golden files are how the team enforces stable Envoy resource layouts.

Mocks

Mocks are generated with mockery (pinned to v3.5.2 in the Makefile). The configuration lives at .grpcmocks.yaml. Mock files are checked in alongside their interfaces. To regenerate:

make mocks-tools
make mocks

Integration tests

Most operator-visible integration suites use the HashiCorp Deployer to spin up Docker topologies of Consul + dataplane + applications, then run RPC and HTTP assertions. Required Docker images are pulled in make test-deployer-setup.

Envoy integration tests in test/integration/connect/envoy/ are bash-driven and use docker-compose. They drive a real Envoy and verify mTLS, intentions, and traffic management.

Coverage

make cover   # runs tests with -cover and opens an HTML report

make cov is an alias.