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 KafkaContainer
- 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 KafkaContainer ¶ added in v1.1.6
type KafkaContainer struct {
// Brokers is the raw TEST_KAFKA_BROKERS value (may be a comma-separated list).
Brokers string
}
KafkaContainer is a handle to an already-running Kafka broker for integration tests. Like PostgresContainer it does not provision anything — the broker is expected to be running out of band (docker-compose.test.yml / a CI service), addressed by the TEST_KAFKA_BROKERS environment variable.
func StartKafka ¶ added in v1.1.6
func StartKafka(t *testing.T) *KafkaContainer
StartKafka connects to an already-running Kafka broker addressed by TEST_KAFKA_BROKERS and returns a handle for integration tests. It mirrors StartPostgres: it does NOT provision a container, and it SKIPS the calling test (never fails it) when the test runs under -short, TEST_KAFKA_BROKERS is unset, or the broker is unreachable — so unit-only environments stay green and the default build needs no broker.
func (*KafkaContainer) BrokerList ¶ added in v1.1.6
func (k *KafkaContainer) BrokerList() []string
BrokerList returns the configured brokers as a slice.
func (*KafkaContainer) CreateTopic ¶ added in v1.1.6
func (k *KafkaContainer) CreateTopic(t *testing.T, topic string)
CreateTopic creates a single-partition topic and waits until it is visible, then registers a cleanup that deletes it. Use a per-test unique topic name to avoid cross-test interference.
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.
StartKafka (kafka.go) is the analogous helper for Kafka: it connects via TEST_KAFKA_BROKERS and skips when it is unset/unreachable. Neither helper provisions real containers from within tests; to do that add testcontainers-go, a dependency this package avoids 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