Documentation
¶
Overview ¶
Package testutil is the integration-test harness: a real PostgreSQL in a container plus per-test throwaway schemas. Integration tests are the workhorse of this repo — core logic is validated against a real database, not mocks.
Index ¶
- Constants
- func NewDatabase(t *testing.T, serverURL string) string
- func NewPublicTable(t *testing.T, pool *pgxpool.Pool, columns string) string
- func NewRole(t *testing.T, pool *pgxpool.Pool, options string) string
- func NewSchema(t *testing.T, pool *pgxpool.Pool) string
- func PGVersion() string
- func StartPostgres(t *testing.T) string
- type TLSPostgres
Constants ¶
const DefaultPGVersion = "16"
DefaultPGVersion is the major used when PG_VERSION is unset. CI overrides it across the full supported matrix (14 → 18).
Variables ¶
This section is empty.
Functions ¶
func NewDatabase ¶
NewDatabase creates a unique throwaway database on the server at serverURL, sets it up for cleanup, and returns a URL that connects to it. Throwaway schemas do not isolate pg_stat_activity, so a test that must observe an exact session set (e.g. none) on a shared server gets a database of its own. serverURL must be in URL form (postgres://...), which StartPostgres always returns.
func NewPublicTable ¶
NewPublicTable creates a uniquely named throwaway table in the public schema — for tests that exercise unqualified-statement resolution, where a dedicated schema would defeat the point — and returns its name. The unique name keeps a shared PG_DSN database safe; cleanup drops the table.
func NewRole ¶
NewRole creates a throwaway cluster-level role with the given options and registers its drop. Roles are cluster-scoped, so names are unique per process the same way throwaway schemas are.
func NewSchema ¶
NewSchema creates a unique throwaway schema on pool, sets it up for cleanup, and returns its name. Tests qualify their objects with it so parallel tests on one container never collide.
func StartPostgres ¶
StartPostgres returns a PostgreSQL connection URL for the test.
By default it starts a disposable container (terminated when the test ends). When PG_DSN is set, that external server is used instead and no container is started — the compose/ workflow and CI variants that run a long-lived server use this. Set SKIP_INTEGRATION=1 to skip tests that need a database entirely.
Types ¶
type TLSPostgres ¶
type TLSPostgres struct {
// URL is the connection URL without an sslmode parameter, so the
// caller's TLS configuration decides the handshake.
URL string
// CACertPath is the PEM CA certificate that signed the server
// certificate — the trust anchor for verify-full connections.
CACertPath string
// UntrustedCACertPath is a valid CA certificate that did NOT sign the
// server certificate, for negative verification tests.
UntrustedCACertPath string
}
TLSPostgres describes a TLS-only PostgreSQL started by StartPostgresTLS.
func StartPostgresTLS ¶
func StartPostgresTLS(t *testing.T) TLSPostgres
StartPostgresTLS starts a disposable PostgreSQL container that accepts only TLS connections, using a CA generated for this test. Unlike StartPostgres it never uses PG_DSN — the whole point is controlling the server's TLS posture. Set SKIP_INTEGRATION=1 to skip.
Source Files