package testserver

import "github.com/cockroachdb/cockroach-go/v2/testserver"

Package testserver provides helpers to run a cockroach binary within tests. It automatically downloads the latest cockroach binary for your platform (Linux-amd64 and Darwin-amd64 only for now), or attempts to run "cockroach" from your PATH.

To use, run as follows:

import "github.com/cockroachdb/cockroach-go/v2/testserver"
import "testing"
import "time"

func TestRunServer(t *testing.T) {
   ts, err := testserver.NewTestServer()
   if err != nil {
     t.Fatal(err)
   }
   if err := ts.Start(); err != nil {
     t.Fatal(err)
   }
   defer ts.Stop()

   url := ts.PGURL()
   if url == nil {
     t.Fatalf("url not found")
   }
   t.Logf("URL: %s", url.String())

   db, err := sql.Open("postgres", url.String())
   if err != nil {
     t.Fatal(err)
   }
 }

Index ¶

• func NewDBForTest(t *testing.T, opts ...testServerOpt) (*sql.DB, func())
• func NewDBForTestWithDatabase( t *testing.T, database string, opts ...testServerOpt, ) (*sql.DB, func())
• func SecureOpt() testServerOpt
• type TestServer
• func NewTestServer(opts ...testServerOpt) (TestServer, error)

Functions ¶

func NewDBForTest ¶

func NewDBForTest(t *testing.T, opts ...testServerOpt) (*sql.DB, func())

NewDBForTest creates a new CockroachDB TestServer instance and opens a SQL database connection to it. Returns a sql *DB instance and a shutdown function. The caller is responsible for executing the returned shutdown function on exit.

func NewDBForTestWithDatabase ¶

func NewDBForTestWithDatabase(
	t *testing.T, database string, opts ...testServerOpt,
) (*sql.DB, func())

NewDBForTestWithDatabase creates a new CockroachDB TestServer instance and opens a SQL database connection to it. If database is specified, the returned connection will explicitly connect to it. Returns a sql *DB instance a shutdown function. The caller is responsible for executing the returned shutdown function on exit.

func SecureOpt ¶

func SecureOpt() testServerOpt

SecureOpt is a TestServer option that can be passed to NewTestServer to enable secure mode.

Types ¶

type TestServer ¶

type TestServer interface {
	// Start starts the server.
	Start() error
	// Stop stops the server and cleans up any associated resources.
	Stop()

	// Stdout returns the entire contents of the process' stdout.
	Stdout() string
	// Stdout returns the entire contents of the process' stderr.
	Stderr() string
	// PGURL returns the postgres connection URL to this server.
	PGURL() *url.URL
	// WaitForInit retries until a SQL connection is successfully established to
	// this server.
	WaitForInit() error
}

TestServer is a helper to run a real cockroach node.

func NewTestServer ¶

func NewTestServer(opts ...testServerOpt) (TestServer, error)

NewTestServer creates a new TestServer and starts it. It also waits until the server is ready to accept clients, so it safe to connect to the server returned by this function right away. The cockroach binary for your OS and ARCH is downloaded automatically. If the download fails, we attempt just call "cockroach", hoping it is found in your path.

Source Files ¶

binaries.go tenant.go testserver.go