...
TestServer and TestCluster are two frameworks we built to create Go unit tests for CockroachDB:, for tests that need a functional SQL layer and/or KV layer.
TestServer simulates a single CockroachDB node.
TestCluster simulates a multi-node CockroachDB cluster. Each node is simulated using one TestServer.
...
For integration tests, consider using roachtest instead. See: the page pages Overview of all test frameworks and Roachtest vs TestServer for details.
For other unit tests that do not need a full SQL or KV layer, consider a more narrow unit test that only instantiates the components it cares about. This will make the test run faster.
Here are the main differences between a regular CockroachDB node (e.g. one started via cockroach start) and one simulated via TestServer:
...
.StorageLayer()always points to the storage layer inside TestServer..SystemLayer()always points to the special system interface inside TestServer (previously known as “system tenant” in previous versions of CockroachDB).
Temporary API pitfall and misdesign
This section is the target of a redirect from a warning printed in tests when the test code uses an ApplicationLayerInterface method without calling .ApplicationLayer() first. For example:
| Code Block | ||
|---|---|---|
| ||
ts := serverutils.StartServerOnly(t, ...)
defer ts.Stopper().Stop(ctx)
addr := ts.RPCAddr() // prints warning, linking to this section |
...
)
...
| Code Block | ||
|---|---|---|
| ||
srv := serverutils.StartServerOnly(t, ...)
defer srv.Stopper().Stop(ctx)
ts := srv.ApplicationLayer()
addr := ts.RPCAddr() |
More detailed explanation
The reason for this warning is that as of this writing, TestServerInterface also contains the following interface embedding:
...
| language | go |
|---|
...
.
...
This was done because many tests were already implemented by the time .ApplicationLayer() was implemented.
However, this status quo is quite problematic.
Two problems result from this.
The first is incoherence: the following two excerpts are not equivalent, which is counter-intuitive and can be the source of bugs:
| Code Block |
|---|
srv, db, _ := StartServer(t, ...)
// vs.
srv := StartServerOnly(t, ...)
db := srv.ApplicationLayer().SQLConn(t, ...) |
The second problem is insufficient test coverage. If the test code only ever uses the implicit ApplicationLayerInterface, it will never be exposed to cluster virtualization via the randomization described above. So it will not exercise the relevant code paths and cluster virtualization will be under tested.
Bottom line: use .ApplicationLayer()!
...