testserver

Documentation

Overview

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/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) (*sql.DB, func())
• func NewDBForTestWithDatabase(t *testing.T, database string) (*sql.DB, func())
• type TestServer
  • func NewTestServer() (*TestServer, error)
  • func (ts *TestServer) PGURL() *url.URL
  • func (ts *TestServer) Start() error
  • func (ts *TestServer) Stderr() string
  • func (ts *TestServer) Stdout() string
  • func (ts *TestServer) Stop()
  • func (ts *TestServer) WaitForInit(db *sql.DB) error

Functions

func NewDBForTest

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

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

func NewDBForTestWithDatabase

func NewDBForTestWithDatabase(t *testing.T, database string) (*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.

Types

type TestServer

type TestServer struct {
	// contains filtered or unexported fields
}

TestServer is a helper to run a real cockroach node.

func NewTestServer

func NewTestServer() (*TestServer, error)

NewTestServer creates a new TestServer, but does not start it. 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.

func (*TestServer) PGURL

func (ts *TestServer) PGURL() *url.URL

PGURL returns the postgres connection URL to reach the started cockroach node.

It blocks until the network URL is determined and does not timeout, relying instead on test timeouts.

func (*TestServer) Start

func (ts *TestServer) Start() error

Start runs the process, returning an error on any problems, including being unable to start, but not unexpected failure. It should only be called once in the lifetime of a TestServer object.

func (*TestServer) Stderr

func (ts *TestServer) Stderr() string

Stderr returns the entire contents of the process' stderr.

func (*TestServer) Stdout

func (ts *TestServer) Stdout() string

Stdout returns the entire contents of the process' stdout.

func (*TestServer) Stop

func (ts *TestServer) Stop()

Stop kills the process if it is still running and cleans its directory. It should only be called once in the lifetime of a TestServer object. Logs fatal if the process has already failed.

func (*TestServer) WaitForInit

func (ts *TestServer) WaitForInit(db *sql.DB) error

WaitForInit retries until a connection is successfully established.