Use Docker to run your Go integration tests against third party services on Windows, macOS, and Linux!

Dockertest supports running any Docker image from Docker Hub or from a Dockerfile.

• Why should I use Dockertest?
• Installation
• Quick Start
• Migration from v3
• API overview
  • Pool creation
  • Running containers
  • Container configuration
  • Container reuse
  • Getting connection info
  • Waiting for readiness
  • Executing commands
  • Container logs
  • Building from Dockerfile
  • Networks
  • Cleanup
  • Error handling
• Examples
• Troubleshoot & FAQ
  • Out of disk space
• Running in CI
  • GitHub Actions
  • GitLab CI
    • Shared runners
    • Custom (group) runners

Why should I use Dockertest?

When developing applications, it is often necessary to use services that talk to a database system. Unit testing these services can be cumbersome because mocking database/DBAL is strenuous. Making slight changes to the schema implies rewriting at least some, if not all mocks. The same goes for API changes in the DBAL.

To avoid this, it is smarter to test these specific services against a real database that is destroyed after testing. Docker is the perfect system for running integration tests as you can spin up containers in a few seconds and kill them when the test completes.

The Dockertest library provides easy to use commands for spinning up Docker containers and using them for your tests.

Installation

go get github.com/ory/dockertest/v4

Quick Start

package myapp_test
import (
"testing""time"
dockertest "github.com/ory/dockertest/v4"
)
funcTestPostgres(t*testing.T) {
pool:=dockertest.NewPoolT(t, "")
// Container is automatically reused across test runs based on "postgres:14".postgres:=pool.RunT(t, "postgres",
dockertest.WithTag("14"),
dockertest.WithEnv([]string{
"POSTGRES_PASSWORD=secret",
"POSTGRES_DB=testdb",
}),
)
hostPort:=postgres.GetHostPort("5432/tcp")
// Connect to postgres://postgres:secret@hostPort/testdb// Wait for PostgreSQL to be readyerr:=pool.Retry(t.Context(), 30*time.Second, func() error {
// try connecting...returnnil
})
iferr!=nil {
t.Fatalf("Could not connect: %v", err)
}
}

Migration from v3

Version 4 introduces automatic container reuse, making tests significantly faster by reusing containers across test runs. Additionally, a lightweight docker client is used which reduces third party dependencies significantly.

See UPGRADE.md for the complete migration guide.

API overview

View the Go API documentation.

Pool creation

// For tests - auto-cleanup with t.Cleanup()pool:=dockertest.NewPoolT(t, "")
// With optionspool:=dockertest.NewPoolT(t, "",
dockertest.WithMaxWait(2*time.Minute),
)
// With a custom Docker clientpool:=dockertest.NewPoolT(t, "",
dockertest.WithMobyClient(myClient),
)
// For non-test code - requires manual Close()ctx:=context.Background()
pool, err:=dockertest.NewPool(ctx, "")
iferr!=nil {
panic(err)
}
deferpool.Close(ctx)

Running containers

// Test helper - fails test on errorresource:=pool.RunT(t, "postgres",
dockertest.WithTag("14"),
dockertest.WithEnv([]string{"POSTGRES_PASSWORD=secret"}),
dockertest.WithCmd([]string{"postgres", "-c", "log_statement=all"}),
)
// With error handlingresource, err:=pool.Run(ctx, "postgres",
dockertest.WithTag("14"),
dockertest.WithEnv([]string{"POSTGRES_PASSWORD=secret"}),
)
iferr!=nil {
panic(err)
}

See Cleanup for container lifecycle management.

Container configuration

Customize container settings with configuration options:

resource:=pool.RunT(t, "postgres",
dockertest.WithTag("14"),
dockertest.WithUser("postgres"),
dockertest.WithWorkingDir("/var/lib/postgresql/data"),
dockertest.WithLabels(map[string]string{
"test": "integration",
"service": "database",
}),
dockertest.WithHostname("test-db"),
dockertest.WithEnv([]string{"POSTGRES_PASSWORD=secret"}),
)

Available configuration options:

• WithTag(tag string) - Set the image tag (default: "latest")
• WithEnv(env []string) - Set environment variables
• WithCmd(cmd []string) - Override the default command
• WithEntrypoint(entrypoint []string) - Override the default entrypoint
• WithUser(user string) - Set the user to run commands as (supports "user" or "user:group")
• WithWorkingDir(dir string) - Set the working directory
• WithLabels(labels map[string]string) - Add labels to the container
• WithHostname(hostname string) - Set the container hostname
• WithName(name string) - Set the container name
• WithMounts(binds []string) - Set bind mounts ("host:container" or "host:container:mode")
• WithPortBindings(bindings network.PortMap) - Set explicit port bindings
• WithReuseID(id string) - Set a custom reuse key (default: "repository:tag")
• WithoutReuse() - Disable container reuse for this run
• WithContainerConfig(modifier func(*container.Config)) - Modify the container config directly
• WithHostConfig(modifier func(*container.HostConfig)) - Modify the host config (port bindings, volumes, restart policy, memory/CPU limits)

For advanced container configuration, use WithContainerConfig:

stopTimeout:=30resource:=pool.RunT(t, "app",
dockertest.WithContainerConfig(func(cfg*container.Config) {
cfg.StopTimeout=&stopTimeoutcfg.StopSignal="SIGTERM"cfg.Healthcheck=&container.HealthConfig{
Test: []string{"CMD", "curl", "-f", "http://localhost/health"},
Interval: 10*time.Second,
Timeout: 5*time.Second,
Retries: 3,
}
}),
)

For host-level configuration, use WithHostConfig:

resource:=pool.RunT(t, "postgres",
dockertest.WithTag("14"),
dockertest.WithHostConfig(func(hc*container.HostConfig) {
hc.RestartPolicy= container.RestartPolicy{
Name: container.RestartPolicyOnFailure,
MaximumRetryCount: 3,
}
}),
)

Container reuse

Containers are automatically reused based on repository:tag. Reuse is reference-counted: each Run/RunT call increments the ref count, and each Close/cleanup decrements it. The container is only removed from Docker when the last reference is released.

// First test creates containerr1:=pool.RunT(t, "postgres", dockertest.WithTag("14"))
// Second test reuses the same containerr2:=pool.RunT(t, "postgres", dockertest.WithTag("14"))
// r1 and r2 point to the same container

Disable reuse if needed:

resource:=pool.RunT(t, "postgres",
dockertest.WithTag("14"),
dockertest.WithoutReuse(), // Always create new container
)

Getting connection info

resource:=pool.RunT(t, "postgres", dockertest.WithTag("14"))
// Get host:port (e.g., "127.0.0.1:54320")hostPort:=resource.GetHostPort("5432/tcp")
// Get just the port (e.g., "54320")port:=resource.GetPort("5432/tcp")
// Get just the IP (e.g., "127.0.0.1")ip:=resource.GetBoundIP("5432/tcp")
// Get container IDid:=resource.ID()

Waiting for readiness

Use pool.Retry to wait for a container to become ready:

err:=pool.Retry(t.Context(), 30*time.Second, func() error {
returndb.Ping()
})
iferr!=nil {
t.Fatalf("Container not ready: %v", err)
}

If timeout is 0, pool.MaxWait (default 60s) is used. The retry interval is fixed at 1 second.

For more control, use the package-level functions:

// Fixed interval retryerr:=dockertest.Retry(ctx, 30*time.Second, 500*time.Millisecond, func() error {
returndb.Ping()
})
// Exponential backoff retryerr:=dockertest.RetryWithBackoff(ctx,
30*time.Second, // timeout100*time.Millisecond, // initial interval5*time.Second, // max intervalfunc() error {
returndb.Ping()
},
)

Executing commands

Run commands inside a running container:

result, err:=resource.Exec(ctx, []string{"pg_isready", "-U", "postgres"})
iferr!=nil {
t.Fatal(err)
}
ifresult.ExitCode!=0 {
t.Fatalf("command failed: %s", result.StdErr)
}
t.Log(result.StdOut)

Container logs

// Get all logs with stdout and stderr separatedstdout, stderr, err:=resource.Logs(ctx)
iferr!=nil {
t.Fatal(err)
}
t.Log(stdout)
t.Log(stderr)
// Stream logs until container exits or ctx is cancelledvarbuf bytes.Buffererr=resource.FollowLogs(ctx, &buf, io.Discard)

Building from Dockerfile

Build a Docker image from a Dockerfile and run it:

version:="1.0.0"resource, err:=pool.BuildAndRun(ctx, "myapp:test",
&dockertest.BuildOptions{
ContextDir: "./testdata",
Dockerfile: "Dockerfile.test",
BuildArgs: map[string]*string{"VERSION": &version},
},
dockertest.WithEnv([]string{"APP_ENV=test"}),
)
iferr!=nil {
t.Fatal(err)
}

BuildAndRunT is the test helper variant:

resource:=pool.BuildAndRunT(t, "myapp:test",
&dockertest.BuildOptions{
ContextDir: "./testdata",
},
)

Networks

Create Docker networks for container-to-container communication:

net:=pool.CreateNetworkT(t, "my-network", nil)
// Connect a containererr:=resource.ConnectToNetwork(ctx, net)
// Get the container's IP in the networkip:=resource.GetIPInNetwork(net)
// Disconnecterr:=resource.DisconnectFromNetwork(ctx, net)

With custom options:

net, err:=pool.CreateNetwork(ctx, "my-network", &dockertest.NetworkCreateOptions{
Driver: "bridge",
Internal: true,
})

Cleanup

NewPoolT + RunT (recommended): Cleanup is fully automatic. RunT registers cleanup via t.Cleanup, and the pool is closed when the test finishes. Nothing to do.

funcTestDB(t*testing.T) {
pool:=dockertest.NewPoolT(t, "")
resource:=pool.RunT(t, "postgres", dockertest.WithTag("14"))
// Use resource... cleanup happens automatically when t finishes.
}

NewPool + Run: Call resource.Close(ctx) to release individual containers, or pool.Close(ctx) to release everything:

ctx:=context.Background()
pool, err:=dockertest.NewPool(ctx, "")
iferr!=nil {
panic(err)
}
deferpool.Close(ctx) // releases all tracked containers and networksresource, err:=pool.Run(ctx, "postgres", dockertest.WithTag("14"))
iferr!=nil {
panic(err)
}
deferresource.Close(ctx) // or let pool.Close handle it

Advanced: shared pool in TestMain: Use this when you need a single pool shared across all tests in a package:

funcTestMain(m*testing.M) {
ctx:=context.Background()
pool, _:=dockertest.NewPool(ctx, "")
code:=m.Run()
pool.Close(ctx)
os.Exit(code)
}

Error handling

resource, err:=pool.Run(ctx, "postgres", dockertest.WithTag("14"))
iferrors.Is(err, dockertest.ErrImagePullFailed) {
// Image could not be pulled
}
iferrors.Is(err, dockertest.ErrContainerCreateFailed) {
// Container creation failed
}
iferrors.Is(err, dockertest.ErrContainerStartFailed) {
// Container start failed
}
iferrors.Is(err, dockertest.ErrClientClosed) {
// Pool or client has been closed
}

Examples

See the examples directory for complete examples.

Troubleshoot & FAQ

Out of disk space

Try cleaning up unused containers, images, and volumes:

docker system prune -f

Running in CI

GitHub Actions

Docker is available by default on GitHub Actions ubuntu-latest runners, so no extra services are needed:

name: Test with Dockeron: [push]jobs:
test:
runs-on: ubuntu-lateststeps:
- uses: actions/checkout@v4
- uses: actions/setup-go@v5with:
go-version: "1.24"
- run: go test -v ./...

GitLab CI

Shared runners

Add the Docker dind service to your job which starts in a sibling container. The database will be available on host docker. Your app should be able to change the database host through an environment variable.

stages:
- testgo-test:
stage: testimage: golang:1.24services:
- docker:dindvariables:
DOCKER_HOST: tcp://docker:2375DOCKER_DRIVER: overlay2DOCKER_TLS_CERTDIR: ""YOUR_APP_DB_HOST: dockerscript:
- go test ./...

In your pool.Retry callback, use $YOUR_APP_DB_HOST instead of localhost when connecting to the database.

Custom (group) runners

GitLab runner can be run in docker executor mode to save compatibility with shared runners:

gitlab-runner register -n \
--url https://gitlab.com/ \
--registration-token $YOUR_TOKEN \
--executor docker \
--description "My Docker Runner" \
--docker-image "docker:27" \
--docker-privileged

The DOCKER_TLS_CERTDIR: "" variable in the example above tells the Docker daemon to start on port 2375 over HTTP (TLS disabled).