README
¶
Testing Support
The test package provides utilities for integration testing with PostgreSQL using testcontainers-go. It automatically starts a PostgreSQL container, creates a connection pool, and cleans up after tests complete.
Usage
TestMain Pattern
For test suites that share a single container across all tests in a package:
package mypackage_test
import (
"testing"
pg "github.com/mutablelogic/go-pg"
pgtest "github.com/mutablelogic/go-pg/pkg/test"
)
var conn pgtest.Conn
func TestMain(m *testing.M) {
pgtest.Main(m, &conn, nil)
}
func TestSomething(t *testing.T) {
c := conn.Begin(t)
defer c.Close()
// Use c.PoolConn for database operations
err := c.Exec(ctx, "CREATE TABLE test (id SERIAL PRIMARY KEY)")
// ...
}
Per-Test Container
For isolated tests that need their own container:
func TestWithManager(t *testing.T) {
mgr := pgtest.NewManager(t)
defer mgr.Close()
// Use mgr.Manager for PostgreSQL management operations
roles, err := mgr.ListRoles(ctx, schema.RoleListRequest{})
// ...
}
Container Options
When creating containers directly, you can customize the configuration:
container, err := pgtest.NewContainer(ctx, "mytest", "postgres:16",
pgtest.WithEnv("POSTGRES_PASSWORD", "secret"),
pgtest.WithEnv("POSTGRES_DB", "testdb"),
pgtest.WithPort("5432/tcp"),
pgtest.WithWaitLog("database system is ready to accept connections"),
)
Available Options
| Option | Description |
|---|---|
WithEnv(key, value) |
Set environment variable |
WithPort(port) |
Expose a port (e.g., "5432/tcp") |
WithWaitLog(message) |
Wait for log message before considering container ready |
WithWaitPort(port) |
Wait for port to be available |
PostgreSQL Container
The NewPgxContainer function provides a preconfigured PostgreSQL container:
container, pool, err := pgtest.NewPgxContainer(ctx, "mytest", verbose, traceFn)
if err != nil {
t.Fatal(err)
}
defer pool.Close()
defer container.Close(ctx)
With optional schema search path:
container, pool, err := pgtest.NewPgxContainer(ctx, "mytest", verbose, traceFn, "myschema", "public")
if err != nil {
t.Fatal(err)
}
defer pool.Close()
defer container.Close(ctx)
Parameters:
ctx- Context with timeoutname- Container name prefix (timestamp is appended)verbose- Enable verbose SQL loggingtraceFn- Optional trace function for SQL queriessearchPath- Optional variadic parameter to set schema search path
Verbose Mode
When running tests with -v, SQL queries are logged:
go test -v ./...
The trace function receives all executed SQL with arguments and any errors.
Documentation
¶
Overview ¶
Package test provides utilities for integration testing with PostgreSQL using testcontainers.
It automatically starts a PostgreSQL container, creates a connection pool, and cleans up after tests complete.
For example, in order to test postgres integration tests, use the following boilerplate for your tests:
// Global variable which will hold the connection
var conn test.Conn
// Start up a container and return the connection
func TestMain(m *testing.M) {
test.Main(m, &conn, nil)
}
// Run a test which pings the database
func Test_Pool_001(t *testing.T) {
assert := assert.New(t)
conn := conn.Begin(t)
defer conn.Close()
// Ping the database
assert.NoError(conn.Ping(context.Background()))
}
Index ¶
- func Main(m *testing.M, conn *Conn, setup func(*Conn) (func(), error))
- type Conn
- type Container
- type ManagerConn
- type Opt
- func OptCommand(cmd []string) Opt
- func OptEntrypoint(entrypoint ...string) Opt
- func OptEnv(name, value string) Opt
- func OptFile(file testcontainers.ContainerFile) Opt
- func OptFiles(files ...testcontainers.ContainerFile) Opt
- func OptPorts(ports ...string) Opt
- func OptPostgres(user, password, database string) Opt
- func OptPostgresSetting(key, value string) Opt
- func OptWait(strategy wait.Strategy) Opt
- func OptWaitLog(log string) Opt
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Main ¶
Main is the entry point for running tests with a test container. It sets up a test database container and runs the tests in the provided testing.M. The provided setup function can be used to perform any additional setup before running the tests, such as initializing the database schema. The returned cleanup function from setup will be called after the tests are complete to clean up any resources.
Types ¶
type Container ¶
type Container struct {
testcontainers.Container `json:"-"`
Env map[string]string `json:"env"`
MappedPorts map[string]string `json:"mapped_ports"`
}
func NewContainer ¶
NewContainer creates a new container with the given name and image.
func NewPgxContainer ¶
func NewPgxContainer(ctx context.Context, name string, verbose bool, tracer pg.TraceFn, searchPath ...string) (*Container, pg.PoolConn, error)
NewPgxContainer creates a new PostgreSQL container and connection pool. Optional searchPath parameter sets the schema search path for the connection.
type ManagerConn ¶
ManagerConn wraps a Manager with its underlying connection for testing
func NewManager ¶
func NewManager(t *testing.T) *ManagerConn
NewManager creates a new Manager with a test container for integration testing. The returned ManagerConn must be closed after use.
func (*ManagerConn) Close ¶
func (m *ManagerConn) Close()
Close closes the manager connection and container
type Opt ¶
type Opt func(*opts) error
Opt mutates a container request before it is started.
func OptEntrypoint ¶ added in v1.1.9
OptEntrypoint sets the container entrypoint.
func OptFile ¶ added in v1.1.9
func OptFile(file testcontainers.ContainerFile) Opt
OptFile copies a single file into the container before startup.
func OptFiles ¶ added in v1.1.9
func OptFiles(files ...testcontainers.ContainerFile) Opt
OptFiles copies multiple files into the container before startup.
func OptPostgres ¶
OptPostgres configures a PostgreSQL container and adds SQL readiness checks.
func OptPostgresSetting ¶
OptPostgresSetting adds a PostgreSQL configuration setting via -c flag
func OptWaitLog ¶ added in v1.1.9
OptWaitLog waits for a specific log line before considering the container ready.
Source Files