Documentation
¶
Overview ¶
Package postgrestest provides PostgreSQL test harnesses backed by postgres.
It owns the harnesses that stand up a database for a test, prove a migration set reversible, and snapshot a schema. The connection, transaction and migration primitives they rest on live in postgres.
Index ¶
- Variables
- func NewContextTest(ctx context.Context, config postgres.Config) (context.Context, string, error)
- func RunDBTest(t *testing.T, config postgres.Config, migrations fs.FS, ...)
- func RunIsolatedTransactionalTest(t *testing.T, config postgres.Config, migrations fs.FS, ...)
- func RunMigrationRoundtripTest(t *testing.T, config postgres.Config, migrations fs.FS, opts *RoundtripOptions)
- func RunTransactionalTest(t *testing.T, config postgres.Config, callback TransactionalTestFunc)
- func SchemaSnapshot(ctx context.Context, db bun.IDB, schema string) (string, error)
- func SnapshotDelta(want, got string) []string
- type RoundtripOptions
- type TransactionalTestFunc
Constants ¶
This section is empty.
Variables ¶
var ErrUnsupportedSchemaObject = errors.New("schema holds an object class the census cannot render")
ErrUnsupportedSchemaObject reports a schema object the census cannot safely compare. Such objects fail instead of being silently omitted.
Functions ¶
func NewContextTest ¶
NewContextTest derives a context bound to a fresh, randomly named schema created through config, isolating the test from others sharing the database. It returns the schema name so the caller can drop it once done.
func RunDBTest ¶
func RunDBTest(t *testing.T, config postgres.Config, migrations fs.FS, callback TransactionalTestFunc)
RunDBTest runs callback against a fresh PostgreSQL database of its own, cloned from a migrated template with `CREATE DATABASE … TEMPLATE`. Each call is isolated, so the test and its sub-tests may run in parallel even when they reuse the same fixture keys.
The migrations run once, into a template database named after their hash. Each test then gets a fast file-level copy of that template. The test's cleanup drops the copy. The template stays for later runs until the migrations change.
config must expose Options() []pgdriver.Option, as postgrespresets.Default does. callback receives a context carrying a *bun.DB for its database, which postgres.GetContext returns.
func RunIsolatedTransactionalTest ¶
func RunIsolatedTransactionalTest( t *testing.T, config postgres.Config, migrations fs.FS, callback TransactionalTestFunc, )
RunIsolatedTransactionalTest runs callback in a throwaway schema, which admits operations a transaction cannot host concurrently, such as refreshing a materialized view.
The schema lives in the existing database, so its extensions remain available. Each call reruns the whole migration set, which makes RunTransactionalTest the cheaper default.
func RunMigrationRoundtripTest ¶
func RunMigrationRoundtripTest(t *testing.T, config postgres.Config, migrations fs.FS, opts *RoundtripOptions)
RunMigrationRoundtripTest proves that every down migration exactly reverses its up.
It snapshots each up, verifies each down against the preceding snapshot, then re-applies the full set. Fixtures run between steps. Snapshots bind each schema to its exact migration prefix.
config must expose Options() []pgdriver.Option, as postgrespresets.Default does.
func RunTransactionalTest ¶
func RunTransactionalTest(t *testing.T, config postgres.Config, callback TransactionalTestFunc)
RunTransactionalTest runs callback inside a transaction that is rolled back on cleanup. Sub-transactions resolve to that same transaction, so concurrent calls sharing the connection cannot deadlock.
func SchemaSnapshot ¶
SchemaSnapshot renders supported schema objects as canonical, sorted, one-line records. PostgreSQL renders definitions, so statement order and DDL spelling do not affect the result.
It includes database-scoped extensions and schemas, reads no row data, and returns ErrUnsupportedSchemaObject for an object class it cannot render.
func SnapshotDelta ¶
SnapshotDelta returns sorted per-object differences between want and got. Records are compared as a set.
Types ¶
type RoundtripOptions ¶
type RoundtripOptions struct {
// Fixtures holds optional `<timestamp>_<name>.sql` files, applied after the named migration.
Fixtures fs.FS
// Snapshots is the directory holding one schema snapshot per migration, each bound to the
// migration history up to it. Empty skips them. Setting GOLIB_UPDATE_SNAPSHOTS rewrites them.
Snapshots string
}
RoundtripOptions configures RunMigrationRoundtripTest. Its zero value is valid.