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/v2/testserver" import "testing" import "time" func TestRunServer(t *testing.T) { ts, err := testserver.NewTestServer() if err != nil { t.Fatal(err) } defer ts.Stop() db, err := sql.Open("postgres", ts.PGURL().String()) if err != nil { t.Fatal(err) } }
Index ¶
- func GetDownloadFilename(response *http.Response, nonStableDB bool, desiredVersion string) (string, error)
- func GetDownloadResponse(desiredVersion string, nonStable bool) (*http.Response, string, error)
- func NewDBForTest(t *testing.T, opts ...TestServerOpt) (*sql.DB, func())
- func NewDBForTestWithDatabase(t *testing.T, database string, opts ...TestServerOpt) (*sql.DB, func())
- type TestConfig
- type TestServer
- type TestServerOpt
- func AddHttpPortOpt(port int) TestServerOpt
- func AddListenAddrPortOpt(port int) TestServerOpt
- func CockroachBinaryPathOpt(executablePath string) TestServerOpt
- func CustomVersionOpt(version string) TestServerOpt
- func EnvVarOpt(vars []string) TestServerOpt
- func ExposeConsoleOpt(port int) TestServerOpt
- func ExternalIODirOpt(ioDir string) TestServerOpt
- func InitTimeoutOpt(timeout int) TestServerOpt
- func NonStableDbOpt() TestServerOpt
- func PollListenURLTimeoutOpt(timeout int) TestServerOpt
- func RootPasswordOpt(pw string) TestServerOpt
- func SecureOpt() TestServerOpt
- func SetStoreMemSizeOpt(memSize float64) TestServerOpt
- func StopDownloadInMiddleOpt() TestServerOpt
- func StoreOnDiskOpt() TestServerOpt
- func ThreeNodeOpt() TestServerOpt
- func UpgradeCockroachBinaryPathOpt(executablePath string) TestServerOpt
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func GetDownloadFilename ¶
func GetDownloadFilename( response *http.Response, nonStableDB bool, desiredVersion string, ) (string, error)
GetDownloadFilename returns the local filename of the downloaded CRDB binary file.
func GetDownloadResponse ¶
GetDownloadResponse return the http response of a CRDB download. It creates the url for downloading a CRDB binary for current runtime OS, makes a request to this url, and return the response. nonStable should only be used if desiredVersion is not specified. If nonStable is used, the latest cockroach binary will be used.
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.
Types ¶
type TestConfig ¶
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 first node's stdout. Stdout() string // Stdout returns the entire contents of the first node's stderr. Stderr() string // StdoutForNode returns the entire contents of the node's stdout. StdoutForNode(i int) string // StderrForNode returns the entire contents of the node's stderr. StderrForNode(i int) 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 // BaseDir returns directory StoreOnDiskOpt writes to if used. BaseDir() string // WaitForInitFinishForNode waits until a node has completed // initialization and is available to connect to and query on. WaitForInitFinishForNode(numNode int) error // StartNode runs the "cockroach start" command for the node. StartNode(i int) error // StopNode kills the node's process. StopNode(i int) error // UpgradeNode stops the node, then starts the node on the with the // binary specified at "upgradeBinaryPath". UpgradeNode(i int) error // PGURLForNode returns the PGUrl for the node. PGURLForNode(nodeNum int) *url.URL }
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.
type TestServerOpt ¶
type TestServerOpt func(args *testServerArgs)
TestServerOpt is passed to NewTestServer.
func AddHttpPortOpt ¶
func AddHttpPortOpt(port int) TestServerOpt
AddHttpPortOpt is a TestServer option that can be passed to NewTestServer to specify the http ports for the Cockroach nodes.
func AddListenAddrPortOpt ¶
func AddListenAddrPortOpt(port int) TestServerOpt
AddListenAddrPortOpt is a TestServer option that can be passed to NewTestServer to specify the ports for the Cockroach nodes. In the case of restarting nodes, it is up to the user of TestServer to make sure the port used here cannot be re-used.
func CockroachBinaryPathOpt ¶
func CockroachBinaryPathOpt(executablePath string) TestServerOpt
CockroachBinaryPathOpt is a TestServer option that can be passed to NewTestServer to specify the path of the cockroach binary. This can be used to avoid downloading cockroach if running tests in an environment with no internet connection, for instance.
func CustomVersionOpt ¶
func CustomVersionOpt(version string) TestServerOpt
CustomVersionOpt is a TestServer option that can be passed to NewTestServer to download the a specific version of CRDB.
func EnvVarOpt ¶
func EnvVarOpt(vars []string) TestServerOpt
EnvVarOpt is a list of environment variables to be passed to the start command. Each entry in the slice should be in `key=value` format.
func ExposeConsoleOpt ¶
func ExposeConsoleOpt(port int) TestServerOpt
ExposeConsoleOpt is a TestServer option that can be passed to NewTestServer to expose the console of the server on the given port. Warning: This is kept around for backwards compatibility, use AddHttpPortOpt instead.
func ExternalIODirOpt ¶
func ExternalIODirOpt(ioDir string) TestServerOpt
ExternalIODirOpt is a TestServer option that can be passed to NewTestServer to specify the external IO directory to be used for the cluster.
func InitTimeoutOpt ¶
func InitTimeoutOpt(timeout int) TestServerOpt
func NonStableDbOpt ¶
func NonStableDbOpt() TestServerOpt
NonStableDbOpt is a TestServer option that can be passed to NewTestServer to download the latest beta version of CRDB, but not necessary a stable one.
func PollListenURLTimeoutOpt ¶
func PollListenURLTimeoutOpt(timeout int) TestServerOpt
func RootPasswordOpt ¶
func RootPasswordOpt(pw string) TestServerOpt
RootPasswordOpt is a TestServer option that, when passed to NewTestServer, sets the given password for the root user (and returns a URL using it from PGURL(). This avoids having to use client certs.
func SecureOpt ¶
func SecureOpt() TestServerOpt
SecureOpt is a TestServer option that can be passed to NewTestServer to enable secure mode.
func SetStoreMemSizeOpt ¶
func SetStoreMemSizeOpt(memSize float64) TestServerOpt
SetStoreMemSizeOpt is a TestServer option that can be passed to NewTestServer to set the proportion of available memory that is allocated to the test server.
func StopDownloadInMiddleOpt ¶
func StopDownloadInMiddleOpt() TestServerOpt
StopDownloadInMiddleOpt is a TestServer option used only in testing. It is used to test the flock over downloaded CRDB binary. It should not be used in production.
func StoreOnDiskOpt ¶
func StoreOnDiskOpt() TestServerOpt
StoreOnDiskOpt is a TestServer option that can be passed to NewTestServer to enable storing database in memory.
func ThreeNodeOpt ¶
func ThreeNodeOpt() TestServerOpt
func UpgradeCockroachBinaryPathOpt ¶
func UpgradeCockroachBinaryPathOpt(executablePath string) TestServerOpt