test

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)
}

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)

Parameters:

• ctx - Context with timeout
• name - Container name prefix (timestamp is appended)
• verbose - Enable verbose SQL logging
• traceFn - Optional trace function for SQL queries

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)
				}

		     // 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)
• type Conn
  • func (c *Conn) Begin(t *testing.T) *Conn
  • func (c *Conn) Close()
• type Container
  • func NewContainer(ctx context.Context, name, image string, opt ...Opt) (*Container, error)
  • func NewPgxContainer(ctx context.Context, name string, verbose bool, tracer pg.TraceFn) (*Container, pg.PoolConn, error)
  • func (c *Container) Close(ctx context.Context) error
  • func (c *Container) GetEnv(name string) (string, error)
  • func (c *Container) GetPort(name string) (string, error)
  • func (c *Container) String() string
• type ManagerConn
  • func NewManager(t *testing.T) *ManagerConn
  • func (m *ManagerConn) Close()
• type Opt
  • func OptCommand(cmd []string) Opt
  • func OptEnv(name, value string) Opt
  • func OptPorts(ports ...string) Opt
  • func OptPostgres(user, password, database string) Opt
  • func OptPostgresSetting(key, value string) Opt

Functions

func Main

func Main(m *testing.M, conn *Conn)

Types

type Conn

type Conn struct {
	pg.PoolConn
	// contains filtered or unexported fields
}

Conn is a wrapper around pg.PoolConn which provides a test connection

func (*Conn) Begin

func (c *Conn) Begin(t *testing.T) *Conn

Begin a test

func (*Conn) Close

func (c *Conn) Close()

Close ends the test.

type Container

type Container struct {
	testcontainers.Container `json:"-"`
	Env                      map[string]string `json:"env"`
	MappedPorts              map[string]string `json:"mapped_ports"`
}

func NewContainer

func NewContainer(ctx context.Context, name, image string, opt ...Opt) (*Container, error)

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) (*Container, pg.PoolConn, error)

NewPgxContainer creates a new PostgreSQL container and connection pool.

func (*Container) Close

func (c *Container) Close(ctx context.Context) error

func (*Container) GetEnv

func (c *Container) GetEnv(name string) (string, error)

func (*Container) GetPort

func (c *Container) GetPort(name string) (string, error)

func (*Container) String

func (c *Container) String() string

type ManagerConn

type ManagerConn struct {
	*manager.Manager
	// contains filtered or unexported fields
}

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

func OptCommand

func OptCommand(cmd []string) Opt

func OptEnv

func OptEnv(name, value string) Opt

func OptPorts

func OptPorts(ports ...string) Opt

func OptPostgres

func OptPostgres(user, password, database string) Opt

func OptPostgresSetting

func OptPostgresSetting(key, value string) Opt

OptPostgresSetting adds a PostgreSQL configuration setting via -c flag