testutil

package
v0.0.0-...-534e583 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 12, 2026 License: Apache-2.0 Imports: 21 Imported by: 0

Documentation

Index

Constants

View Source
const (
	// DefaultPostgresImage is the PostgreSQL image used for test databases.
	// It matches the image used by the performance suite and the kind
	// deployment so all test paths exercise the same major version.
	DefaultPostgresImage = "postgres:17.8"

	// PostgresImageEnvVar overrides the image used for the shared PostgreSQL
	// test container, for example to trial a different major version.
	PostgresImageEnvVar = "TEST_POSTGRES_IMAGE"
)
View Source
const (
	// TestDBBackendEnvVar selects the database backend used by NewTestDB.
	// Accepted values are BackendPostgres and BackendSQLite. An empty value
	// selects the default backend.
	TestDBBackendEnvVar = "TEST_DB"

	// BackendPostgres runs database tests against PostgreSQL through
	// Testcontainers. It requires a reachable container runtime (Docker or
	// Podman); run tests through scripts/testcontainers-run.sh or set
	// DOCKER_HOST to select an endpoint.
	BackendPostgres = "postgres"

	// BackendSQLite runs database tests against in-memory SQLite. It needs no
	// external dependencies but does not reproduce PostgreSQL behavior
	// (JSONB constraints, advisory locks, transaction conflicts). Select it
	// explicitly with TEST_DB=sqlite when no container runtime is available.
	BackendSQLite = "sqlite"
)

Database backends available for tests that exercise SQL/GORM behavior.

View Source
const SQLiteInMemoryPattern = "file:%s?mode=memory&cache=shared"

Use a named in-memory DB with shared cache so GORM's connection pool sees a single logical database. ":memory:" would create a separate DB per connection and break tests.

Variables

This section is empty.

Functions

func NewPostgresTestDB

func NewPostgresTestDB(t *testing.T, migrate func(*gorm.DB) error, cfg *gorm.Config) *gorm.DB

NewPostgresTestDB returns a GORM handle to an isolated, migrated PostgreSQL database for the test. See PostgresTestDSN for the isolation model and TerminateSharedPostgres for container lifetime.

The returned handle's connection pool is closed when the test finishes.

func NewSQLiteTestDB

func NewSQLiteTestDB(t *testing.T, cfg *gorm.Config) *gorm.DB

func NewTestDB

func NewTestDB(t *testing.T, cfg *gorm.Config, migrate func(*gorm.DB) error) *gorm.DB

NewTestDB returns a migrated test database on the backend selected through TestDBBackendEnvVar, defaulting to PostgreSQL.

The migrate function brings the database schema up to date. On SQLite it runs once per call, matching the per-test in-memory database. On PostgreSQL it runs once per test binary to build a template database that every test database is copied from, so pass a stable function value (a package-level function, not a fresh closure) to avoid building more templates than needed. migrate may be nil when the test does not need a schema.

PostgreSQL requires a container runtime; run tests through scripts/testcontainers-run.sh (or the make target that wraps it) so runtime detection and Podman quirks are handled, and add a TestMain calling TerminateSharedPostgres so the shared container is removed reliably.

func PostgresTestDSN

func PostgresTestDSN(t *testing.T, migrate func(*gorm.DB) error) string

PostgresTestDSN provisions an isolated PostgreSQL database for the test and returns its DSN. Use NewPostgresTestDB unless the test needs to open handles itself.

The first call in a test binary starts one PostgreSQL testcontainer and, for each distinct migrate function, builds a template database by running migrate once. Every call then copies the template into a private database, giving tests full schema isolation without paying the migration cost per test. Databases are dropped when their test finishes; the container is stopped by TerminateSharedPostgres.

Pass a stable function value (a package-level function, not a fresh closure) as migrate so its template is reused; distinct functions get distinct templates. migrate may be nil when no schema is needed, in which case databases are copied from PostgreSQL's pristine template0.

func TerminateSharedPostgres

func TerminateSharedPostgres() error

TerminateSharedPostgres stops the shared PostgreSQL testcontainer and closes its maintenance connection. It is a no-op when no PostgreSQL test database was created. Call it from TestMain after m.Run so the container is removed even when Ryuk is disabled, which scripts/testcontainers-run.sh does for Podman. Report any returned error and fail the test binary, even if m.Run succeeded. Call only after all tests and their database cleanup have finished.

func TestDBBackend

func TestDBBackend() string

TestDBBackend returns the database backend selected through TestDBBackendEnvVar, defaulting to BackendPostgres. It panics on unsupported values so backend-specific branches cannot silently treat typos as SQLite.

PostgreSQL is the default because it is what production runs and SQLite cannot reproduce PostgreSQL-specific behavior (JSONB constraints, advisory locks, transaction conflicts). Select BackendSQLite explicitly with TEST_DB=sqlite when no container runtime is available.

func UsingPostgres

func UsingPostgres() bool

UsingPostgres reports whether tests are running against the PostgreSQL backend. Use this to branch over backend-specific behavior that cannot be expressed generically (for example, setting a lock timeout). Like TestDBBackend, it panics if TestDBBackendEnvVar contains an unsupported value.

Types

This section is empty.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL