Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/jfelipearaujo/testcontainers
This is an addon to be used with Testcontainers package and with GoDog
https://github.com/jfelipearaujo/testcontainers
bdd godog testcontainers testcontainers-go
Last synced: 4 days ago
JSON representation
This is an addon to be used with Testcontainers package and with GoDog
- Host: GitHub
- URL: https://github.com/jfelipearaujo/testcontainers
- Owner: jfelipearaujo
- License: mit
- Created: 2024-06-05T22:14:37.000Z (7 months ago)
- Default Branch: main
- Last Pushed: 2024-06-13T22:19:17.000Z (7 months ago)
- Last Synced: 2024-12-22T04:08:42.160Z (12 days ago)
- Topics: bdd, godog, testcontainers, testcontainers-go
- Language: Go
- Homepage:
- Size: 104 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
[](https://github.com/jfelipearaujo/testcontainers/actions/workflows/tests.yml)
[](https://github.com/jfelipearaujo/testcontainers/releases/latest)
[](https://pkg.go.dev/github.com/jfelipearaujo/testcontainers#section-readme)
[](https://github.com/jfelipearaujo/testcontainers/blob/main/LICENSE)
# testcontainers
This is an addon to be used with Testcontainers package and with GoDog
## Installation
```bash
go get github.com/jfelipearaujo/testcontainers@latest
```
## How to use
To use this addon, you need to import the packages in your project:
```go
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"
```
# Examples
| Example | Description |
| --- | --- |
| [Example 01](./examples/example_01/README.md) | Simple BDD test.
| [Example 02](./examples/example_02/README.md) | Using a Postgres container.
| [Example 03](./examples/example_03/README.md) | Using aLocalStack container.
| [Example 04](./examples/example_04/README.md) | Using a MongoDB container.
| [Example 05](./examples/example_05/README.md) | Custom API running on a container via Dockerfile.
| [Example 06](./examples/example_06/README.md) | Two containers interacting with each other using a Network.
# Full documentation
# container
```go
import "github.com/jfelipearaujo/testcontainers/pkg/container"
```
## Index
- [func DestroyGroup\(ctx context.Context, group GroupContainer\) \(context.Context, error\)](<#DestroyGroup>)
- [func GetMappedPort\(ctx context.Context, container testcontainers.Container, exposedPort nat.Port\) \(nat.Port, error\)](<#GetMappedPort>)
- [func NewGroup\(\) map\[string\]GroupContainer](<#NewGroup>)
- [type Container](<#Container>)
- [func NewContainerDefinition\(opts ...ContainerOption\) \*Container](<#NewContainerDefinition>)
- [func \(c \*Container\) BuildContainer\(ctx context.Context\) \(testcontainers.Container, error\)](<#Container.BuildContainer>)
- [type ContainerOption](<#ContainerOption>)
- [func WithDockerfile\(fromDockerFile testcontainers.FromDockerfile\) ContainerOption](<#WithDockerfile>)
- [func WithEnvVars\(envVars map\[string\]string\) ContainerOption](<#WithEnvVars>)
- [func WithExecutableFiles\(basePath string, files ...string\) ContainerOption](<#WithExecutableFiles>)
- [func WithExposedPorts\(ports ...string\) ContainerOption](<#WithExposedPorts>)
- [func WithFiles\(basePath string, files ...string\) ContainerOption](<#WithFiles>)
- [func WithForceWaitDuration\(duration time.Duration\) ContainerOption](<#WithForceWaitDuration>)
- [func WithImage\(image string\) ContainerOption](<#WithImage>)
- [func WithNetwork\(alias string, network \*testcontainers.DockerNetwork\) ContainerOption](<#WithNetwork>)
- [func WithWaitingForLog\(log string, startupTimeout time.Duration\) ContainerOption](<#WithWaitingForLog>)
- [func WithWaitingForPort\(port string, startupTimeout time.Duration\) ContainerOption](<#WithWaitingForPort>)
- [type GroupContainer](<#GroupContainer>)
- [func BuildGroupContainer\(opts ...TestContainersOption\) GroupContainer](<#BuildGroupContainer>)
- [type TestContainersOption](<#TestContainersOption>)
- [func WithDockerContainer\(container ...testcontainers.Container\) TestContainersOption](<#WithDockerContainer>)
- [func WithDockerNetwork\(network \*testcontainers.DockerNetwork\) TestContainersOption](<#WithDockerNetwork>)
```go
func DestroyGroup(ctx context.Context, group GroupContainer) (context.Context, error)
```
DestroyGroup destroys the given group of containers and the network \(if exists\)
```go
func GetMappedPort(ctx context.Context, container testcontainers.Container, exposedPort nat.Port) (nat.Port, error)
```
```go
func NewGroup() map[string]GroupContainer
```
NewGroup creates a new map of test contexts to store a group of containers
Container is a type that represents a container that will be created
```go
type Container struct {
ContainerRequest testcontainers.ContainerRequest
ForceWaitDuration *time.Duration
}
```
### func [NewContainerDefinition]()
```go
func NewContainerDefinition(opts ...ContainerOption) *Container
```
NewContainerDefinition creates a new container definition that will be used to create a container
### func \(\*Container\) [BuildContainer]()
```go
func (c *Container) BuildContainer(ctx context.Context) (testcontainers.Container, error)
```
BuildContainer creates a new container following the container definition
ContainerOption is a type that represents a container option
```go
type ContainerOption func(*Container)
```
```go
func WithDockerfile(fromDockerFile testcontainers.FromDockerfile) ContainerOption
```
WithDockerfile is a ContainerOption that sets the Dockerfile data of the container
Default: nil
```go
func WithEnvVars(envVars map[string]string) ContainerOption
```
WithEnvVars is a ContainerOption that sets the environment variables of the container
Default:
```
POSTGRES_DB: postgres_db
POSTGRES_USER: postgres
POSTGRES_PASSWORD: postgres
```
### func [WithExecutableFiles]()
```go
func WithExecutableFiles(basePath string, files ...string) ContainerOption
```
WithExecutableFiles is a ContainerOption that sets the executable files of the container that will be copied to the container
Default: nil
```go
func WithExposedPorts(ports ...string) ContainerOption
```
WithExposedPorts is a ContainerOption that sets the exposed ports of the container
Default: 5432
```go
func WithFiles(basePath string, files ...string) ContainerOption
```
WithFiles is a ContainerOption that sets the startup files of the container that will be copied to the container
Default: nil
### func [WithForceWaitDuration]()
```go
func WithForceWaitDuration(duration time.Duration) ContainerOption
```
WithForceWaitDuration is a ContainerOption that sets the duration to wait for the container to be ready
```
Default: nil
```
```go
func WithImage(image string) ContainerOption
```
WithImage is a ContainerOption that sets the image of the container
Default: postgres:latest
```go
func WithNetwork(alias string, network *testcontainers.DockerNetwork) ContainerOption
```
WithNetwork is a ContainerOption that sets the network of the container
Default: nil
### func [WithWaitingForLog]()
```go
func WithWaitingForLog(log string, startupTimeout time.Duration) ContainerOption
```
WithWaitingForLog is a ContainerOption that sets the log to wait for
Default: ready for start up
### func [WithWaitingForPort]()
```go
func WithWaitingForPort(port string, startupTimeout time.Duration) ContainerOption
```
WithWaitingForPort is a ContainerOption that sets the port to wait for
```
Example: "8080" for 30 seconds
```
GroupContainer is a type that represents a test context
```go
type GroupContainer struct {
Network *testcontainers.DockerNetwork
Containers []testcontainers.Container
}
```
### func [BuildGroupContainer]()
```go
func BuildGroupContainer(opts ...TestContainersOption) GroupContainer
```
BuildGroupContainer creates a new test context with the given options
## type [TestContainersOption]()
TestContainersOption is a type that represents a test context option
```go
type TestContainersOption func(*GroupContainer)
```
### func [WithDockerContainer]()
```go
func WithDockerContainer(container ...testcontainers.Container) TestContainersOption
```
WithDockerContainer is a TestContainersOption that sets the containers of the test context
### func [WithDockerNetwork]()
```go
func WithDockerNetwork(network *testcontainers.DockerNetwork) TestContainersOption
```
WithDockerNetwork is a TestContainersOption that sets the network of the test context
# network
```go
import "github.com/jfelipearaujo/testcontainers/pkg/network"
```
## Index
- [type Network](<#Network>)
- [func NewNetwork\(opts ...NetworkOption\) \*Network](<#NewNetwork>)
- [func \(ntw \*Network\) Build\(ctx context.Context\) \(\*testcontainers.DockerNetwork, error\)](<#Network.Build>)
- [type NetworkOption](<#NetworkOption>)
- [func WithAlias\(alias string\) NetworkOption](<#WithAlias>)
- [func WithType\(typeName NetworkType\) NetworkOption](<#WithType>)
- [type NetworkType](<#NetworkType>)
Network is a type that represents a network
```go
type Network struct {
Alias string
Type NetworkType
// contains filtered or unexported fields
}
```
```go
func NewNetwork(opts ...NetworkOption) *Network
```
NewNetwork creates a new Network
### func \(\*Network\) [Build]()
```go
func (ntw *Network) Build(ctx context.Context) (*testcontainers.DockerNetwork, error)
```
Build creates a new DockerNetwork
NetworkOption is a type that represents a network option
```go
type NetworkOption func(*Network)
```
```go
func WithAlias(alias string) NetworkOption
```
WithAlias is a NetworkOption that sets the alias of the network
Default: network
```go
func WithType(typeName NetworkType) NetworkOption
```
WithType is a NetworkOption that sets the type of the network
Default: bridge
NetworkType is a type that represents the type of network
```go
type NetworkType string
```
```go
var (
// NetworkTypeBridge is a network type that represents a bridge network
NetworkTypeBridge NetworkType = "bridge"
)
```
# state
```go
import "github.com/jfelipearaujo/testcontainers/pkg/state"
```
## Index
- [type CtxKeyType](<#CtxKeyType>)
- [type State](<#State>)
- [func NewState\[T any\]\(opts ...StateOption\[T\]\) \*State\[T\]](<#NewState>)
- [func \(state \*State\[T\]\) Enrich\(ctx context.Context, data \*T\) context.Context](<#State[T].Enrich>)
- [func \(state \*State\[T\]\) Retrieve\(ctx context.Context\) \*T](<#State[T].Retrieve>)
- [type StateOption](<#StateOption>)
- [func WithCtxKey\[T any\]\(ctxKey CtxKeyType\) StateOption\[T\]](<#WithCtxKey>)
CtxKeyType is a type that can be used as a key for a context.Context
```go
type CtxKeyType string
```
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
```go
type State[T any] struct {
CtxKey CtxKeyType
}
```
```go
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]()
```go
func (state *State[T]) Enrich(ctx context.Context, data *T) context.Context
```
Enrich 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]()
```go
func (state *State[T]) Retrieve(ctx context.Context) *T
```
Retrieve 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
StateOption is a type that can be used to configure a State
```go
type StateOption[T any] func(*State[T])
```
```go
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"),
)
```
# testsuite
```go
import "github.com/jfelipearaujo/testcontainers/pkg/testsuite"
```
## Index
- [func NewTestSuite\(t \*testing.T, scenarioInitializer func\(ctx \*godog.ScenarioContext\), opts ...TestSuiteOption\)](<#NewTestSuite>)
- [type TestSuiteOption](<#TestSuiteOption>)
- [func WithConcurrency\(concurrency int\) TestSuiteOption](<#WithConcurrency>)
- [func WithPaths\(paths ...string\) TestSuiteOption](<#WithPaths>)
```go
func NewTestSuite(t *testing.T, scenarioInitializer func(ctx *godog.ScenarioContext), opts ...TestSuiteOption)
```
NewTestSuite creates a new test suite
TestSuiteOption is a type that represents a test suite option
```go
type TestSuiteOption func(*godog.Options)
```
```go
func WithConcurrency(concurrency int) TestSuiteOption
```
WithConcurrency 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
```go
func WithPaths(paths ...string) TestSuiteOption
```
WithPaths is a TestSuiteOption that sets the paths of the test suite
Default: "features"
# localstack
```go
import "github.com/jfelipearaujo/testcontainers/pkg/container/localstack"
```
## Index
- [Constants](<#constants>)
- [func BuildEndpoint\(ctx context.Context, container testcontainers.Container, opts ...LocalStackOption\) \(string, error\)](<#BuildEndpoint>)
- [func WithLocalStackContainer\(\) container.ContainerOption](<#WithLocalStackContainer>)
- [type LocalStackOption](<#LocalStackOption>)
- [func WithDebug\(debug string\) LocalStackOption](<#WithDebug>)
- [func WithDefaultRegion\(defaultRegion string\) LocalStackOption](<#WithDefaultRegion>)
- [func WithDockerHost\(dockerHost string\) LocalStackOption](<#WithDockerHost>)
- [func WithExposedPort\(exposedPort string\) LocalStackOption](<#WithExposedPort>)
- [type Options](<#Options>)
## Constants
```go
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"
)
```
```go
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]()
```go
func WithLocalStackContainer() container.ContainerOption
```
Return 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"
```
LocalStackOption is a type that represents a LocalStack option
```go
type LocalStackOption func(*Options)
```
```go
func WithDebug(debug string) LocalStackOption
```
WithDebug is a LocalStackOption that sets the debug of the LocalStack container
```
Default: false
```
### func [WithDefaultRegion]()
```go
func WithDefaultRegion(defaultRegion string) LocalStackOption
```
WithDefaultRegion is a LocalStackOption that sets the default region of the LocalStack container
```
Default: "us-east-1"
```
```go
func WithDockerHost(dockerHost string) LocalStackOption
```
WithDockerHost is a LocalStackOption that sets the Docker host of the LocalStack container
```
Default: "unix:///var/run/docker.sock"
```
```go
func WithExposedPort(exposedPort string) LocalStackOption
```
WithExposedPort is a LocalStackOption that sets the exposed port of the LocalStack container
```
Default: "4566"
```
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"
```
```go
type Options struct {
ExposedPort string
Debug string
DockerHost string
DefaultRegion string
}
```
# mongodb
```go
import "github.com/jfelipearaujo/testcontainers/pkg/container/mongodb"
```
## Index
- [Constants](<#constants>)
- [func BuildExternalConnectionString\(ctx context.Context, container testcontainers.Container, opts ...MongoOption\) \(string, error\)](<#BuildExternalConnectionString>)
- [func BuildInternalConnectionString\(ctx context.Context, container testcontainers.Container, opts ...MongoOption\) \(string, error\)](<#BuildInternalConnectionString>)
- [func WithMongoContainer\(\) container.ContainerOption](<#WithMongoContainer>)
- [type MongoOption](<#MongoOption>)
- [func WithExposedPort\(exposedPort string\) MongoOption](<#WithExposedPort>)
- [func WithNetwork\(network \*network.Network\) MongoOption](<#WithNetwork>)
- [func WithPass\(pass string\) MongoOption](<#WithPass>)
- [func WithUser\(user string\) MongoOption](<#WithUser>)
- [type Options](<#Options>)
## Constants
```go
const (
ExposedPort string = "27017"
User string = "mongo"
Pass string = "mongo"
)
```
## func [BuildExternalConnectionString]()
```go
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]()
```go
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]()
```go
func WithMongoContainer() container.ContainerOption
```
Return 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"
```
MongoOption is a type that represents a MongoDB option
```go
type MongoOption func(*Options)
```
```go
func WithExposedPort(exposedPort string) MongoOption
```
WithExposedPort is a MongoOption that sets the exposed port of the MongoDB container
```
Default: "27017"
```
```go
func WithNetwork(network *network.Network) MongoOption
```
WithNetwork is a MongoOption that sets the network alias of the MongoDB container
```
Default: nil
```
```go
func WithPass(pass string) MongoOption
```
WithPass is a MongoOption that sets the password of the MongoDB container
```
Default: "test"
```
```go
func WithUser(user string) MongoOption
```
WithUser is a MongoOption that sets the user of the MongoDB container
```
Default: "test"
```
Options is a type that represents the options for a MongoDB container
```
Default options:
ExposedPort: "27017"
User: "mongo"
Pass: "mongo"
```
```go
type Options struct {
ExposedPort string
User string
Pass string
NetworkAlias *string
}
```
# postgres
```go
import "github.com/jfelipearaujo/testcontainers/pkg/container/postgres"
```
## Index
- [Constants](<#constants>)
- [func BuildExternalConnectionString\(ctx context.Context, container testcontainers.Container, opts ...PostgresOption\) \(string, error\)](<#BuildExternalConnectionString>)
- [func BuildInternalConnectionString\(ctx context.Context, container testcontainers.Container, opts ...PostgresOption\) \(string, error\)](<#BuildInternalConnectionString>)
- [func WithPostgresContainer\(\) container.ContainerOption](<#WithPostgresContainer>)
- [type Options](<#Options>)
- [type PostgresOption](<#PostgresOption>)
- [func WithDatabase\(database string\) PostgresOption](<#WithDatabase>)
- [func WithExposedPort\(exposedPort string\) PostgresOption](<#WithExposedPort>)
- [func WithNetwork\(network \*network.Network\) PostgresOption](<#WithNetwork>)
- [func WithPass\(pass string\) PostgresOption](<#WithPass>)
- [func WithUser\(user string\) PostgresOption](<#WithUser>)
## Constants
```go
const (
BasePath string = "/docker-entrypoint-initdb.d"
ExposedPort string = "5432"
Database string = "postgres_db"
User string = "postgres"
Pass string = "postgres"
)
```
## func [BuildExternalConnectionString]()
```go
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]()
```go
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]()
```go
func WithPostgresContainer() container.ContainerOption
```
Return 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"
```
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
```
```go
type Options struct {
ExposedPort string
Database string
User string
Pass string
NetworkAlias *string
}
```
PostgresOption is a type that represents a PostgreSQL option
```go
type PostgresOption func(*Options)
```
```go
func WithDatabase(database string) PostgresOption
```
WithDatabase is a PostgresOption that sets the database of the PostgreSQL container
```
Default: "postgres_db"
```
```go
func WithExposedPort(exposedPort string) PostgresOption
```
WithExposedPort is a PostgresOption that sets the exposed port of the PostgreSQL container
```
Default: "5432"
```
```go
func WithNetwork(network *network.Network) PostgresOption
```
WithNetwork is a PostgresOption that sets the network alias of the PostgreSQL container
```
Default: nil
```
```go
func WithPass(pass string) PostgresOption
```
WithPass is a PostgresOption that sets the password of the PostgreSQL container
```
Default: "postgres"
```
```go
func WithUser(user string) PostgresOption
```
WithUser is a PostgresOption that sets the user of the PostgreSQL container
```
Default: "postgres"
```
Generated by [gomarkdoc]()