Documentation
¶
Overview ¶
Package riverdbtest contains testing infrastructure for the River project itself that creates isolated schemas suitable for use within a single case.
This package is for internal use and should not be considered stable. Changes to functions and types in this package WILL NOT be considered breaking changes for purposes of River's semantic versioning.
Index ¶
- func TestSchema[TTx any](ctx context.Context, tb testutil.TestingTB, driver riverdriver.Driver[TTx], ...) string
- func TestTx[TTx any](ctx context.Context, tb testing.TB, driver riverdriver.Driver[TTx], ...) TTx
- func TestTxPgx(ctx context.Context, tb testing.TB) pgx.Tx
- type TestSchemaOpts
- type TestTxOpts
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func TestSchema ¶
func TestSchema[TTx any](ctx context.Context, tb testutil.TestingTB, driver riverdriver.Driver[TTx], opts *TestSchemaOpts) string
TestSchema generates an isolated schema for use during a single test run. Migrations are run in the schema (this adds ~50 ms of overhead) to prepare it for River testing. AFter a test run, the schema in use is checked back into a pool for potential reuse. When a schema is reused, tables in TruncateTables are truncated to leave a clean state for the next test.
Use of a schema doesn't happen in River clients automatically. TestSchema returns the name of a schema to use. This should be set in River clients, used as a parameter for testfactory functions, and anywhere else where database operations are issued.
Despite reasonably fast migrations and efficient reuse, test schemas still have more overhead than a test transaction, so prefer the use of riversharedtest.TestTx where a full database isn't needed (TestSchema is commonly needed where tests rely on database notifications).
tb is an interface that tolerates not having a cleanup hook so constructs like testutil.PanicTB can be used. If Cleanup isn't available, schemas aren't checked back in for reuse.
Where Cleanup is available, the function also performs a post-flight check that makes sure all tables in TruncateTables are empty. This helps detect problems where test cases accidentally inject data into the default schema rather than the one returned by this function.
func TestTx ¶
func TestTx[TTx any](ctx context.Context, tb testing.TB, driver riverdriver.Driver[TTx], opts *TestTxOpts) TTx
TestTx starts a test transaction that's rolled back automatically as the test case is cleaning itself up.
The function invokes TestSchema to create a single schema where this test transaction and all future test transactions for this package test run will run.
`search_path` is set to the name of the transaction schema so that it's not necessary to specify an explicit schema for database operations. (This is somewhat of a legacy decision
The included driver determines what migrations are run to prepare the test transaction schema.
Types ¶
type TestSchemaOpts ¶
type TestSchemaOpts struct {
// Lines are migration lines to run. By default, the migration lines
// specified by the driver's GetMigrationDefaultLines function are run.
//
// Set to an empty non-nil slice like `[]string{}` to run no migrations.
Lines []string
// contains filtered or unexported fields
}
TestSchemaOpts are options for TestSchema. Most of the time these can be left as nil.
type TestTxOpts ¶
type TestTxOpts struct {
// IsTestTxHelper should be set to true for if TestTx is being called from
// within a secondary helper that's in a common testing package. This causes
// an extra stack frame to be skipped when determining the name of the test
// schema being used for test transactions. So instead of `riverdbtest` or
// `riverprodbtest` we get the real name of the package being tested (e.g.
// `river` or `riverpro`).
IsTestTxHelper bool
// contains filtered or unexported fields
}
TestTxOpts are options for TestTx. Most of the time these can be left as nil.
Source Files