Page Comparison

...

• .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:

ts := serverutils.StartServerOnly(t, ...)
defer ts.Stopper().Stop(ctx)

addr := ts.RPCAddr()  // prints warning, linking to this section

The recommended way to remove the warning is to make the test intent explicit by adding the missing call to .ApplicationLayer(), for example:

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:

type TestServerInterface interface {
  ...
  // ApplicationLayerInterface is implemented by TestServerInterface
  // for backward-compatibility with existing test code.
  //
  // It is CURRENTLY equivalent to .SystemLayer() however
  // this results in poor test semantics.
  //
  // New tests should spell out their intent clearly by calling
  // the .ApplicationLayer() (preferred) or .SystemLayer() methods directly.
  ApplicationLayerInterface
  ...
}

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:

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()!

In a later version, we envision to redirect the implicit ApplicationLayerInterface to the result of .ApplicationLayer() automatically, so that this entire section becomes a non-problem. Follow along here: https://github.com/cockroachdb/cockroach/pull/110001