testpgx

README

This package was developed by Silicon Ally while working on a project for Adventure Scientists. Many thanks to Adventure Scientists for supporting our open source mission!

NOTE: this package is pre-v1.0.0 release, meaning that the API is liable to change as we add + refactor functionality. Since it's only for use in testing, that's likely fine for small projects, but contact us before integrating this into any larger/more serious projects.

testpgx

testpgx is a testing library for running tests against a real Postgres database. It provides a test with a *pgx.Conn connection to a live database running in a Docker container, though this can be converted into a more generic *sql.DB.

Usage

See the example/ directory for an example of how to integrate testpgx into a test suite.

Contributing

Contribution guidelines can be found on our website.

Documentation

Index

• type DumpOption
  • func WithCustomDisclaimer(disclaimer string) DumpOption
  • func WithHumanReadableSchema() DumpOption
• type DumpOptions
• type Env
  • func New(ctx context.Context, opts ...Option) (*Env, error)
  • func (e *Env) CreateDB(ctx context.Context) (*TestDB, error)
  • func (e *Env) DumpDatabaseSchema(ctx context.Context, dbName string, opts ...DumpOption) (string, error)
  • func (e *Env) GetMigratedDB(ctx context.Context, t testing.TB) *pgxpool.Pool
  • func (e *Env) TearDown(ctx context.Context) error
  • func (e *Env) WithMigratedDB(ctx context.Context, fn func(*pgxpool.Pool) error) error
• type Migrator
• type Option
  • func WithDockerBinaryPath(p string) Option
  • func WithMaxDBs(n int) Option
  • func WithMigrator(m Migrator) Option
  • func WithPostgresDockerImage(img string) Option
• type StepMigrator
• type TestDB

Types

type DumpOption

type DumpOption func(*DumpOptions)

func WithCustomDisclaimer

func WithCustomDisclaimer(disclaimer string) DumpOption

func WithHumanReadableSchema

func WithHumanReadableSchema() DumpOption

type DumpOptions

type DumpOptions struct {
	// contains filtered or unexported fields
}

type Env

type Env struct {
	// contains filtered or unexported fields
}

func New

func New(ctx context.Context, opts ...Option) (*Env, error)

func (*Env) CreateDB

func (e *Env) CreateDB(ctx context.Context) (*TestDB, error)

func (*Env) DumpDatabaseSchema

func (e *Env) DumpDatabaseSchema(ctx context.Context, dbName string, opts ...DumpOption) (string, error)

func (*Env) GetMigratedDB

func (e *Env) GetMigratedDB(ctx context.Context, t testing.TB) *pgxpool.Pool

func (*Env) TearDown

func (e *Env) TearDown(ctx context.Context) error

func (*Env) WithMigratedDB

func (e *Env) WithMigratedDB(ctx context.Context, fn func(*pgxpool.Pool) error) error

type Migrator

type Migrator interface {
	Migrate(*sql.DB) error
}

type Option

type Option func(*options)

Option allows configuring the test environment created by testpgx.

func WithDockerBinaryPath

func WithDockerBinaryPath(p string) Option

WithDockerBinaryPath sets the path to the local Docker binary. If blank, the default is to look in $PATH for the executable.

func WithMaxDBs

func WithMaxDBs(n int) Option

WithMaxDBs controls the number of DBs, which corresponds to the number of parallel executions. Test errors can occur if there are too many DBs created (because of memory limits). Defaults to 10.

func WithMigrator

func WithMigrator(m Migrator) Option

WithMigrator allows specifing a migration system to populate the database schema. If not specified, the database will be empty (e.g. have no tables or anything).

func WithPostgresDockerImage

func WithPostgresDockerImage(img string) Option

WithPostgresDockerImage csets the Docker image to use for running PostgreSQL. It defaults to 'postgres:14.4'

type StepMigrator

type StepMigrator interface {
	Migrator
	StepUp(*sql.DB) error
	StepDown(*sql.DB) error
}

type TestDB

type TestDB struct {
	// contains filtered or unexported fields
}