Documentation
¶
Overview ¶
Package dockertest provides Docker container orchestration for Go testing.
Dockertest v4 uses the official github.com/moby/moby/client and provides a modern, context-aware API with automatic container reuse for fast tests.
Quick Start ¶
func TestDatabase(t *testing.T) {
pool := dockertest.NewPoolT(t, "")
db := pool.RunT(t, "postgres",
dockertest.WithTag("14"),
dockertest.WithEnv([]string{"POSTGRES_PASSWORD=secret"}),
)
db.Cleanup(t)
hostPort := db.GetHostPort("5432/tcp")
connStr := fmt.Sprintf("postgres://postgres:secret@%s/postgres?sslmode=disable", hostPort)
err := pool.Retry(t.Context(), 30*time.Second, func() error {
conn, err := sql.Open("postgres", connStr)
if err != nil {
return err
}
defer conn.Close()
return conn.Ping()
})
if err != nil {
t.Fatalf("Database not ready: %v", err)
}
}
Features ¶
- Container reuse: Containers are reused by default based on repository:tag for 2-3x faster tests - Context support: All operations accept context.Context for cancellation and timeouts - Test helpers: *T methods use t.Context() and t.Cleanup() for simplified test lifecycle - Networks: Create networks for container-to-container communication - Custom images: Build and run custom Docker images from Dockerfiles
See https://github.com/ory/dockertest for more examples and documentation.
Index ¶
- Variables
- func Register(reuseID string, r ClosableResource) error
- func ResetRegistry()
- func Retry(ctx context.Context, timeout, interval time.Duration, fn func() error) error
- func RetryWithBackoff(ctx context.Context, timeout, initialInterval, maxInterval time.Duration, ...) error
- func TestMain(ctx context.Context, m *testing.M, opts ...TestMainOption)
- type BuildOptions
- type ClosableNetwork
- type ClosablePool
- type ClosableResource
- type ExecResult
- type Network
- type NetworkCreateOptions
- type Pool
- type PoolOption
- type Resource
- type RunFunc
- type RunOption
- func WithCmd(cmd []string) RunOption
- func WithContainerConfig(modifier func(*container.Config)) RunOption
- func WithEntrypoint(entrypoint []string) RunOption
- func WithEnv(env []string) RunOption
- func WithHostConfig(modifier func(*container.HostConfig)) RunOption
- func WithHostname(hostname string) RunOption
- func WithLabels(labels map[string]string) RunOption
- func WithMounts(binds []string) RunOption
- func WithName(name string) RunOption
- func WithPortBindings(bindings network.PortMap) RunOption
- func WithReuseID(id string) RunOption
- func WithTag(tag string) RunOption
- func WithUser(user string) RunOption
- func WithWorkingDir(dir string) RunOption
- func WithoutReuse() RunOption
- type TestMainOption
- type TestingTB
Constants ¶
This section is empty.
Variables ¶
var ErrClientClosed = errors.New("client is closed")
ErrClientClosed is returned when an operation is attempted on a resource whose pool or client has already been closed.
var ErrContainerCreateFailed = errors.New("container creation failed")
ErrContainerCreateFailed is returned when container creation fails.
var ErrContainerStartFailed = errors.New("container start failed")
ErrContainerStartFailed is returned when starting a container fails.
var ErrImageBuildFailed = errors.New("image build failed")
ErrImageBuildFailed is returned when building a Docker image fails.
var ErrImagePullFailed = errors.New("image pull failed")
ErrImagePullFailed is returned when pulling a Docker image fails.
var ErrInvalidOption = errors.New("invalid option")
ErrInvalidOption is returned for invalid pool, build, TestMain, or Wrap options.
var ErrShuttingDown = errors.New("dockertest is shutting down")
ErrShuttingDown is returned when a new Docker resource is requested after TestMain or Wrap has started process shutdown.
Functions ¶
func Register ¶
func Register(reuseID string, r ClosableResource) error
Register stores a resource with the given reuseID in the global registry.
If a resource with the same reuseID already exists, the existing resource is kept and no error is returned. This ensures that concurrent registration attempts result in exactly one resource being stored. The race winner's resource becomes the canonical one in the registry, which is safe because both resources represent containers with the same configuration (same image, tag, env, etc.).
The global registry enables container reuse across tests. Containers registered here can be retrieved with Get.
Note: This function is called automatically by Pool.Run when container reuse is enabled. You typically don't need to call it directly.
func ResetRegistry ¶
func ResetRegistry()
ResetRegistry clears all resources from the global registry. This does NOT stop or remove the containers themselves.
func Retry ¶
Retry retries fn with a fixed interval until it succeeds, the context is cancelled, or the timeout is reached. The interval is deterministic (no jitter).
func RetryWithBackoff ¶
func RetryWithBackoff(ctx context.Context, timeout, initialInterval, maxInterval time.Duration, fn func() error) error
RetryWithBackoff retries fn with exponential backoff until it succeeds, the context is cancelled, or the timeout is reached.
The interval starts at initialInterval and doubles after each attempt, capped at maxInterval. The backoff is deterministic (no jitter).
func TestMain ¶ added in v4.0.1
func TestMain(ctx context.Context, m *testing.M, opts ...TestMainOption)
TestMain runs the tests of a package and cleans up its owned Docker resources, even when a test hangs or the process is interrupted. Images, builder cache, named volumes, and pre-existing unlabeled resources are outside automatic cleanup. Use it from the package's TestMain:
func TestMain(m *testing.M) {
dockertest.TestMain(context.Background(), m)
}
TestMain owns process exit and never returns. It calls m.Run on the calling goroutine and exits with its status after cleanup; cleanup failures are printed to stderr but do not change the status. On SIGINT or SIGTERM, shutdown starts even if m.Run is stuck, and the process exits with 130 or 143 after cleanup. After the first signal the default signal behavior is restored, so a second signal terminates the process immediately.
Pools may be constructed before TestMain as long as they have created no Docker resources. Invalid options or a repeated TestMain or Wrap exit with status 1 before any test runs.
Containers and networks are labeled with an expiry derived from -test.timeout: once it has passed, go test has killed the process. At shutdown, TestMain also removes expired resources that earlier runs left behind on the daemons it used, for example after a kill or a power loss. With -test.timeout=0, -test.bench, or -test.fuzz resources get no expiry and are never removed by other runs.
Use Wrap to compose with other TestMain helpers or to keep control of the exit status.
Types ¶
type BuildOptions ¶
type BuildOptions struct {
// Dockerfile is the name of the Dockerfile within the ContextDir.
// Defaults to "Dockerfile" if empty.
Dockerfile string
// ContextDir is the directory containing the Dockerfile and build context.
// This directory will be archived and sent to the Docker daemon.
// REQUIRED - build will fail if empty.
ContextDir string
// Tags are the tags to apply to the built image.
// If empty, the image name from BuildAndRun will be used.
Tags []string
// BuildArgs are build-time variables passed to the Dockerfile.
// Use pointers to distinguish between empty string and unset.
// Example: map[string]*string{"VERSION": &versionStr}
BuildArgs map[string]*string
// Labels are metadata to apply to the built image.
// Example: map[string]string{"version": "1.0", "env": "test"}
Labels map[string]string
// NoCache disables build cache when set to true.
// Useful for ensuring a clean build.
NoCache bool
// ForceRemove always removes intermediate containers, even on build failure.
// It does not remove intermediate images or builder cache.
ForceRemove bool
// Version specifies the builder to use. "1" for classic, "2" for BuildKit.
// Defaults to the daemon's configured default if empty.
Version string
}
BuildOptions configures image building from a Dockerfile. Use with Pool.BuildAndRun to build and run custom Docker images.
Only ContextDir is required. All other fields are optional and have sensible defaults. Built images and builder cache are not automatically removed.
type ClosableNetwork ¶
ClosableNetwork extends Network with explicit lifecycle management. Returned by CreateNetwork; the caller is responsible for calling Close.
type ClosablePool ¶
ClosablePool extends Pool with explicit lifecycle management. Returned by NewPool; the caller is responsible for calling Close.
func NewPool ¶
func NewPool(ctx context.Context, endpoint string, opts ...PoolOption) (ClosablePool, error)
NewPool creates a new pool with the given endpoint and options.
The endpoint parameter must be empty. The Docker client is created from environment variables (DOCKER_HOST, DOCKER_TLS_VERIFY, DOCKER_CERT_PATH) or provided via WithMobyClient option.
The default maxWait is 60 seconds. This can be customized with WithMaxWait.
Example:
ctx := context.Background()
pool, err := dockertest.NewPool(ctx, "")
if err != nil {
panic(err)
}
defer pool.Close(ctx)
type ClosableResource ¶
type ClosableResource interface {
Resource
Close(ctx context.Context) error
CloseT(t TestingTB)
Cleanup(t TestingTB)
}
ClosableResource extends Resource with explicit lifecycle management. Returned by Run and BuildAndRun; the caller is responsible for calling Close.
func Get ¶
func Get(reuseID string) (ClosableResource, bool)
Get retrieves a resource from the global registry by reuseID. Returns the resource and true if found, nil and false otherwise.
The global registry stores containers for reuse. By default, containers are registered with a reuseID of "repository:tag".
Note: This function is called automatically by Pool.Run when checking for existing containers. You typically don't need to call it directly.
func GetAll ¶
func GetAll() []ClosableResource
GetAll returns a slice of all resources in the global registry. The order of resources in the returned slice is not guaranteed.
The registry only contains reusable containers that are currently referenced; it is not an inventory of everything dockertest created. Use TestMain for process-wide cleanup.
func NewResource ¶
func NewResource(c container.InspectResponse) ClosableResource
NewResource creates a Resource for testing purposes. This is intended for unit tests that need a Resource without a Docker container.
type ExecResult ¶
ExecResult holds the output of a command executed inside a container.
type Network ¶
type Network interface {
ID() string
Inspect() mobynetwork.Inspect
}
Network provides access to a Docker network. Returned by CreateNetworkT; does not expose Close or CloseT.
type NetworkCreateOptions ¶
type NetworkCreateOptions struct {
Driver string // Network driver (e.g., "bridge", "overlay")
Labels map[string]string // User-defined metadata
Options map[string]string // Driver-specific options
Internal bool // Restrict external access to the network
Attachable bool // Enable manual container attachment
Ingress bool // Create an ingress network (swarm mode)
EnableIPv6 bool // Enable IPv6 networking
}
NetworkCreateOptions holds options for creating a network. This is a subset of mobyclient.NetworkCreateOptions from github.com/moby/moby/client to provide a simpler API while allowing common customizations.
All fields are optional. If not specified, Docker's defaults are used:
- Driver defaults to "bridge"
- Internal defaults to false (network has external access)
- Attachable defaults to false
- EnableIPv6 defaults to false
type Pool ¶
type Pool interface {
Run(ctx context.Context, repository string, opts ...RunOption) (ClosableResource, error)
RunT(t TestingTB, repository string, opts ...RunOption) Resource
BuildAndRun(ctx context.Context, name string, buildOpts *BuildOptions, runOpts ...RunOption) (ClosableResource, error)
BuildAndRunT(t TestingTB, name string, buildOpts *BuildOptions, runOpts ...RunOption) Resource
CreateNetwork(ctx context.Context, name string, opts *NetworkCreateOptions) (ClosableNetwork, error)
CreateNetworkT(t TestingTB, name string, opts *NetworkCreateOptions) Network
Retry(ctx context.Context, timeout time.Duration, fn func() error) error
Client() client.DockerClient
}
Pool is the interface for managing Docker resources in tests. Returned by NewPoolT; does not expose Close or CloseT.
type PoolOption ¶
type PoolOption func(*pool)
PoolOption is a functional option for configuring a pool. Use with NewPool or NewPoolT to customize pool behavior.
func WithCleanupTimeout ¶ added in v4.0.1
func WithCleanupTimeout(timeout time.Duration) PoolOption
WithCleanupTimeout sets the context deadline for removing the pool's resources, both in Close and in automatic cleanup registered with t.Cleanup. An earlier deadline of the caller's context is kept. The default is 60 seconds; NewPool rejects a timeout that is not positive.
func WithMaxWait ¶
func WithMaxWait(d time.Duration) PoolOption
WithMaxWait sets the maximum wait time for operations. The default maxWait is 60 seconds.
func WithMobyClient ¶
func WithMobyClient(c client.DockerClient) PoolOption
WithMobyClient sets a custom Docker client. When a custom client is provided, the pool will not close it on Close().
type Resource ¶
type Resource interface {
ID() string
Container() container.InspectResponse
GetPort(portID string) string
GetBoundIP(portID string) string
GetHostPort(portID string) string
Logs(ctx context.Context) (stdout, stderr string, err error)
FollowLogs(ctx context.Context, stdout, stderr io.Writer) error
Exec(ctx context.Context, cmd []string) (ExecResult, error)
ConnectToNetwork(ctx context.Context, net Network) error
DisconnectFromNetwork(ctx context.Context, net Network) error
GetIPInNetwork(net Network) string
}
Resource provides access to a Docker container. Returned by *T variants; does not expose Close, CloseT, or Cleanup.
type RunFunc ¶ added in v4.0.1
type RunFunc func() int
RunFunc runs tests and returns their exit code. It satisfies goleak.TestingM.
func Wrap ¶ added in v4.0.1
func Wrap(ctx context.Context, run func() int, opts ...TestMainOption) RunFunc
Wrap returns run wrapped in the cleanup of TestMain, for a TestMain that composes with other helpers or keeps control of its exit status:
func TestMain(m *testing.M) {
goleak.VerifyTestMain(dockertest.Wrap(context.Background(), m.Run))
}
The returned Run installs the cleanup, calls run, shuts down as TestMain does, and returns the status of run. Invalid options, a repeated TestMain or Wrap, or resources created earlier are printed to stderr and return 1 without calling run. Cleanup failures are printed but do not change the status. Before Run returns, signal handling has stopped and the Docker clients pools created are closed, so leak checks after it see no dockertest goroutines. Signals and expiry labels behave as under TestMain.
type RunOption ¶
type RunOption func(*runConfig) error
RunOption configures container creation. Use with Pool.Run or Pool.RunT to customize how containers are started.
func WithContainerConfig ¶
WithContainerConfig allows direct modification of the container.Config. This is useful for advanced options not covered by other WithXxx functions. The modifier is applied after all other options are processed.
func WithEntrypoint ¶
WithEntrypoint sets the container entrypoint, overriding the image's default ENTRYPOINT.
func WithEnv ¶
WithEnv sets environment variables for the container. Each string should be in "KEY=value" format.
func WithHostConfig ¶
func WithHostConfig(modifier func(*container.HostConfig)) RunOption
WithHostConfig allows direct modification of the container.HostConfig. Use this to set host-level options like port bindings, volume mounts, restart policies, memory/CPU limits, or AutoRemove. The modifier is applied after the default HostConfig is constructed.
func WithHostname ¶
WithHostname sets the container's hostname.
func WithLabels ¶
WithLabels sets labels on the container. Labels are useful for marking test containers or adding metadata.
func WithMounts ¶
WithMounts sets bind mounts for the container. Each string should be in "host:container" or "host:container:mode" format.
func WithPortBindings ¶
WithPortBindings sets explicit port bindings for the container. Use network.PortMap to specify the bindings.
func WithReuseID ¶
WithReuseID sets a custom reuse ID for container reuse. By default, containers are reused based on "repository:tag".
func WithUser ¶
WithUser sets the user that will run commands inside the container. Supports both "user" and "user:group" formats.
func WithWorkingDir ¶
WithWorkingDir sets the working directory for commands run in the container.
func WithoutReuse ¶
func WithoutReuse() RunOption
WithoutReuse disables container reuse for this run. A new container will be created every time.
type TestMainOption ¶ added in v4.0.1
type TestMainOption func(*mainOptions)
TestMainOption configures TestMain and Wrap.
func WithShutdownTimeout ¶ added in v4.0.1
func WithShutdownTimeout(d time.Duration) TestMainOption
WithShutdownTimeout sets the deadline of the whole shutdown, including the teardown set with WithTeardown. Shutdown ends shortly after it even if a teardown or client ignores its context. Defaults to 60 seconds; negative values are rejected.
func WithTeardown ¶ added in v4.0.1
func WithTeardown(fn func(context.Context) error) TestMainOption
WithTeardown sets a package teardown that runs once, before Docker resources are removed, under the shutdown deadline. Its error is reported but does not change the exit status.
It is not needed for pools, containers, and networks created through dockertest: shutdown removes them and closes the Docker clients pools created. Use it only for state dockertest does not own.
type TestingTB ¶
type TestingTB interface {
Helper()
Context() context.Context
Cleanup(func())
Logf(format string, args ...any)
Fatalf(format string, args ...any)
}
TestingTB is a subset of testing.TB for dependency injection. This interface allows methods to work with test helpers without directly depending on the testing package.
