spantest

Documentation

Overview

Package spantest implements TestMain for running tests that interact with Cloud Spanner.

It starts and stops the Cloud Spanner emulator and provides a *spanner.Client connected to it. It creates emulated Spanner instances, initialized from DDL statements loaded from a SQL file.

Skips all that if `INTEGRATION_TESTS` is not set to 1.

Index

• Constants
• func SpannerTestContext(tb testing.TB, cleanupDatabase CleanupDatabase) context.Context
• func SpannerTestMain(m *testing.M, initScript string)
• type CleanupDatabase
• type EmulatedInstance
  • func NewEmulatedInstance(ctx context.Context, e *emulator.Emulator) (*EmulatedInstance, error)
• type TempDB
  • func NewTempDB(ctx context.Context, cfg TempDBConfig) (*TempDB, error)
  • func (db *TempDB) Client(ctx context.Context) (*spanner.Client, error)
  • func (db *TempDB) Drop(ctx context.Context) error
• type TempDBConfig

Constants

const IntegrationTestEnvVar = "INTEGRATION_TESTS"

IntegrationTestEnvVar is the name of the environment variable which controls whether spanner tests are executed. The value must be "1" for integration tests to run.

Functions

func SpannerTestContext

func SpannerTestContext(tb testing.TB, cleanupDatabase CleanupDatabase) context.Context

SpannerTestContext returns a context for testing code that talks to Spanner.

Skips the test if `INTEGRATION_TESTS` env var is not 1.

Tests that use Spanner MUST NOT call t.Parallel().

TODO: Each test can use its own emulated spanner instance, then they can run in parallel.

func SpannerTestMain

func SpannerTestMain(m *testing.M, initScript string)

SpannerTestMain is a test main function for packages that have tests that talk to Cloud Spanner.

If `INTEGRATION_TESTS` env var is set to 1, it launches a new instance of Cloud Spanner emulator and creates a temporary spanner database before running tests.

The database is initialized with DDL statements from the given init script, discovered in one of the ancestor directories. If given an init script path "a/b/init_db.sql", it would probe "./a/b/init_db.sql", then "../a/b/init_db.sql", then "../../a/b/init_db.sql" and so on.

If `INTEGRATION_TESTS` env var is not set to 1, doesn't do anything special and runs tests normally. All tests that need Cloud Spanner (i.e. tests that call SpannerTestContext) will be skipped.

This function never returns. Instead it calls os.Exit with the value returned by m.Run().

Types

type CleanupDatabase

type CleanupDatabase func(ctx context.Context, client *spanner.Client) error

CleanupDatabase deletes all data from all tables.

TODO: Can just create a new instance per test: less code, more reliable and likely faster in the emulator anyway.

type EmulatedInstance

type EmulatedInstance struct {
	// Name is a full instance name "projects/locally-emulated/instances/...".
	Name string
	// Emulator is the emulator that holds this instance.
	Emulator *emulator.Emulator
}

EmulatedInstance is a Cloud Spanner instance inside the emulator.

func NewEmulatedInstance

func NewEmulatedInstance(ctx context.Context, e *emulator.Emulator) (*EmulatedInstance, error)

NewEmulatedInstance creates a Cloud Spanner instance inside the emulator.

It will have some randomly generated name.

type TempDB

type TempDB struct {
	// Name is the full database name to pass to the spanner client.
	Name string
	// contains filtered or unexported fields
}

TempDB is a temporary Spanner database.

func NewTempDB

func NewTempDB(ctx context.Context, cfg TempDBConfig) (*TempDB, error)

NewTempDB creates a temporary database with a random name.

Creates it either in a Cloud Spanner emulator (if cfg.EmulatedInstance is set) or in **a real Cloud Spanner instance** (if cfg.CloudInstance is set).

If this is a Cloud Spanner database, the caller is responsible for calling Drop on the returned TempDB to delete it after usage. Emulated databases are implicitly dropped when the emulator exits.

func (*TempDB) Client

func (db *TempDB) Client(ctx context.Context) (*spanner.Client, error)

Client returns a new spanner client connected to the database.

func (*TempDB) Drop

func (db *TempDB) Drop(ctx context.Context) error

Drop deletes the database.

type TempDBConfig

type TempDBConfig struct {
	// EmulatedInstance, if set, indicates to use the given emulated instance to
	// create the DB in.
	//
	// Either EmulatedInstance or CloudInstance must be set.
	EmulatedInstance *EmulatedInstance

	// CloudInstance, if set, indicates to use **real** Cloud Spanner instance.
	//
	// Format: projects/{project}/instances/{instance}.
	//
	// Either EmulatedInstance or CloudInstance must be set.
	CloudInstance string

	// InitScriptPath is a path to a DDL script to initialize the database.
	//
	// In lieu of a proper DDL parser, it is parsed using regexes.
	// Therefore the script MUST:
	//   - Use `#“ and/or `--“ for comments. No block comments.
	//   - Separate DDL statements with `;\n`.
	//
	// If empty, the database is created with no tables.
	InitScriptPath string
}

TempDBConfig specifies how to create a temporary database.