Testing

CockroachDB tests come in five major flavors. Most contributors only need the first two.

1. Go unit tests

Live next to production code as *_test.go and use the standard testing package plus a few CRDB-specific helpers.

./dev test pkg/sql/parser
./dev test pkg/sql/parser -f=TestParse -v
./dev test pkg/util/log --race
./dev test pkg/sql --count=5 --stress

Common helpers worth knowing:

• testutils/skip — skip tests under race, deadlock, stress, etc.
• testutils/serverutils — boot a *server.TestServer and *kv.DB for integration tests.
• pkg/testutils/testcluster — a multi-node test cluster that wraps TestServer.
• pkg/util/leaktest — assert that a test does not leak goroutines.

Many tests start with defer leaktest.AfterTest(t)() to enforce that.

2. Data-driven tests

CRDB uses cockroachdb/datadriven extensively. Inputs and expected outputs live in testdata/ directories next to the code:

exec
SELECT * FROM foo
----
1 a
2 b

The test reads the directive, runs your handler, and rewrites the expected output if you pass -rewrite. This is the idiomatic way to test optimizer rules, MVCC, the lock table, the schema changer, the SQL planner, and many other layers.

./dev test pkg/sql/opt -f=TestOptRules -rewrite will regenerate the expectations in place. Inspect the diff carefully before committing.

3. SQL logic tests

pkg/sql/logictest/ is a port of SQLite's logic-test framework. Tests live in pkg/sql/logictest/testdata/logic_test/. Each file is a sequence of statements with expected results.

./dev testlogic --files=join --subtests=specific --config=local

Configurations control what cluster shape the tests run against (local, 5node, multiregion-9node-3region-3azs, local-mixed-25.4, …). Many bugs only reproduce in distributed configurations; CI runs every test under multiple configs.

4. Roachtests

Roachtests boot real cockroach processes on real (or simulated) hardware and exercise long-running, multi-hour scenarios — TPC-C imports, schema changes under load, decommissioning, version upgrades, network partitions. They live in pkg/cmd/roachtest/.

Roachtests are not part of the per-PR CI loop. They run on a nightly schedule and are configured via roachprod (pkg/cmd/roachprod/).

./dev build roachtest
./bin/roachtest run "tpcc/nodes=3" --local       # local, smaller version

5. Acceptance tests

pkg/acceptance/ boots a small set of CockroachDB containers via Docker Compose and runs end-to-end smoke tests. They mostly verify packaging and CLI behavior.

Other useful tools

• ./dev testlogic is a thin wrapper around bazel test //pkg/sql/logictest/tests/... with sane defaults.
• ./dev test pkg/... --stress --stressflags='-p 4' runs the stress harness from pkg/cmd/cockroach-short with N parallel runners.
• ./dev test pkg/... --record enables go test -test.profile for cpu profiling during a run.
• testutils/echotest — golden-file tests where the test compares stdout/stderr to a recorded expected file.
• pkg/sql/sqltestutils — shared helpers for building test schemas.

Test environment knobs

Some tests honor these:

• COCKROACH_RANDOM_SEED — reproducible randomized tests.
• GOEXPERIMENT= — Go runtime experiments.
• COCKROACH_DEV_LICENSE — used by some tests that exercise CCL features.
• KV_RANGEFEED_USE_NEW_PROCESSOR — many feature flags toggle behavior in tests.

Picking the right level

You changed	Run
A pure helper in pkg/util/...	unit tests in that package
An optimizer rule	datadriven tests in pkg/sql/opt/...
SQL semantics	a logictest
KV server semantics	unit tests + pkg/kv/kvserver/kvnemesis/ if invariants might break
End-to-end behavior	a roachtest (file in same PR or a follow-up)

When in doubt, look at how a similar feature was tested and follow that pattern.