This is an addon to be used with Testcontainers package and with GoDog
go get github.com/jfelipearaujo/testcontainers@latestTo use this addon, you need to import the packages in your project:
import "github.com/jfelipearaujo/testcontainers/pkg/container"
import "github.com/jfelipearaujo/testcontainers/pkg/network"
import "github.com/jfelipearaujo/testcontainers/pkg/state"
import "github.com/jfelipearaujo/testcontainers/pkg/testsuite"| Example | Description |
|---|---|
| Example 01 | Simple BDD test. |
| Example 02 | Using a Postgres container. |
| Example 03 | Using aLocalStack container. |
| Example 04 | Using a MongoDB container. |
| Example 05 | Custom API running on a container via Dockerfile. |
| Example 06 | Two containers interacting with each other using a Network. |
import "github.com/jfelipearaujo/testcontainers/pkg/container"- func DestroyGroup(ctx context.Context, group GroupContainer) (context.Context, error)
- func GetMappedPort(ctx context.Context, container testcontainers.Container, exposedPort nat.Port) (nat.Port, error)
- func NewGroup() map[string]GroupContainer
- type Container
- type ContainerOption
- func WithDockerfile(fromDockerFile testcontainers.FromDockerfile) ContainerOption
- func WithEnvVars(envVars map[string]string) ContainerOption
- func WithExecutableFiles(basePath string, files ...string) ContainerOption
- func WithExposedPorts(ports ...string) ContainerOption
- func WithFiles(basePath string, files ...string) ContainerOption
- func WithForceWaitDuration(duration time.Duration) ContainerOption
- func WithImage(image string) ContainerOption
- func WithNetwork(alias string, network *testcontainers.DockerNetwork) ContainerOption
- func WithWaitingForLog(log string, startupTimeout time.Duration) ContainerOption
- func WithWaitingForPort(port string, startupTimeout time.Duration) ContainerOption
- type GroupContainer
- type TestContainersOption
func DestroyGroup
func DestroyGroup(ctx context.Context, group GroupContainer) (context.Context, error)DestroyGroup destroys the given group of containers and the network (if exists)
func GetMappedPort
func GetMappedPort(ctx context.Context, container testcontainers.Container, exposedPort nat.Port) (nat.Port, error)func NewGroup
func NewGroup() map[string]GroupContainerNewGroup creates a new map of test contexts to store a group of containers
type Container
Container is a type that represents a container that will be created
type Container struct {
ContainerRequest testcontainers.ContainerRequest
ForceWaitDuration *time.Duration
}func NewContainerDefinition(opts ...ContainerOption) *ContainerNewContainerDefinition creates a new container definition that will be used to create a container
func (*Container) BuildContainer
func (c *Container) BuildContainer(ctx context.Context) (testcontainers.Container, error)BuildContainer creates a new container following the container definition
type ContainerOption
ContainerOption is a type that represents a container option
type ContainerOption func(*Container)func WithDockerfile
func WithDockerfile(fromDockerFile testcontainers.FromDockerfile) ContainerOptionWithDockerfile is a ContainerOption that sets the Dockerfile data of the container
Default: nil
func WithEnvVars
func WithEnvVars(envVars map[string]string) ContainerOptionWithEnvVars is a ContainerOption that sets the environment variables of the container
Default:
POSTGRES_DB: postgres_db
POSTGRES_USER: postgres
POSTGRES_PASSWORD: postgres
func WithExecutableFiles
func WithExecutableFiles(basePath string, files ...string) ContainerOptionWithExecutableFiles is a ContainerOption that sets the executable files of the container that will be copied to the container
Default: nil
func WithExposedPorts
func WithExposedPorts(ports ...string) ContainerOptionWithExposedPorts is a ContainerOption that sets the exposed ports of the container
Default: 5432
func WithFiles
func WithFiles(basePath string, files ...string) ContainerOptionWithFiles is a ContainerOption that sets the startup files of the container that will be copied to the container
Default: nil
func WithForceWaitDuration(duration time.Duration) ContainerOptionWithForceWaitDuration is a ContainerOption that sets the duration to wait for the container to be ready
Default: nil
func WithImage
func WithImage(image string) ContainerOptionWithImage is a ContainerOption that sets the image of the container
Default: postgres:latest
func WithNetwork
func WithNetwork(alias string, network *testcontainers.DockerNetwork) ContainerOptionWithNetwork is a ContainerOption that sets the network of the container
Default: nil
func WithWaitingForLog
func WithWaitingForLog(log string, startupTimeout time.Duration) ContainerOptionWithWaitingForLog is a ContainerOption that sets the log to wait for
Default: ready for start up
func WithWaitingForPort
func WithWaitingForPort(port string, startupTimeout time.Duration) ContainerOptionWithWaitingForPort is a ContainerOption that sets the port to wait for
Example: "8080" for 30 seconds
type GroupContainer
GroupContainer is a type that represents a test context
type GroupContainer struct {
Network *testcontainers.DockerNetwork
Containers []testcontainers.Container
}func BuildGroupContainer
func BuildGroupContainer(opts ...TestContainersOption) GroupContainerBuildGroupContainer creates a new test context with the given options
type TestContainersOption
TestContainersOption is a type that represents a test context option
type TestContainersOption func(*GroupContainer)func WithDockerContainer
func WithDockerContainer(container ...testcontainers.Container) TestContainersOptionWithDockerContainer is a TestContainersOption that sets the containers of the test context
func WithDockerNetwork
func WithDockerNetwork(network *testcontainers.DockerNetwork) TestContainersOptionWithDockerNetwork is a TestContainersOption that sets the network of the test context
import "github.com/jfelipearaujo/testcontainers/pkg/network"type Network
Network is a type that represents a network
type Network struct {
Alias string
Type NetworkType
// contains filtered or unexported fields
}func NewNetwork
func NewNetwork(opts ...NetworkOption) *NetworkNewNetwork creates a new Network
func (*Network) Build
func (ntw *Network) Build(ctx context.Context) (*testcontainers.DockerNetwork, error)Build creates a new DockerNetwork
type NetworkOption
NetworkOption is a type that represents a network option
type NetworkOption func(*Network)func WithAlias
func WithAlias(alias string) NetworkOptionWithAlias is a NetworkOption that sets the alias of the network
Default: network
func WithType
func WithType(typeName NetworkType) NetworkOptionWithType is a NetworkOption that sets the type of the network
Default: bridge
type NetworkType
NetworkType is a type that represents the type of network
type NetworkType stringvar (
// NetworkTypeBridge is a network type that represents a bridge network
NetworkTypeBridge NetworkType = "bridge"
)import "github.com/jfelipearaujo/testcontainers/pkg/state"type CtxKeyType
CtxKeyType is a type that can be used as a key for a context.Context
type CtxKeyType stringtype State
State is a type that can be used to store data in a context.Context It is useful for storing data that needs to be shared between tests
type State[T any] struct {
CtxKey CtxKeyType
}func NewState
func NewState[T any](opts ...StateOption[T]) *State[T]NewState creates a new State
Example:
type test struct {
Name string
}
state := state.NewState[test]()
func (*State[T]) Enrich
func (state *State[T]) Enrich(ctx context.Context, data *T) context.ContextEnrich enriches the context with the data
Example:
type test struct {
Name string
}
state := state.NewState[test]()
ctx := state.Enrich(ctx, &test{
Name: "John",
})
func (*State[T]) Retrieve
func (state *State[T]) Retrieve(ctx context.Context) *TRetrieve retrieves the data from the context
Example:
type test struct {
Name string
}
state := state.NewState[test]()
ctx := state.Enrich(ctx, &test{
Name: "John",
})
data := state.Retrieve(ctx)
fmt.Println(data.Name) // John
type StateOption
StateOption is a type that can be used to configure a State
type StateOption[T any] func(*State[T])func WithCtxKey
func WithCtxKey[T any](ctxKey CtxKeyType) StateOption[T]WithCtxKey is a StateOption that sets the key for the context.Context
Default: default
Example:
type test struct {
Name string
}
state := state.NewState[test](
state.WithCtxKey("test"),
)
import "github.com/jfelipearaujo/testcontainers/pkg/testsuite"- func NewTestSuite(t *testing.T, scenarioInitializer func(ctx *godog.ScenarioContext), opts ...TestSuiteOption)
- type TestSuiteOption
func NewTestSuite
func NewTestSuite(t *testing.T, scenarioInitializer func(ctx *godog.ScenarioContext), opts ...TestSuiteOption)NewTestSuite creates a new test suite
type TestSuiteOption
TestSuiteOption is a type that represents a test suite option
type TestSuiteOption func(*godog.Options)func WithConcurrency
func WithConcurrency(concurrency int) TestSuiteOptionWithConcurrency is a TestSuiteOption that sets the concurrency of the test suite. If the concurrency is set to 0, the test suite will NOT run in parallel
Default: 4
func WithPaths
func WithPaths(paths ...string) TestSuiteOptionWithPaths is a TestSuiteOption that sets the paths of the test suite
Default: "features"
import "github.com/jfelipearaujo/testcontainers/pkg/container/localstack"- Constants
- func BuildEndpoint(ctx context.Context, container testcontainers.Container, opts ...LocalStackOption) (string, error)
- func WithLocalStackContainer() container.ContainerOption
- type LocalStackOption
- type Options
const (
BasePath string = "/etc/localstack/init/ready.d"
ExposedPort string = "4566"
Debug string = "false"
DockerHost string = "unix:///var/run/docker.sock"
DefaultRegion string = "us-east-1"
)func BuildEndpoint
func BuildEndpoint(ctx context.Context, container testcontainers.Container, opts ...LocalStackOption) (string, error)BuildEndpoint returns the endpoint of the LocalStack container
Example: "http://localhost:4566"
func WithLocalStackContainer() container.ContainerOptionReturn a new container definition for a LocalStack container with default options:
DockerImage: "localstack/localstack:3.4"
ExposedPort: "4566"
Environment variables:
DEBUG: false
DOCKER_HOST: "unix:///var/run/docker.sock"
DEFAULT_REGION: "us-east-1"
BasePath: "/etc/localstack/init/ready.d"
WaitingForLog: "Initialization complete!"
StartupTimeout: "30 seconds"
type LocalStackOption
LocalStackOption is a type that represents a LocalStack option
type LocalStackOption func(*Options)func WithDebug
func WithDebug(debug string) LocalStackOptionWithDebug is a LocalStackOption that sets the debug of the LocalStack container
Default: false
func WithDefaultRegion
func WithDefaultRegion(defaultRegion string) LocalStackOptionWithDefaultRegion is a LocalStackOption that sets the default region of the LocalStack container
Default: "us-east-1"
func WithDockerHost
func WithDockerHost(dockerHost string) LocalStackOptionWithDockerHost is a LocalStackOption that sets the Docker host of the LocalStack container
Default: "unix:///var/run/docker.sock"
func WithExposedPort
func WithExposedPort(exposedPort string) LocalStackOptionWithExposedPort is a LocalStackOption that sets the exposed port of the LocalStack container
Default: "4566"
type Options
Options is a type that represents the options for a LocalStack container
Default options:
ExposedPort: "4566"
Debug: false
DockerHost: "unix:///var/run/docker.sock"
DefaultRegion: "us-east-1"
type Options struct {
ExposedPort string
Debug string
DockerHost string
DefaultRegion string
}import "github.com/jfelipearaujo/testcontainers/pkg/container/mongodb"- Constants
- func BuildExternalConnectionString(ctx context.Context, container testcontainers.Container, opts ...MongoOption) (string, error)
- func BuildInternalConnectionString(ctx context.Context, container testcontainers.Container, opts ...MongoOption) (string, error)
- func WithMongoContainer() container.ContainerOption
- type MongoOption
- type Options
const (
ExposedPort string = "27017"
User string = "mongo"
Pass string = "mongo"
)func BuildExternalConnectionString(ctx context.Context, container testcontainers.Container, opts ...MongoOption) (string, error)Return a MongoDB connection string for the given container with default options when the container is NOT in a network
Example: "mongodb://mongo:mongo@localhost:27017/"
func BuildInternalConnectionString(ctx context.Context, container testcontainers.Container, opts ...MongoOption) (string, error)Return a MongoDB connection string for the given container with default options when the container is in a network
Example: "mongodb://mongo:mongo@network_alias:27017/"
func WithMongoContainer
func WithMongoContainer() container.ContainerOptionReturn a new container definition for a MongoDB container with default options
DockerImage: "mongo:7"
Exposed ports: "27017"
Environment variables:
MONGO_INITDB_ROOT_USERNAME: "mongo"
MONGO_INITDB_ROOT_PASSWORD: "mongo"
WaitingForLog: "Waiting for connections"
StartupTimeout: "30 seconds"
type MongoOption
MongoOption is a type that represents a MongoDB option
type MongoOption func(*Options)func WithExposedPort
func WithExposedPort(exposedPort string) MongoOptionWithExposedPort is a MongoOption that sets the exposed port of the MongoDB container
Default: "27017"
func WithNetwork
func WithNetwork(network *network.Network) MongoOptionWithNetwork is a MongoOption that sets the network alias of the MongoDB container
Default: nil
func WithPass
func WithPass(pass string) MongoOptionWithPass is a MongoOption that sets the password of the MongoDB container
Default: "test"
func WithUser
func WithUser(user string) MongoOptionWithUser is a MongoOption that sets the user of the MongoDB container
Default: "test"
type Options
Options is a type that represents the options for a MongoDB container
Default options:
ExposedPort: "27017"
User: "mongo"
Pass: "mongo"
type Options struct {
ExposedPort string
User string
Pass string
NetworkAlias *string
}import "github.com/jfelipearaujo/testcontainers/pkg/container/postgres"- Constants
- func BuildExternalConnectionString(ctx context.Context, container testcontainers.Container, opts ...PostgresOption) (string, error)
- func BuildInternalConnectionString(ctx context.Context, container testcontainers.Container, opts ...PostgresOption) (string, error)
- func WithPostgresContainer() container.ContainerOption
- type Options
- type PostgresOption
const (
BasePath string = "/docker-entrypoint-initdb.d"
ExposedPort string = "5432"
Database string = "postgres_db"
User string = "postgres"
Pass string = "postgres"
)func BuildExternalConnectionString(ctx context.Context, container testcontainers.Container, opts ...PostgresOption) (string, error)Return a PostgreSQL connection string for the given container with default options when the container is NOT in a network
Example: "postgres://postgres:postgres@localhost:5432/postgres_db?sslmode=disable"
func BuildInternalConnectionString(ctx context.Context, container testcontainers.Container, opts ...PostgresOption) (string, error)Return a PostgreSQL connection string for the given container with default options when the container is in a network
Example: "postgres://postgres:postgres@network_alias:5432/postgres_db?sslmode=disable"
func WithPostgresContainer() container.ContainerOptionReturn a new container definition for a PostgreSQL container with default options
DockerImage: "postgres:16"
Exposed ports: "5432"
Environment variables:
POSTGRES_DB: "postgres_db"
POSTGRES_USER: "postgres"
POSTGRES_PASSWORD: "postgres"
BasePath: "/docker-entrypoint-initdb.d"
WaitingForLog: "database system is ready to accept connections"
StartupTimeout: "30 seconds"
type Options
Options is a type that represents the options for a PostgreSQL container
Default options:
ExposedPort: "5432"
Database: "postgres_db"
User: "postgres"
Pass: "postgres"
Default network alias: nil
type Options struct {
ExposedPort string
Database string
User string
Pass string
NetworkAlias *string
}type PostgresOption
PostgresOption is a type that represents a PostgreSQL option
type PostgresOption func(*Options)func WithDatabase
func WithDatabase(database string) PostgresOptionWithDatabase is a PostgresOption that sets the database of the PostgreSQL container
Default: "postgres_db"
func WithExposedPort
func WithExposedPort(exposedPort string) PostgresOptionWithExposedPort is a PostgresOption that sets the exposed port of the PostgreSQL container
Default: "5432"
func WithNetwork
func WithNetwork(network *network.Network) PostgresOptionWithNetwork is a PostgresOption that sets the network alias of the PostgreSQL container
Default: nil
func WithPass
func WithPass(pass string) PostgresOptionWithPass is a PostgresOption that sets the password of the PostgreSQL container
Default: "postgres"
func WithUser
func WithUser(user string) PostgresOptionWithUser is a PostgresOption that sets the user of the PostgreSQL container
Default: "postgres"
Generated by gomarkdoc