feat: building blocks for Go modules

container_test.go

@@ -419,3 +419,57 @@ func TestVolumeMount(t *testing.T) {
 		})
 	}
 }
+
+func TestOverrideContainerRequest(t *testing.T) {
+	req := GenericContainerRequest{
+		ContainerRequest: ContainerRequest{
+			Env: map[string]string{
+				"BAR": "BAR",
+			},
+			Image:        "foo",
+			ExposedPorts: []string{"12345/tcp"},
+			WaitingFor: wait.ForNop(
+				func(ctx context.Context, target wait.StrategyTarget) error {
+					return nil
+				},
+			),
+			Networks: []string{"foo", "bar", "baaz"},
+			NetworkAliases: map[string][]string{
+				"foo": {"foo0", "foo1", "foo2", "foo3"},
+			},
+		},
+	}
+
+	toBeMergedRequest := GenericContainerRequest{
+		ContainerRequest: ContainerRequest{
+			Env: map[string]string{
+				"FOO": "FOO",
+			},
+			Image:        "bar",
+			ExposedPorts: []string{"67890/tcp"},
+			Networks:     []string{"foo1", "bar1"},
+			NetworkAliases: map[string][]string{
+				"foo1": {"bar"},
+			},
+			WaitingFor: wait.ForLog("foo"),
+		},
+	}
+
+	// the toBeMergedRequest should be merged into the req
+	CustomizeRequest(toBeMergedRequest)(&req)
+
+	// toBeMergedRequest should not be changed
+	assert.Equal(t, "", toBeMergedRequest.Env["BAR"])
+	assert.Equal(t, 1, len(toBeMergedRequest.ExposedPorts))
+	assert.Equal(t, "67890/tcp", toBeMergedRequest.ExposedPorts[0])
+
+	// req should be merged with toBeMergedRequest
+	assert.Equal(t, "FOO", req.Env["FOO"])
+	assert.Equal(t, "BAR", req.Env["BAR"])
+	assert.Equal(t, "bar", req.Image)
+	assert.Equal(t, []string{"12345/tcp", "67890/tcp"}, req.ExposedPorts)
+	assert.Equal(t, []string{"foo", "bar", "baaz", "foo1", "bar1"}, req.Networks)
+	assert.Equal(t, []string{"foo0", "foo1", "foo2", "foo3"}, req.NetworkAliases["foo"])
+	assert.Equal(t, []string{"bar"}, req.NetworkAliases["foo1"])
+	assert.Equal(t, wait.ForLog("foo"), req.WaitingFor)
+}

docker.go

@@ -188,7 +188,7 @@ func (c *DockerContainer) SessionID() string {
 // Start will start an already created container
 func (c *DockerContainer) Start(ctx context.Context) error {
 	shortID := c.ID[:12]
-	c.logger.Printf("Starting container id: %s image: %s", shortID, c.Image)
+	c.logger.Printf("🐳 Starting container id: %s image: %s", shortID, c.Image)
 
 	if err := c.provider.client.ContainerStart(ctx, c.ID, types.ContainerStartOptions{}); err != nil {
 		return err
@@ -197,12 +197,12 @@ func (c *DockerContainer) Start(ctx context.Context) error {
 
 	// if a Wait Strategy has been specified, wait before returning
 	if c.WaitingFor != nil {
-		c.logger.Printf("Waiting for container id %s image: %s", shortID, c.Image)
+		c.logger.Printf("🚧 Waiting for container id %s image: %s", shortID, c.Image)
 		if err := c.WaitingFor.WaitUntilReady(ctx, c); err != nil {
 			return err
 		}
 	}
-	c.logger.Printf("Container is ready id: %s image: %s", shortID, c.Image)
+	c.logger.Printf("✅ Container is ready id: %s image: %s", shortID, c.Image)
 	c.isRunning = true
 	return nil
 }

docs/features/creating_container.md

@@ -89,7 +89,7 @@ func TestIntegrationNginxLatestReturn(t *testing.T) {
 
 ### Advanced Settings
 
-The aforementioned `GenericContainer` function and the `ContainerRequest` struct represent a straightforward manner to configure the containers, but you could need to create your containers with more advance settings regarding the config, host config and endpoint settings Docker types. For those more advance settings, _Testcontainers for Go_ offers a way to fully customise the container request and those internal Docker types. These customisations, called _modifiers_, will be applied just before the internal call to the Docker client to create the container.
+The aforementioned `GenericContainer` function and the `ContainerRequest` struct represent a straightforward manner to configure the containers, but you could need to create your containers with more advance settings regarding the config, host config and endpoint settings Docker types. For those more advance settings, _Testcontainers for Go_ offers a way to fully customize the container request and those internal Docker types. These customisations, called _modifiers_, will be applied just before the internal call to the Docker client to create the container.
 
 <!--codeinclude-->
 [Using modifiers](../../lifecycle_test.go) inside_block:reqWithModifiers

docs/modules/index.md

@@ -46,11 +46,59 @@ or for creating a Go module:
 go run . --name ${NAME_OF_YOUR_MODULE} --image "${REGISTRY}/${MODULE}:${TAG}" --title ${TITLE_OF_YOUR_MODULE} --as-module
 ```
 
-## Update Go dependencies in the modules
+### Adding types and methods to the module
+
+We are going to propose a set of steps to follow when adding types and methods to the module:
+
+!!!warning
+    The `StartContainer` function will be eventually deprecated and replaced with `RunContainer`. We are keeping it in certain modules for backwards compatibility, but they will be removed in the future.
+
+- Make sure a public `Container` type exists for the module. This type have to use composition to embed the `testcontainers.Container` type, inheriting all the methods from it.
+- Make sure a `RunContainer` function exists and is public. This function is the entrypoint to the module and will define the initial values for a `testcontainers.GenericContainerRequest` struct, including the image, the default exposed ports, wait strategies, etc. Therefore, the function must initialise the container request with the default values.
+- Define container options for the module. We consider that a best practice for the options is to return a function that returns a modified `testcontainers.GenericContainerRequest` type, and for that, the library already provides with a `testcontainers.CustomizeRequestOption` type representing this function signature.
+- The options will be passed to the `RunContainer` function as variadic arguments after the Go context, and they will be processed right after defining the initial `testcontainers.GenericContainerRequest` struct using a for loop.
+
+```golang
+func RunContainer(ctx context.Context, opts ...testcontainers.CustomizeRequestOption) (*Container, error) {...}
+```
+
+- If needed, define public methods to extract information from the running container, using the `Container` type as receiver. E.g. a connection string to access a database:
+
+```golang
+func (c *Container) ConnectionString(ctx context.Context) (string, error) {...}
+```
+
+- Document the public API with Go comments.
+- Extend the docs to describe the new API of the module. We usually define a parent `Module reference` section, including a `Container options` and a `Container methods` subsections; within each subsection, we define a nested subsection for each option and method, respectively.
+
+### ContainerRequest options
+
+In order to simplify the creation of the container for a given module, `Testcontainers for Go` provides with a set of `testcontainers.CustomizeRequestOption` functions to customise the container request for the module. These options are:
+
+- `testcontainers.CustomizeRequest`: a function that merges the default options with the ones provided by the user. Recommended for completely customising the container request.
+- `testcontainers.WithImage`: a function that sets the image for the container request.
+- `testcontainers.WithConfigModifier`: a function that sets the config Docker type for the container request. Please see [Advanced Settings](../features/creating_container.md#advanced-settings) for more information.
+- `testcontainers.WithEndpointSettingsModifier`: a function that sets the endpoint settings Docker type for the container request. Please see [Advanced Settings](../features/creating_container.md#advanced-settings) for more information.
+- `testcontainers.WithHostConfigModifier`: a function that sets the host config Docker type for the container request. Please see [Advanced Settings](../features/creating_container.md#advanced-settings) for more information.
+- `testcontainers.WithWaitStrategy`: a function that sets the wait strategy for the container request, adding all the passed wait strategies to the container request, using a `testcontainers.MultiStrategy` with 60 seconds of deadline. Please see [Wait strategies](../features/wait/multi.md) for more information.
+- `testcontainers.WithWaitStrategyAndDeadline`: a function that sets the wait strategy for the container request, adding all the passed wait strategies to the container request, using a `testcontainers.MultiStrategy` with the passed deadline. Please see [Wait strategies](../features/wait/multi.md) for more information.
+
+### Update Go dependencies in the modules
 
 To update the Go dependencies in the modules, please run:
 
 ```shell
 $ cd modules
 $ make tidy-examples
 ```
+
+## Interested in converting an example into a module?
+
+The steps to convert an existing example, aka `${THE_EXAMPLE}`, into a module are the following:
+
+1. Rename the module path at the `go.mod`file for your example.
+1. Move the `examples/${THE_EXAMPLE}` directory to `modules/${THE_EXAMPLE}`.
+1. Move the `${THE_EXAMPLE}` dependabot config from the examples section to the modules one, which is located at the bottom.
+1. In the `mkdocs.yml` file, move the entry for `${THE_EXAMPLE}` from examples to modules.
+1. Move `docs/examples${THE_EXAMPLE}.md` file to `docs/modules/${THE_EXAMPLE}`, updating the references to the source code paths.
+1. Update the Github workflow for `${THE_EXAMPLE}`, modifying names and paths.

docs/modules/mysql.md

@@ -19,11 +19,11 @@ go get github.com/testcontainers/testcontainers-go/modules/mysql
 The MySQL module exposes one entrypoint function to create the container, and this function receives two parameters:
 
 ```golang
-func StartContainer(ctx context.Context, opts ...Option) (*MySQLContainer, error) {
+func RunContainer(ctx context.Context, opts ...testcontainers.CustomizeRequestOption) (*MySQLContainer, error) {
 ```
 
 - `context.Context`, the Go context.
-- `Option`, a variad argument for passing options.
+- `testcontainers.CustomizeRequestOption`, a variad argument for passing options.
 
 ## Container Options
 
@@ -35,7 +35,7 @@ When starting the MySQL container, you can pass options in a variadic way to con
 
 ### Set Image
 
-By default, the image used is `mysql:8`.  If you need to use a different image, you can use `WithImage` option.
+By default, the image used is `mysql:8`.  If you need to use a different image, you can use `testcontainers.WithImage` option.
 
 <!--codeinclude-->
 [Custom Image](../../modules/mysql/mysql_test.go) inside_block:withConfigFile

docs/modules/postgres.md

@@ -19,11 +19,11 @@ go get github.com/testcontainers/testcontainers-go/modules/postgres
 The Postgres module exposes one entrypoint function to create the Postgres container, and this function receives two parameters:
 
 ```golang
-func StartContainer(ctx context.Context, opts ...PostgresContainerOption) (*PostgresContainer, error)
+func RunContainer(ctx context.Context, opts ...testcontainers.CustomizeRequestOption) (*PostgresContainer, error)
 ```
 
 - `context.Context`, the Go context.
-- `PostgresContainerOption`, a variad argument for passing options.
+- `testcontainers.CustomizeRequestOption`, a variadic argument for passing options.
 
 ### Container Options
 
@@ -34,8 +34,8 @@ When starting the Postgres container, you can pass options in a variadic way to
 
 #### Image
 
-If you need to set a different Postgres Docker image, you can use `WithImage` with a valid Docker image
-for Postgres. E.g. `WithImage("docker.io/postgres:9.6")`.
+If you need to set a different Postgres Docker image, you can use `testcontainers.WithImage` with a valid Docker image
+for Postgres. E.g. `testcontainers.WithImage("docker.io/postgres:9.6")`.
 
 #### Initial Database
 
@@ -74,7 +74,7 @@ In the case you have a custom config file for Postgres, it's possible to copy th
 #### Wait Strategies
 
 Given you could need to wait for different conditions, in particular using a wait.ForSQL strategy,
-the Postgres container exposes a `WithWaitStrategy` option to set a custom wait strategy.
+the Postgres container exposes a `testcontainers.WithWaitStrategy` option to set a custom wait strategy.
 
 <!--codeinclude-->
 [Set Wait Strategy](../../modules/postgres/postgres_test.go) inside_block:withWaitStrategy

docs/modules/pulsar.md

@@ -33,7 +33,7 @@ Then you can retrieve the broker and the admin url:
 When starting the Pulsar container, you can pass options in a variadic way to configure it.
 
 ### Pulsar Image
-If you need to set a different Pulsar image you can use the `WithPulsarImage`.
+If you need to set a different Pulsar image you can use the `testcontainers.WithImage`.
 
 <!--codeinclude-->
 [Set Pulsar image](../../modules/pulsar/pulsar_test.go) inside_block:setPulsarImage
@@ -87,7 +87,7 @@ If you want to know more about LogConsumers, please check the [Following Contain
 ## Advanced configuration
 
 In the case you need a more advanced configuration regarding the config, host config and endpoint settings Docker types, you can leverage the modifier functions that are available in
-the ContainerRequest. The Pulsar container exposes a way to interact with those modifiers in a simple manner, using the aforementioned options in the `StartContainer` function:
+the ContainerRequest. The Pulsar container exposes a way to interact with those modifiers in a simple manner, using the aforementioned options in the `RunContainer` function:
 
 <!--codeinclude-->
 [Advanced Docker settings](../../modules/pulsar/pulsar_test.go) inside_block:advancedDockerSettings

docs/modules/redis.md

@@ -19,11 +19,11 @@ go get github.com/testcontainers/testcontainers-go/modules/redis
 The Redis module exposes one entrypoint function to create the containerr, and this function receives two parameters:
 
 ```golang
-func StartContainer(ctx context.Context, opts ...RedisContainerOption) (*RedisContainer, error)
+func RunContainer(ctx context.Context, opts ...testcontainers.CustomizeRequestOption) (*RedisContainer, error)
 ```
 
 - `context.Context`, the Go context.
-- `RedisContainerOption`, a variad argument for passing options.
+- `testcontainers.CustomizeRequestOption`, a variad argument for passing options.
 
 ### Container Options
 
@@ -34,8 +34,8 @@ When starting the Redis container, you can pass options in a variadic way to con
 
 #### Image
 
-If you need to set a different Redis Docker image, you can use `WithImage` with a valid Docker image
-for Postgres. E.g. `WithImage("docker.io/redis:7")`.
+If you need to set a different Redis Docker image, you can use `testcontainers.WithImage` with a valid Docker image
+for Postgres. E.g. `testcontainers.WithImage("docker.io/redis:7")`.
 
 <!--codeinclude-->
 [Use a different image](../../modules/redis/redis_test.go) inside_block:withImage

docs/modules/vault.md

@@ -13,10 +13,10 @@ go get github.com/testcontainers/testcontainers-go/modules/vault
 ```
 
 ## Usage example
-The **StartContainer** function is the main entry point to create a new VaultContainer instance. 
+The **RunContainer** function is the main entry point to create a new VaultContainer instance. 
 It takes a context and zero or more Option values to configure the container.
 <!--codeinclude-->
-[Creating a Vault container](../../modules/vault/vault_test.go) inside_block:StartContainer
+[Creating a Vault container](../../modules/vault/vault_test.go) inside_block:RunContainer
 <!--/codeinclude-->
 
 ### Use CLI to read data from Vault container:
@@ -43,7 +43,7 @@ go get -u github.com/hashicorp/vault-client-go
 You can set below options to create Vault container.
 
 ### Image 
-If you need to set a different Vault image, you can use the `WithImageName`. 
+If you need to set a different Vault image, you can use the `testcontainers.WithImage`. 
 
 !!!info
     Default image name is `hashicorp/vault:1.13.0`.

examples/bigtable/go.mod

@@ -27,7 +27,7 @@ require (
 	github.com/cpuguy83/dockercfg v0.3.1 // indirect
 	github.com/dnephin/pflag v1.0.7 // indirect
 	github.com/docker/distribution v2.8.1+incompatible // indirect
-	github.com/docker/docker v23.0.1+incompatible // indirect
+	github.com/docker/docker v23.0.2+incompatible // indirect
 	github.com/docker/go-connections v0.4.0 // indirect
 	github.com/docker/go-units v0.5.0 // indirect
 	github.com/envoyproxy/go-control-plane v0.10.3 // indirect
@@ -42,6 +42,7 @@ require (
 	github.com/google/uuid v1.3.0 // indirect
 	github.com/googleapis/enterprise-certificate-proxy v0.2.3 // indirect
 	github.com/googleapis/gax-go/v2 v2.7.0 // indirect
+	github.com/imdario/mergo v0.3.12 // indirect
 	github.com/klauspost/compress v1.15.9 // indirect
 	github.com/magiconair/properties v1.8.7 // indirect
 	github.com/mattn/go-colorable v0.1.12 // indirect

examples/bigtable/go.sum

@@ -97,8 +97,8 @@ github.com/dnephin/pflag v1.0.7 h1:oxONGlWxhmUct0YzKTgrpQv9AUA1wtPBn7zuSjJqptk=
 github.com/dnephin/pflag v1.0.7/go.mod h1:uxE91IoWURlOiTUIA8Mq5ZZkAv3dPUfZNaT80Zm7OQE=
 github.com/docker/distribution v2.8.1+incompatible h1:Q50tZOPR6T/hjNsyc9g8/syEs6bk8XXApsHjKukMl68=
 github.com/docker/distribution v2.8.1+incompatible/go.mod h1:J2gT2udsDAN96Uj4KfcMRqY0/ypR+oyYUYmja8H+y+w=
-github.com/docker/docker v23.0.1+incompatible h1:vjgvJZxprTTE1A37nm+CLNAdwu6xZekyoiVlUZEINcY=
-github.com/docker/docker v23.0.1+incompatible/go.mod h1:eEKB0N0r5NX/I1kEveEz05bcu8tLC/8azJZsviup8Sk=
+github.com/docker/docker v23.0.2+incompatible h1:q81C2qQ/EhPm8COZMUGOQYh4qLv4Xu6CXELJ3WK/mlU=
+github.com/docker/docker v23.0.2+incompatible/go.mod h1:eEKB0N0r5NX/I1kEveEz05bcu8tLC/8azJZsviup8Sk=
 github.com/docker/go-connections v0.4.0 h1:El9xVISelRB7BuFusrZozjnkIM5YnzCViNKohAFqRJQ=
 github.com/docker/go-connections v0.4.0/go.mod h1:Gbd7IOopHjR8Iph03tsViu4nIes5XhDvyHbTtUxmeec=
 github.com/docker/go-units v0.4.0/go.mod h1:fgPhTUdO+D/Jk86RDLlptpiXQzgHJF7gydDDbaIK4Dk=
@@ -205,6 +205,8 @@ github.com/hashicorp/golang-lru v0.5.0/go.mod h1:/m3WP610KZHVQ1SGc6re/UDhFvYD7pJ
 github.com/hashicorp/golang-lru v0.5.1/go.mod h1:/m3WP610KZHVQ1SGc6re/UDhFvYD7pJ4Ao+sR/qLZy8=
 github.com/iancoleman/strcase v0.2.0/go.mod h1:iwCmte+B7n89clKwxIoIXy/HfoL7AsD47ZCWhYzw7ho=
 github.com/ianlancetaylor/demangle v0.0.0-20181102032728-5e5cf60278f6/go.mod h1:aSSvb/t6k1mPoxDqO4vJh6VOCGPwU4O0C2/Eqndh1Sc=
+github.com/imdario/mergo v0.3.12 h1:b6R2BslTbIEToALKP7LxUvijTsNI9TAe80pLWN2g/HU=
+github.com/imdario/mergo v0.3.12/go.mod h1:jmQim1M+e3UYxmgPu/WyfjB3N3VflVyUjjjwH0dnCYA=
 github.com/jstemmer/go-junit-report v0.0.0-20190106144839-af01ea7f8024/go.mod h1:6v2b51hI/fHJwM22ozAgKL4VKDeJcHhJFhtBdhmNjmU=
 github.com/jstemmer/go-junit-report v0.9.1/go.mod h1:Brl9GWCQeLvo8nXZwPNNblvFj/XSXhF0NWZEnDohbsk=
 github.com/kisielk/errcheck v1.5.0/go.mod h1:pFxgyoBC7bSaBwPgfKdkLd5X25qrDl4LWUI2bnpBCr8=
@@ -617,6 +619,8 @@ gopkg.in/check.v1 v1.0.0-20180628173108-788fd7840127/go.mod h1:Co6ibVJAznAaIkqp8
 gopkg.in/errgo.v2 v2.1.0/go.mod h1:hNsd1EY+bozCKY1Ytp96fpM3vjJbqLJn88ws8XvfDNI=
 gopkg.in/yaml.v2 v2.2.2/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI=
 gopkg.in/yaml.v2 v2.2.3/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI=
+gopkg.in/yaml.v2 v2.3.0/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI=
+gopkg.in/yaml.v2 v2.4.0 h1:D8xgwECY7CYvx+Y2n4sBz93Jn9JRvxdiyyo8CTfuKaY=
 gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
 gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
 gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=

examples/cockroachdb/go.mod

@@ -21,14 +21,15 @@ require (
 	github.com/davecgh/go-spew v1.1.1 // indirect
 	github.com/dnephin/pflag v1.0.7 // indirect
 	github.com/docker/distribution v2.8.1+incompatible // indirect
-	github.com/docker/docker v23.0.1+incompatible // indirect
+	github.com/docker/docker v23.0.2+incompatible // indirect
 	github.com/docker/go-connections v0.4.0 // indirect
 	github.com/docker/go-units v0.5.0 // indirect
 	github.com/fatih/color v1.13.0 // indirect
 	github.com/fsnotify/fsnotify v1.5.4 // indirect
 	github.com/gogo/protobuf v1.3.2 // indirect
 	github.com/golang/protobuf v1.5.2 // indirect
 	github.com/google/shlex v0.0.0-20191202100458-e7afc7fbc510 // indirect
+	github.com/imdario/mergo v0.3.12 // indirect
 	github.com/jackc/chunkreader/v2 v2.0.1 // indirect
 	github.com/jackc/pgconn v1.14.0 // indirect
 	github.com/jackc/pgio v1.0.0 // indirect