Documentation
¶
Overview ¶
Package containers provides connection helpers for integration testing against infrastructure that is already running.
Despite the package name, it does NOT provision Docker containers. It assumes the test infrastructure (PostgreSQL) has already been started out of band — typically via the repository's docker-compose.test.yml (see `make infra-up`) or by an equivalent service in CI — and provides convenience helpers to connect to it, create/drop isolated test schemas, and wire up an integration test harness. When the expected instance is not reachable, StartPostgres skips the calling test rather than failing it, so unit-only environments stay green.
There is intentionally no StartKafka (or other broker) helper here: Kafka integration tests connect directly using the TEST_KAFKA_BROKERS environment variable and skip themselves when it is unset. If you need real container provisioning (lifecycle managed from within the test), add testcontainers-go as a dependency; this package deliberately avoids that dependency to keep the default build lightweight.
Index ¶
- Variables
- type FullStackTest
- type IntegrationTest
- func (it *IntegrationTest) ConnectionString() string
- func (it *IntegrationTest) Container() *PostgresContainer
- func (it *IntegrationTest) Context() context.Context
- func (it *IntegrationTest) DB() *sql.DB
- func (it *IntegrationTest) Exec(query string, args ...interface{})
- func (it *IntegrationTest) Query(query string, args ...interface{}) *sql.Rows
- func (it *IntegrationTest) Schema() string
- type IntegrationTestOption
- type PostgresContainer
- func (c *PostgresContainer) ConnectionString() string
- func (c *PostgresContainer) CreateSchema(ctx context.Context, db *sql.DB, prefix string) (string, error)
- func (c *PostgresContainer) DB(ctx context.Context) (*sql.DB, error)
- func (c *PostgresContainer) DropSchema(ctx context.Context, db *sql.DB, schema string) error
- func (c *PostgresContainer) MustDB(ctx context.Context) *sql.DB
- type PostgresOption
Constants ¶
This section is empty.
Variables ¶
var ( // ErrInvalidSchemaPrefix indicates the schema prefix contains invalid characters. ErrInvalidSchemaPrefix = errors.New("containers: schema prefix must contain only alphanumeric characters and underscores") // ErrInvalidPort indicates the port is not valid. ErrInvalidPort = errors.New("containers: port must be a valid number between 1 and 65535") // ErrEmptyPassword indicates the password is empty. ErrEmptyPassword = errors.New("containers: password cannot be empty") )
Validation errors.
Functions ¶
This section is empty.
Types ¶
type FullStackTest ¶
type FullStackTest struct {
*IntegrationTest
}
FullStackTest provides complete end-to-end test infrastructure.
func NewFullStackTest ¶
func NewFullStackTest(t *testing.T) *FullStackTest
NewFullStackTest creates a new full stack test environment.
func (*FullStackTest) SetupMinkSchema ¶
func (fst *FullStackTest) SetupMinkSchema()
SetupMinkSchema creates the mink event store schema.
type IntegrationTest ¶
type IntegrationTest struct {
// contains filtered or unexported fields
}
IntegrationTest provides a complete integration test environment.
func NewIntegrationTest ¶
func NewIntegrationTest(t *testing.T, opts ...IntegrationTestOption) *IntegrationTest
NewIntegrationTest creates a new integration test environment.
func (*IntegrationTest) ConnectionString ¶
func (it *IntegrationTest) ConnectionString() string
ConnectionString returns the connection string with schema.
func (*IntegrationTest) Container ¶
func (it *IntegrationTest) Container() *PostgresContainer
Container returns the PostgreSQL container.
func (*IntegrationTest) Context ¶
func (it *IntegrationTest) Context() context.Context
Context returns the test context.
func (*IntegrationTest) DB ¶
func (it *IntegrationTest) DB() *sql.DB
DB returns the database connection.
func (*IntegrationTest) Exec ¶
func (it *IntegrationTest) Exec(query string, args ...interface{})
Exec executes a SQL statement.
func (*IntegrationTest) Query ¶
func (it *IntegrationTest) Query(query string, args ...interface{}) *sql.Rows
Query executes a SQL query.
func (*IntegrationTest) Schema ¶
func (it *IntegrationTest) Schema() string
Schema returns the test schema name.
type IntegrationTestOption ¶
type IntegrationTestOption func(*integrationTestConfig)
IntegrationTestOption configures an integration test.
func WithSchemaPrefix ¶
func WithSchemaPrefix(prefix string) IntegrationTestOption
WithSchemaPrefix sets the schema prefix.
func WithTimeout ¶
func WithTimeout(timeout time.Duration) IntegrationTestOption
WithTimeout sets the test timeout.
type PostgresContainer ¶
type PostgresContainer struct {
Host string
Port string
Database string
User string
Password string
// contains filtered or unexported fields
}
PostgresContainer represents a PostgreSQL test container.
func StartPostgres ¶
func StartPostgres(t *testing.T, opts ...PostgresOption) *PostgresContainer
StartPostgres connects to an already-running PostgreSQL instance and returns a handle for use in integration tests. It does NOT provision a container: the instance is expected to be running already (for example via docker-compose.test.yml / `make infra-up`, or a CI service). Connection settings default to those in docker-compose.test.yml and can be overridden with PostgresOption values or the documented environment variables.
If the instance is not reachable within the readiness timeout, the calling test is skipped (t.Skip) rather than failed, so the suite still passes in environments without the infrastructure.
There is no StartKafka counterpart: Kafka integration tests connect directly via TEST_KAFKA_BROKERS and skip when it is unset. To provision real containers from within tests, add testcontainers-go; this package avoids that dependency on purpose.
func (*PostgresContainer) ConnectionString ¶
func (c *PostgresContainer) ConnectionString() string
ConnectionString returns the PostgreSQL connection string.
func (*PostgresContainer) CreateSchema ¶
func (c *PostgresContainer) CreateSchema(ctx context.Context, db *sql.DB, prefix string) (string, error)
CreateSchema creates a unique test schema.
func (*PostgresContainer) DropSchema ¶
DropSchema drops a test schema.
type PostgresOption ¶
type PostgresOption func(*postgresConfig)
PostgresOption configures a PostgreSQL container.
func WithPostgresDatabase ¶
func WithPostgresDatabase(database string) PostgresOption
WithPostgresDatabase sets the database name.
func WithPostgresImage ¶
func WithPostgresImage(image string) PostgresOption
WithPostgresImage sets the PostgreSQL Docker image.
func WithPostgresPassword ¶
func WithPostgresPassword(password string) PostgresOption
WithPostgresPassword sets the database password.
func WithPostgresPort ¶
func WithPostgresPort(port string) PostgresOption
WithPostgresPort sets the host port.
func WithPostgresUser ¶
func WithPostgresUser(user string) PostgresOption
WithPostgresUser sets the database user.
Source Files