Testcontainers-Go Booster

Boost testcontainers/testcontainers-go with some jet fuel! 🚀

Prerequisites

• Go >= 1.22

Install

go get go.nhat.io/testcontainers-extra

Callbacks

After successfully starting a container, you may want to do some extra operations to make it ready for your purposes. Then you could use the callbacks.

For example:

package example

import (
	"context"
	"time"

	"go.nhat.io/testcontainers-extra"
	"go.nhat.io/testcontainers-extra/wait"
)

func startPostgres(dbName, dbUser, dbPassword string) error {
	_, err := testcontainers.StartGenericContainer(context.Background(), testcontainers.ContainerRequest{
		Name:         "postgres",
		Image:        "postgres:12-alpine",
		ExposedPorts: []string{":5432"},
		Env: map[string]string{
			"LC_ALL":            "C.UTF-8",
			"POSTGRES_DB":       dbName,
			"POSTGRES_USER":     dbUser,
			"POSTGRES_PASSWORD": dbPassword,
		},
		WaitingFor: wait.ForHealthCheckCmd("pg_isready").
			WithRetries(3).
			WithStartPeriod(30 * time.Second).
			WithTestTimeout(5 * time.Second).
			WithTestInterval(10 * time.Second),
	}, testcontainers.WithCallback(func(ctx context.Context, c testcontainers.Container, r testcontainers.ContainerRequest) error {
		// Do your stuff here, for example, migration.

		return nil
	}))

	return err
}

Populating Host and Ports Envs

testcontainers.PopulateHostPortEnv is a callback that set the environment variables for the exposed ports.

For example:

package example

import (
	"context"
	"time"

	"go.nhat.io/testcontainers-extra"
	"go.nhat.io/testcontainers-extra/wait"
)

func startPostgres(dbName, dbUser, dbPassword string) error {
	_, err := testcontainers.StartGenericContainer(context.Background(), testcontainers.ContainerRequest{
		Name:         "postgres",
		Image:        "postgres:12-alpine",
		ExposedPorts: []string{":5432"},
		Env: map[string]string{
			"LC_ALL":            "C.UTF-8",
			"POSTGRES_DB":       dbName,
			"POSTGRES_USER":     dbUser,
			"POSTGRES_PASSWORD": dbPassword,
		},
		WaitingFor: wait.ForHealthCheckCmd("pg_isready").
			WithRetries(3).
			WithStartPeriod(30 * time.Second).
			WithTestTimeout(5 * time.Second).
			WithTestInterval(10 * time.Second),
	}, testcontainers.PopulateHostPortEnv)

	return err
}

After calling startPostgres(), there will be 2 variables POSTGRES_5432_HOST and POSTGRES_5432_PORT. The POSTGRES is from the container name in the request, 5432 is the exposed port. The values are

• POSTGRES_5432_HOST: the hostname of the docker daemon where the container port is exposed.
• POSTGRES_5432_PORT: the port that mapped to the exposed container port.

Wait Strategies

Health Check

The health check provides the same behavior as docker-compose with the configuration:

• Start Period: Retry is only counted when time passes the start period. This is helpful for some containers that need time to get ready. The default value is 0.
• Test Timeout: Timeout for executing the test.
• Test Internal: If the container is unhealthy, the health check will wait for an amount of time before testing again.
• Retries: The number of retries to test the container after start period ends.

For example:

package example

import (
	"context"
	"time"

	"go.nhat.io/testcontainers-extra"
	"go.nhat.io/testcontainers-extra/wait"
)

func startPostgres(dbName, dbUser, dbPassword string) error {
	_, err := testcontainers.StartGenericContainer(context.Background(), testcontainers.ContainerRequest{
		Name:         "postgres",
		Image:        "postgres:12-alpine",
		ExposedPorts: []string{":5432"},
		Env: map[string]string{
			"LC_ALL":            "C.UTF-8",
			"POSTGRES_DB":       dbName,
			"POSTGRES_USER":     dbUser,
			"POSTGRES_PASSWORD": dbPassword,
		},
		WaitingFor: wait.ForHealthCheckCmd("pg_isready").
			WithRetries(3).
			WithStartPeriod(30 * time.Second).
			WithTestTimeout(5 * time.Second).
			WithTestInterval(10 * time.Second),
	})

	return err
}

Donation

If this project help you reduce time to develop, you can give me a cup of coffee :)

Paypal donation

       or scan this