Creating Modules in Testcontainers for Go

Often your projects depend on a certain technology in a very recurrent manner, and you could find yourself in the situation of moving code to interact with that technology from one project to another. “Why don’t we package this code into a library and consume it everywhere?”

That’s when your mind recalls certain software engineering best practices, such as modularity, decoupling, and cohesion.

In this blog post, we’ll explain how to create a new module for Testcontainers for Go, representing that technology you use in your projects and for which you want to test your code against.

Creating a module from scratch

A Testcontainers for Go module is just a Go module that will expose an API for a given technology. To make it easier to create the Go module from scratch, Testcontainers for Go provides a command-line tool to generate the scaffolding for the code of the module you are interested in, so you can get started quickly.

This tool will generate:

• A Go module for the technology, including:
  • go.mod and go.sum files, including the current version of Testcontainers for Go.
  • A Go package named after the module, in lowercase.
  • A Go file for the creation of the container, using a dedicated struct in which the value of the image flag is used as Docker image.
  • A Go test file for running a simple test for your container, consuming the above struct.
  • A Makefile to run the tests in a consistent manner.
• A markdown file in the docs/modules directory including the snippets for both the creation of the container and a simple test. By default, this generated file will contain all the documentation for the module, including:
  • The version of Testcontainers for Go in which the module was added.
  • A short introduction to the module.
  • A section for adding the module to the project dependencies.
  • A section for a usage example, including a snippet for creating the container, from the examples_test.go file in the Go module.
  • A section for the module reference, including the entrypoint function for creating the container, and the options for creating the container.
  • A section for the container methods.
• A new Nav entry for the module in the docs site, adding it to the mkdocs.yml file located at the root directory of the project.
• A GitHub workflow file in the .github/workflows directory to run the tests for the technology.
• An entry in the VSCode workspace file, in order to include the new model in the project’s workspace..

The code-generation tool

The code-generation tool is a Go program that lives in the modulegen directory as a Go module, to avoid distributing Go dependencies with Testcontainers for Go, and its only purpose is to create the scaffolding for a Go module using Go templates.

The command-line flags of the code generation tool are described in Table 1:

If the module name or title does not contain alphanumeric characters, the program will exit the generation. And, if the module already exists, it will exit without updating the existing files.

From the modulegen directory, run:

go run . new module --name ${NAME_OF_YOUR_MODULE} --image "${REGISTRY}/${MODULE}:${TAG}" --title ${TITLE_OF_YOUR_MODULE}

Adding types and methods to the module

We propose the following set of steps to follow when adding types and methods to the module:

1. Make sure a public Container type exists for the module. This type has to use composition to embed the testcontainers.Container type, promoting all the methods from it.
2. 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. As a result, the function must initialize the container request with the default values.
3. Define container options for the module leveraging the testcontainers.ContainerCustomizer interface, that has one single method: Customize(req *GenericContainerRequest) error.

Note: We consider that a best practice for the options is to define a function using the With prefix, and then return a function returning a modified testcontainers.GenericContainerRequest type. For that, the library already provides a testcontainers.CustomizeRequestOption type implementing the ContainerCustomizer interface, and we encourage you to use this type for creating your own customizer functions.

4. At the same time, you might need to create your own container customizers for your module. Make sure they implement the testcontainers.ContainerCustomizer interface. Defining your own customizer functions is useful when you need to transfer a certain state that is not present at the ContainerRequest for the container, and possibly using an intermediate Config struct. Take a look at MyCustomizer and WithMy in the snippet below.
5. 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.
6. If needed, define public methods to extract information from the running container, using the Container type as receiver. As an example, a helpful method could be a connection string to access a database. When adding container methods, please consider what will be useful for the users.
7. Document the public API with Go comments.
8. Extend the docs to describe the new API of the module. The code-generation tool already creates a parent Module reference section, including a Container options and a Container methods subsections; within each subsection, please define a nested subsection for each option and method, respectively.

The following snippet shows an example of what the code should look like:

type ModuleContainer struct {
   testcontainers.Container
   cfg *Config
}
// Config type represents an intermediate struct for transferring state from the options to the container
type Config struct {
   data string
}
// RunContainer is the entrypoint to the module
func RunContainer(ctx context.Context, opts ...testcontainers.ContainerCustomizer) (*Container, error) {
   cfg := Config{}
   req := testcontainers.ContainerRequest{
       Image: "my-image",
       //...
   }
   genericContainerReq := testcontainers.GenericContainerRequest{
       ContainerRequest: req,
       Started:          true,
   }
   //...
   for _, opt := range opts {
       if err := opt.Customize(&genericContainerReq); err != nil {
       	return nil, err
       }
       // If you need to transfer some state from the options to the container, you can do it here
       if myCustomizer, ok := opt.(MyCustomizer); ok {
           config.data = customizer.data
       }
   }
   //...
   container, err := testcontainers.GenericContainer(ctx, genericContainerReq)
   //...
   moduleContainer := &Container{Container: container}
   // use config.data here to initialize the state in the running container
   //...
   return moduleContainer, nil
}
// MyCustomizer type represents a container customizer for transferring state from the options to the container
type MyCustomizer struct {
   data string
}
// Customize method implementation
func (c MyCustomizer) Customize(req *testcontainers.GenericContainerRequest) testcontainers.ContainerRequest {
   req.ExposedPorts = append(req.ExposedPorts, "1234/tcp")
   return req.ContainerRequest
}
// WithMy function option to use the customizer
func WithMy(data string) testcontainers.ContainerCustomizer {
   return MyCustomizer{data: data}
}
// WithSomeState function option leveraging the functional option
func WithSomeState(value string) testcontainers.CustomizeRequestOption {
   return func(req *testcontainers.GenericContainerRequest) {
       req.Env["MY_ENV_VAR"] = value
   }
}
// ConnectionString returns the connection to the module container
func (c *Container) ConnectionString(ctx context.Context) (string, error) {...}

ContainerRequest options

To simplify the creation of the container for a given module, Testcontainers for Go provides a set of testcontainers.CustomizeRequestOption functions to customize the container request for the module. They will allow you to fully customize the container request for your service.

These options are:

• testcontainers.WithImage: A function that sets the image for the container request.
• testcontainers.WithImageSubstitutors: A function that sets your own substitutions to the container images.
• testcontainers.WithEnv: A function that sets the environment variables for the container request.
• testcontainers.WithHostPortAccess: A function that enables the container to access a port that is already running in the host.
• testcontainers.WithLogConsumers: A function that sets the log consumers for the container request.
• testcontainers.WithLogger: A function that sets the logger for the container request.
• 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 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 for more information.
• testcontainers.WithStartupCommand: A function that sets the execution of a command when the container starts.
• testcontainers.WithAfterReadyCommand: A function that sets the execution of a command right after the container is ready (its wait strategy is satisfied).
• testcontainers.WithNetwork: A function that sets the network and the network aliases for the container request.
• testcontainers.WithNewNetwork: A function that sets the network aliases for a throwaway network for the container request.
• testcontainers.WithConfigModifier: A function that sets the config Docker type for the container request. Please see Advanced Settings for more information.
• testcontainers.WithEndpointSettingsModifier: A function that sets the endpoint settings Docker type for the container request. Please see Advanced Settings for more information.
• testcontainers.WithHostConfigModifier: A function that sets the host config Docker type for the container request. Please see Advanced Settings for more information.
• testcontainers.CustomizeRequest: A function that merges the default testcontainers.GenericContainerRequest with the ones provided by the user. Recommended for completely customizing the container request.

You could use any of them to customize the container when calling the RunContainer function. An example, for the LocalStack module, would be:

container, err := localstack.RunContainer(ctx,
testcontainers.WithImage("localstack/localstack:2.0.0"),
testcontainers.WithEnv(map[string]string{"SERVICES": "s3,sqs"}),
)

Conclusion

In this article, we shared how to create a Go module for Testcontainers for Go, adding custom types, methods, and customizers. Finally, we discovered how to use the code-generation tool to create the scaffolding for a new module.

Want to know more about modules? Check out the following links:

• Testcontainers Modules
• Testcontainers for Go modules

Learn more

• Subscribe to the Docker Newsletter.
• Get started with Testcontainers Cloud by creating a free account.
• Connect on the Testcontainers Slack.
• Learn about Testcontainers best practices.
• Get started with the Testcontainers guide.