testsuite

package
v0.4.8 Latest Latest
Warning

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

 Go to latest Published: Feb 19, 2026 License: MIT Imports: 22 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	TestDataDirPath = "testdata"

	// Container configuration constants
	DefaultTimeout = 20 * time.Second

	// Default config constants
	DefaultPostgresImage   = "postgres:14.5"
	DefaultUsername        = "postgres"
	DefaultPassword        = "my-secret"
	DefaultHost            = "localhost"
	DefaultPort            = 5432
	DefaultDBName          = "wpgx_test_db"
	DefaultMaxConns        = int32(20)
	DefaultMinConns        = int32(0)
	DefaultMinIdleConns    = int32(0)
	DefaultMaxConnLifetime = 6 * time.Hour
	DefaultMaxConnIdleTime = 1 * time.Minute
	DefaultAppName         = "WPgxTestSuite"

	// Environment variable names
	EnvUseTestContainers = "USE_TEST_CONTAINERS"

	// Golden file extensions
	GoldenFileSuffix    = ".golden"
	VarGoldenFileSuffix = ".var.golden"

	// Connection string format
	PostgresConnStringFormat = "postgres://%s:%s@%s:%d/postgres"
)

Variables

This section is empty.

Functions

This section is empty.

Types

type Dumper 

type Dumper interface {
	Dump() ([]byte, error)
}

type Isolation added in v0.4.3 

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

Isolation is a wrapper around a PostgreSQL database that is isolated from the main suite database.

func (*Isolation) Close added in v0.4.3 

func (t *Isolation) Close()

Close drops the isolated database

func (*Isolation) GetConfig added in v0.4.3 

func (t *Isolation) GetConfig() wpgx.Config

GetConfig returns the config for the isolated database

func (*Isolation) NewPool added in v0.4.3 

func (t *Isolation) NewPool(ctx context.Context) (*wpgx.Pool, error)

NewPool creates a new pool for the isolated database

type Loader 

type Loader interface {
	Load(data []byte) error
}

type WPgxTestSuite added in v0.1.1 

type WPgxTestSuite struct {
	suite.Suite
	Tables []string

	Pool *wpgx.Pool
	// contains filtered or unexported fields
}

func NewWPgxTestSuiteFromConfig added in v0.1.1 

func NewWPgxTestSuiteFromConfig(config *wpgx.Config, tables []string, useContainer bool) *WPgxTestSuite

NewWPgxTestSuiteFromConfig connect to PostgreSQL Server according to @p config, tables are table creation SQL statements. config.DBName will be created, so does tables, on SetupTest.

NOTE: if you use the testcontainers mode, the container is started in SetupSuite and terminated in TearDownSuite. You MUST use the GetConfig() method to get the updated config with container connection details after SetupSuite.

When using direct connection mode (no testcontainers), different test suites may share the same pg and database, which means tests must be run with `go test -count=1 -p 1` to avoid conflicts. To avoid this, you can manage PostgreSQL containers at a higher level (e.g. in CI or your own test setup) and pass each suite its own connection config to run in parallel without conflicts. For built-in container support without external setup, see NewWPgxTestSuiteTcDefault.

func NewWPgxTestSuiteFromEnv added in v0.1.1 

func NewWPgxTestSuiteFromEnv(tables []string) *WPgxTestSuite

NewWPgxTestSuiteFromEnv initialize WPgxTestSuite from environment variables using default wpgx prefix. Use environment variable USE_TEST_CONTAINERS=true to enable testcontainers mode. Otherwise, it will use direct connection mode (requires a running PostgreSQL instance).

NOTE: if you use the testcontainers mode, the container is started in SetupSuite and terminated in TearDownSuite. You MUST use the GetConfig() method to get the updated config with container connection details after SetupSuite.

When using direct connection mode (no testcontainers), different packages may share the same pg and database, which means tests must be run with `go test -count=1 -p 1` to avoid conflicts. To avoid this, you can manage PostgreSQL containers at a higher level (e.g. in CI or your own test setup) and pass each suite its own connection config to run in parallel without conflicts. For built-in container support without external setup, see NewWPgxTestSuiteTcDefault.

func NewWPgxTestSuiteTcDefault added in v0.4.3 

func NewWPgxTestSuiteTcDefault(tables []string) *WPgxTestSuite

NewWPgxTestSuiteTcDefault creates a new WPgxTestSuite with default testcontainers configuration. This is a convenient way to get a PostgreSQL test suite running without any external setup. Each test suite gets its own dedicated container with sensible defaults.

If you prefer managing PostgreSQL test containers at a higher level (e.g. shared across suites or managed by CI), use NewWPgxTestSuiteFromEnv or NewWPgxTestSuiteFromConfig instead.

For even more parallelism within a test suite, use the suite's NewIsolation() method to create isolated databases for individual test cases.

To connect to this testsuite from other code, you should use GetConfig() to get the config with container connection details after SetupSuite (typically in SetupTest or BeforeTest).

func (*WPgxTestSuite) DumpState added in v0.1.1 

func (suite *WPgxTestSuite) DumpState(filename string, dumper Dumper)

DumpState dump state to the file. For example DumpState(ctx, "sample1.golden.json") will dump (insert) bytes from dumper.dump() to "testdata/${suitename}/${filename}".

func (*WPgxTestSuite) GetConfig added in v0.4.3 

func (suite *WPgxTestSuite) GetConfig() wpgx.Config

Config returns the updated config. You MUST use this new config to create pools if you use the testcontainers mode. The host and port are updated to the container's host and port.

func (*WPgxTestSuite) GetPool added in v0.1.2 

func (suite *WPgxTestSuite) GetPool() *wpgx.Pool

GetPool returns the *wpgx.Pool.

func (*WPgxTestSuite) GetRawPool added in v0.1.1 

func (suite *WPgxTestSuite) GetRawPool() *pgxpool.Pool

GetRawPool returns a raw *pgx.Pool.

func (*WPgxTestSuite) Golden added in v0.1.1 

func (suite *WPgxTestSuite) Golden(tableName string, dumper Dumper)

Golden compares db state dumped by @p dumper with the golden file {TestName}.{tableName}.golden. For the first time, you can run `go test -update` to automatically generate the golden file.

func (*WPgxTestSuite) GoldenVarJSON added in v0.1.8 

func (suite *WPgxTestSuite) GoldenVarJSON(varName string, v any)

GoldenVarJSON compares the JSON string representation of @p v with @p varName.golden file with the test case name as prefix: {TestName}.{varName}.var.golden. For the first time, you can run `go test -update` to automatically generate the golden file.

func (*WPgxTestSuite) LoadState added in v0.1.1 

func (suite *WPgxTestSuite) LoadState(filename string, loader Loader)

LoadState load state from the file to DB. For example LoadState(ctx, "sample1.input.json") will load (insert) from "testdata/sample1.input.json" to table

func (*WPgxTestSuite) LoadStateTmpl added in v0.1.7 

func (suite *WPgxTestSuite) LoadStateTmpl(filename string, loader Loader, templateData any)

LoadStateTmpl load state go-template from the file to DB. For example, data := struct{ID int64}{ID:1} LoadState(ctx, "sample1.input.json.tmpl", data) will load (insert) from "testdata/sample1.input.json.tmpl", execute it with @p data and use loader to populate the table.

func (*WPgxTestSuite) NewIsolation added in v0.4.3 

func (suite *WPgxTestSuite) NewIsolation(ctx context.Context) (*Isolation, error)

NewIsolation creates a new isolated database within the test suite's PostgreSQL instance. This allows individual test cases to run in complete isolation with their own database, enabling maximum parallelism within a test suite.

Each isolated database:

  • Has a unique randomly-generated name (e.g., "wpgx_test_db_iso_a1b2c3d4e5f6g7h8")
  • Contains all tables defined in the suite's Tables field
  • Is automatically cleaned up when Close() is called
  • Is completely independent from other isolated databases and the main suite database

Usage example: 

func (suite *MyTestSuite) TestSomething() {
    ctx := context.Background()
    isolation, err := suite.NewIsolation(ctx)
    suite.Require().NoError(err)
    defer isolation.Close()

    pool, err := isolation.NewPool(ctx)
    suite.Require().NoError(err)
    defer pool.Close()

    // Use pool for isolated testing...
}

This is particularly useful when:

  • Running tests in parallel within a suite (t.Parallel())
  • Tests need complete data isolation from each other
  • You want to avoid SetupTest/TearDownTest overhead for individual test cases

func (*WPgxTestSuite) SetupSuite added in v0.4.3 

func (suite *WPgxTestSuite) SetupSuite()

SetupSuite runs once before all tests in the suite. For container mode, it starts the PostgreSQL container.

func (*WPgxTestSuite) SetupTest added in v0.1.1 

func (suite *WPgxTestSuite) SetupTest()

SetupTest sets up the database to a clean state: tables have been created according to the schema, empty.

func (*WPgxTestSuite) TearDownSuite added in v0.4.3 

func (suite *WPgxTestSuite) TearDownSuite()

TearDownSuite runs once after all tests in the suite. For container mode, it terminates the PostgreSQL container.

func (*WPgxTestSuite) TearDownTest added in v0.1.1 

func (suite *WPgxTestSuite) TearDownTest()

TearDownTest closes the pool and sets it to nil.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.