Use Docker to run your Go language integration tests against third party services on Microsoft Windows, Mac OSX and Linux! Dockertest uses Docker to spin up images on Windows and Mac OSX.

Dockertest supports running any Docker Image from Docker Hub and Dockerfile.

Table of Contents

• Why should I use Dockertest?
• Installing and using Dockertest v4
  • Installation
  • Quick Start
  • Key Features
  • Examples
• Upgrading from v3 to v4
  • Breaking Changes
  • Migration Examples
  • Common Patterns
• Using Dockertest v3 (Legacy)
• Troubleshoot & FAQ
  • Out of disk space
  • Removing old containers
• Running in CI
  • GitHub Actions
  • GitLab CI
  • Remote Docker

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 rewriting at least some, if not all mocks. The same goes for API changes in the database/DBAL is strenuous. Making slight changes to the schema implies 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.

[!WARNING]

Dockertest v4 is not yet finalized and may still receive breaking changes before the stable release.

Installation

go get github.com/ory/dockertest/v4

Quick Start

package myapp_test

import (
    "context"
    "os"
    "testing"

    dockertest "github.com/ory/dockertest/v4"
)

func TestPostgres(t *testing.T) {
    pool := dockertest.NewPoolT(t, "")

    db := pool.RunT(t, "postgres",
        dockertest.WithTag("14"),
        dockertest.WithEnv([]string{
            "POSTGRES_PASSWORD=secret",
            "POSTGRES_DB=testdb",
        }),
    )
    db.Cleanup(t)

    // Use db.GetHostPort("5432/tcp") to connect
    hostPort := db.GetHostPort("5432/tcp")
    // Connect to postgres://postgres:secret@hostPort/testdb
}

func TestMain(m *testing.M) {
    // Note: TestMain doesn't have testing.T, so we create a context here
    // In regular tests, always use t.Context() instead
    ctx := context.Background()
    pool, _ := dockertest.NewPool(ctx, "")
    code := m.Run()
    // Clean up before os.Exit — deferred functions do not run after os.Exit.
    pool.Cleanup(ctx)
    pool.Close()
    os.Exit(code)
}

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 options
pool := dockertest.NewPoolT(t, "",
    dockertest.WithMaxWait(2*time.Minute),
)

// For non-test code - requires manual Close()
ctx := context.Background()
pool, err := dockertest.NewPool(ctx, "")
if err != nil {
    panic(err)
}
defer pool.Close()

Running containers

// Test helper - fails test on error
resource := pool.RunT(t, "postgres",
    dockertest.WithTag("14"),
    dockertest.WithEnv([]string{"POSTGRES_PASSWORD=secret"}),
    dockertest.WithCmd([]string{"postgres", "-c", "log_statement=all"}),
)

// With error handling
resource, err := pool.Run(ctx, "postgres",
    dockertest.WithTag("14"),
    dockertest.WithEnv([]string{"POSTGRES_PASSWORD=secret"}),
)
if err != nil {
    panic(err)
}

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:

• 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
• WithEnv(env []string) - Set environment variables
• WithCmd(cmd []string) - Override the default command
• WithEntrypoint(entrypoint []string) - Override the default entrypoint
• WithHostConfig(modifier func(*container.HostConfig)) - Modify the host config (port bindings, volumes, restart policy, memory/CPU limits)

For advanced container configuration, use WithContainerConfig:

stopTimeout := 30
resource := pool.RunT(t, "app",
    dockertest.WithContainerConfig(func(cfg *container.Config) {
        cfg.StopTimeout = &stopTimeout
        cfg.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

[!WARNING]

Do not use resource.Cleanup(t) on reused containers. Because reused containers are shared across tests, cleaning up one reference will remove the container for all other tests that depend on it. Only use pool.Cleanup(ctx) in TestMain to clean up reused containers after all tests have finished.

Containers are automatically reused based on repository:tag:

// First test creates container
r1 := pool.RunT(t, "postgres", dockertest.WithTag("14"))

// Second test reuses the same container (2-3x faster)
r2 := 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 ID
id := resource.ID()

Executing commands

Run commands inside a running container:

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

Cleanup

// In tests - cleanup when test finishes
resource.Cleanup(t)

// Manual cleanup
err := resource.Close(ctx)

// Test helper - fails test on error
resource.CloseT(t)

// Cleanup all containers (in TestMain)
pool.Cleanup(ctx)

Error Handling

resource, err := pool.Run(ctx, "postgres", dockertest.WithTag("14"))
if errors.Is(err, dockertest.ErrImagePullFailed) {
    // Image could not be pulled
}
if errors.Is(err, dockertest.ErrContainerCreateFailed) {
    // Container creation failed
}
if errors.Is(err, dockertest.ErrContainerStartFailed) {
    // Container start failed
}

Examples

See the examples directory for complete examples.

Troubleshoot & FAQ

Out of disk space

Try cleaning up the images with docker-cleanup-volumes.

Running dockertest in Gitlab CI

How to run dockertest on shared gitlab runners?

You should add docker dind service to your job which starts in sibling container. That means database will be available on host docker.
You app should be able to change db host through environment variable.

Here is the simple example of gitlab-ci.yml:

stages:
  - test
go-test:
  stage: test
  image: golang:1.15
  services:
    - docker:dind
  variables:
    DOCKER_HOST: tcp://docker:2375
    DOCKER_DRIVER: overlay2
    YOUR_APP_DB_HOST: docker
  script:
    - go test ./...

Plus in the pool.Retry method that checks for connection readiness, you need to use $YOUR_APP_DB_HOST instead of localhost.

How to run dockertest on group(custom) gitlab runners?

Gitlab runner can be run in docker executor mode to save compatibility with shared runners.
Here is the simple register command:

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

You only need to instruct docker dind to start with disabled tls.
Add variable DOCKER_TLS_CERTDIR: "" to gitlab-ci.yml above. It will tell docker daemon to start on 2375 port over http.

Running Dockertest using GitHub actions

name: Test with Docker

on: [push]

jobs:
  test:
    runs-on: ubuntu-latest
    services:
      dind:
        image: docker:23.0-rc-dind-rootless
        ports:
          - 2375:2375
    steps:
      - name: Checkout code
        uses: actions/checkout@v2

      - name: Set up Go
        uses: actions/setup-go@v4
        with:
          go-version: "1.21"

      - name: Test with Docker
        run: go test -v ./...