Overview

TestServer and TestCluster are two frameworks we built to create Go unit tests for CockroachDB:

TestServer simulates a single CockroachDB node.
TestCluster simulates a multi-node CockroachDB cluster. Each node is simulated using one TestServer.

By default, TestServer uses in-RAM storage (not persisted) to make tests faster..

Here are the main differences between a regular CockroachDB node (e.g. one started via cockroach start) and one simulated via TestServer:

Component	Behavior in `cockroach start`	Behavior in TestServer
SQL, HTTP and KV layers	identical
Coordination glue around SQL/HTTP/KV to create an overall running server (`topLevelServer` in code)	identical
Server configuration	Via CLI flags, defaults useful for production deployments	via `TestServerArgs` struct; defaults useful for testing. For example, KV storage is in-RAM by default (no persistence) to make tests faster.

Introduction to TestServer and TestCluster in Go unit tests

Tests mostly use the following programming pattern:

func TestSomething(t *testing.T) {
  defer leaktest.AfterTest()()  // verify no goroutine leaks
  defer log.Scope(t).Close(t)   // capture test logs intelligently

  ctx := context.Background()
  srv := serverutils.StartServerOnly(t, base.TestServerArgs{})  // initialize and start a TestServer
  defer srv.Stopper().Stop(ctx) // ensure the TestServer gets cleaned up at the end of the test
  
  ts := srv.ApplicationLayer()  // see below for an explanation
  
  // ... use ts in test code ...