docker

go-docker-testsuite

Go library to run third-party dependencies in Docker containers for integration testing. Spin up any Docker image — databases, queues, caches, or object storage — and connect to them via network from your Go tests.

Features

• Container — low-level wrapper to create, run, await output, and clean up any Docker image
• Group — run multiple containers in an isolated Docker network with IP-level connectivity
• Applications — ready-to-use wrappers for popular services (MySQL, PostgreSQL, Redis, Kafka, etc.)
• Hooks — lifecycle callbacks (BeforeRun, AfterRun, BeforeClose, AfterClose) per container
• Exec — run commands inside a running container and capture stdout, stderr, and the exit code
• Lifecycle commands — run startup / after-ready commands via exec (WithStartupCommand, WithAfterReadyCommand)
• Copy files into containers — seed files before start with WithFiles (FileFromBytes for small content, or stream large files via io.Reader + Size)
• Copy files out of containers — read a file/directory back out of a running container as a tar stream with docker.CopyFromContainer (inverse of WithFiles)
• Resource limits — cap CPU/memory/pids to protect the host and CI (WithMemoryLimit, WithCPUs, WithPidsLimit, ...)
• Matchers — await container logs with substring, exact, or regexp matchers before proceeding
• Wait strategies — composable readiness probes beyond log matchers: ForLog, ForHTTPGet, ForCommand, ForTCPConnection, combined with ForAll / ForAny / ForAtLeast (github.com/teran/go-docker-testsuite/wait)
• Environment builder — fluent DSL to declare typed environment variables
• Port bindings — DNAT port mapping with random or one-to-one port allocation
• Network mode — run a container on the host or a custom network (WithNetworkMode(NetworkModeHost), WithHostNetwork())
• IMAGE_PREFIX — optional IMAGE_PREFIX env var to route images through a proxy/mirror
• *testing.T binding — bind a container/group to a test for automatic teardown (t.Cleanup) and t.Logf lifecycle logging, with safe t.Parallel()

Requirements

• Go 1.26+ (uses go.1.26.0 directive in go.mod)
• A running Docker daemon (also works with remote Docker hosts via DOCKER_HOST, etc.)

Installation

The repository is a multi-module workspace: the root is the core module and each application under applications/<name> is its own Go module. Pull only what you need — the core, and any application wrapper — instead of dragging every database/queue client dependency into your go.mod:

# The core (Container, Group, wait, images, ...):
go get github.com/teran/go-docker-testsuite

# A specific application wrapper (own module, own version):
go get github.com/teran/go-docker-testsuite/applications/redis
go get github.com/teran/go-docker-testsuite/applications/postgres

go get .../applications/<name>@latest resolves the application's most recent tagged version (applications/<name>/v...) and transitively pulls the core at the version the application requires. See Modules & releases.

Applications

The test suite provides ready-to-use wrappers (each returns a typed client interface and handles startup, health checks, and cleanup). Several wrappers (PostgreSQL, OpenSearch, nginx, Redis, MySQL, MongoDB, Forgejo) use the wait package internally to poll for readiness. Here's the full list:

Ceph image: the Ceph wrapper runs the multi-arch demo image ghcr.io/teran/ceph-container/ceph:v<version> (built for the squid and tentacle release trains). It is built and published independently from github.com/teran/ceph-container. Use a specific version (e.g. ceph.NewWithImage(ctx, "ghcr.io/teran/ceph-container/ceph:v20.2.4")) when the default (images.Ceph) isn't the one you need.

Many application packages include testable Examples (Example* functions in *_test.go files) that demonstrate real usage. They are displayed on pkg.go.dev and can be verified locally:

# Run all examples (requires a running Docker daemon):
go test -run Example ./applications/... .

# Run a specific example:
go test -run "^Example$" ./applications/mysql/

Usage

Quick start — MySQL

package main

import (
    "context"
    "database/sql"
    "time"

    _ "github.com/go-sql-driver/mysql"

    "github.com/teran/go-docker-testsuite/applications/mysql"
)

func main() {
    ctx, cancel := context.WithTimeout(context.Background(), 2*time.Minute)
    defer cancel()

    app, err := mysql.New(ctx, "index.docker.io/library/mysql:8.0.4")
    if err != nil {
        panic(err)
    }
    defer app.Close(ctx)

    if err := app.CreateDB(ctx, "important_database"); err != nil {
        panic(err)
    }

    db, err := sql.Open("mysql", app.MustDSN("important_database"))
    if err != nil {
        panic(err)
    }
    defer db.Close()

    if _, err := db.ExecContext(ctx, "SELECT 1"); err != nil {
        panic(err)
    }
}

Multi-container group

Use docker.Group to run several containers in an isolated Docker network with internal DNS resolution:

package main

import (
    "context"
    "time"

    "github.com/teran/go-docker-testsuite"
    "github.com/teran/go-docker-testsuite/wait"
)

func main() {
    ctx, cancel := context.WithTimeout(context.Background(), 2*time.Minute)
    defer cancel()

    app := docker.NewApplication(
        c,
        docker.HookFunc(func(ctx context.Context, ht docker.HookType, c docker.Container) error {
            // e.g. wait for readiness before moving on
            return wait.Wait(ctx, c, wait.ForLog(docker.NewSubstringMatcher("ready")))
        }),
    )

    g, err := docker.NewGroup("my-services", app1, app2)
    if err != nil {
        panic(err)
    }

    if err := g.Run(ctx); err != nil {
        panic(err)
    }
    defer g.Close(ctx)
}

Wait strategies

wait.Wait(ctx, target, strategy, opts...) polls a container until a composable readiness strategy reports ready, returning nil on success or a wrapped error on timeout or a fatal condition. Both docker.Container and docker.TestContainer satisfy the wait.Target interface directly:

// Wait until the app's HTTP /health endpoint returns 200.
if err := wait.Wait(ctx, c, wait.ForHTTPGet(8080,
    wait.WithPath("/health"),
    wait.WithResponseStatuses(200),
)); err != nil {
    panic(err)
}

Other strategies: ForLog(matcher) (log-line match), ForCommand(cmd) (run a command in-container), and ForTCPConnection(port) (pure TCP liveness probe). Combine several with ForAll / ForAny / ForAtLeast, and tune polling with WithTimeout / WithInterval. These probes run against real containers, so they require a running Docker daemon.

*testing.T binding & t.Parallel()

Bind a container (or group) to a *testing.T so its lifecycle follows the test automatically — no manual defer c.Close. TestContainer wraps a Container and registers a t.Cleanup handler on the first Run, so the container is always stopped and removed when the test finishes, whether it succeeds, calls t.Fatal, panics, or skips. Cleanup handlers run in LIFO order within the test's context. TestContainer implements the full Container interface, so it can be used anywhere a Container is expected.

func TestRedis(t *testing.T) {
    t.Parallel()

    c, err := docker.NewContainerWithT(
        t,
        "redis",
        images.Redis,
        nil,
        docker.NewEnvironment(),
        docker.NewPortBindings().PortDNAT(docker.ProtoTCP, 6379),
    )
    if err != nil {
        t.Fatal(err)
    }

    c.RunT(ctx) // fail-fast; registers t.Cleanup

    // ... use container ... // no manual defer; cleanup on success/fatal/panic/skip
}

Two ways to start a bound container:

• Run(ctx) error — returns the error (and logs it via t.Logf) rather than failing the test. This keeps TestContainer compatible with applications, groups, and existing code that expects the Container contract.
• RunT(ctx) — fail-fast: if the container fails to start, the test is failed immediately with t.Fatal. Prefer this in tests.

To wrap an existing container or group (created with the base NewContainer/NewContainerWithLifecycle/NewGroup constructors) use BindToT(t, c) or BindGroupToT(t, g):

c, err := docker.NewContainer("my-service", "busybox:latest", nil, nil, nil)
if err != nil {
    t.Fatal(err)
}

docker.BindToT(t, c) // lifecycle now tied to the test
_ = c.Run(ctx)

Application packages expose T-bound constructors that create the container and start it, all tied to the test. Following the standard four-constructor contract (see SPEC → "Constructor contract"), wrappers with a default image expose NewWithT(t, ctx) and NewWithImageT(t, ctx, image) (e.g. applications/postgres, applications/mongodb), while the legacy mysql/redis/vault packages keep NewWithT(t, ctx, image) for backward compatibility.

Safe t.Parallel(). Each binding owns its own lifecycle: cleanups are registered against the correct per-test *testing.T and run in that test's context, so parallel tests do not interfere with one another's teardown. To avoid collisions, container/network names and host ports are randomized per container, so concurrent tests do not clash. Keep the parallel fan-out modest and combine t.Parallel() with resource limits (WithMemoryLimit, WithCPUs, WithPidsLimit) to protect the host and CI runners.

Lifecycle hooks

Every container supports hooks at four stages:

docker.HookTypeBeforeRun   // before container starts
docker.HookTypeAfterRun    // after container starts
docker.HookTypeBeforeClose // before container stops
docker.HookTypeAfterClose  // after container stops

Pass hooks via docker.NewApplication(container, hook1, hook2, ...).

Exec and lifecycle commands

Run a command inside a running container with Container.Exec and inspect its output and exit code:

res, err := c.Exec(ctx, []string{"echo", "hello"})
if err != nil {
    // infrastructure failure (create/attach/inspect or ctx cancelled)
    panic(err)
}

if err := res.Error(); err != nil {
    // non-zero exit code (res.ExitCode, res.Stderr available for diagnostics)
    panic(err)
}

fmt.Printf("exit code: %d\n", res.ExitCode)
fmt.Printf("stdout: %s", res.Stdout)

To run initialization commands automatically, use NewContainerWithLifecycle together with WithStartupCommand (executed right after the container starts) and WithAfterReadyCommand (executed once a readiness log line appears):

c, err := docker.NewContainerWithLifecycle(
    "my-service",
    "busybox:latest",
    []string{"sh", "-c", "echo READY; sleep 300"},
    nil,
    nil,
    docker.WithStartupCommand("sh", "-c", "echo boot > /tmp/startup.txt"),
    docker.WithAfterReadyCommand(
        docker.NewSubstringMatcher("READY"),
        "sh", "-c", "echo seeded > /tmp/seeded.txt",
    ),
)
if err != nil {
    panic(err)
}
defer c.Close(ctx)

if err := c.Run(ctx); err != nil {
    panic(err)
}

For host/CI protection, cap resource usage with the With* options (see SPEC.md → "Resource limits"):

c, err := docker.NewContainer(
    "my-service",
    "busybox:latest",
    []string{"sleep", "300"},
    nil,
    nil,
    docker.WithMemoryLimit(128*1024*1024), // 128 MiB
    docker.WithCPUs(0.5),                  // half a vCPU
    docker.WithPidsLimit(256),
)

Copying files into the container (WithFiles)

Seed files into the container filesystem before it starts with WithFiles. Files are packed into a tar and pushed via the Docker SDK CopyToContainer before WithStartupCommand runs, so both the image entrypoint and startup commands can consume them. WithFiles is a LifecycleOption, so it is used through NewContainerWithLifecycle.

For small in-memory config, use the FileFromBytes helper:

c, err := docker.NewContainerWithLifecycle(
    "my-service",
    "busybox:latest",
    []string{"sleep", "300"},
    nil,
    nil,
    docker.WithFiles(
        docker.FileFromBytes("/etc/app.conf", []byte("key=value\n"), 0600, 0, 0),
    ),
)
if err != nil {
    panic(err)
}
defer c.Close(ctx)

if err := c.Run(ctx); err != nil {
    panic(err)
}

For files larger than available RAM, pass an io.Reader and its exact size — the content is streamed into the tar without buffering in memory:

f, err := os.Open("/data/big.bin")
if err != nil {
    panic(err)
}
defer f.Close()

st, err := f.Stat()
if err != nil {
    panic(err)
}

c, err := docker.NewContainerWithLifecycle(
    "my-service",
    "busybox:latest",
    []string{"sleep", "300"},
    nil,
    nil,
    docker.WithFiles(docker.File{
        Content:     f,
        Size:        st.Size(),
        Mode:        0644,
        Destination: "/data/big.bin",
        // Uid/Gid default to 0 = root:root; set them to chown the file.
    }),
)

Copying files out of the container (CopyFromContainer)

To read a file or directory back out of a running container (e.g. to verify what the application produced), use docker.CopyFromContainer. It returns a tar stream that you unpack (e.g. with archive/tar) to obtain the content:

rc, err := docker.CopyFromContainer(ctx, c, "/tmp/report.txt")
if err != nil {
    panic(err)
}
defer rc.Close()

tr := tar.NewReader(rc)
if _, err := tr.Next(); err != nil {
    panic(err)
}

content, err := io.ReadAll(tr)
if err != nil {
    panic(err)
}

fmt.Printf("content: %s", content)

docker.CopyFromContainer works on any Container (including TestContainer) and requires the container to be running. Copying a directory (e.g. /data) returns tar entries named relative to the archive root (data/...). This is the inverse of WithFiles.

Image prefix / proxy

Set the IMAGE_PREFIX environment variable to prepend a registry mirror to all image references:

# Use a local mirror instead of Docker Hub
export IMAGE_PREFIX=registry-mirror.example.com

Modules & releases

The repository is a multi-module workspace (testcontainers-go style):

• Core module: github.com/teran/go-docker-testsuite — the docker package plus wait, images, internal.
• Application modules: github.com/teran/go-docker-testsuite/applications/<name> — each a standalone Go module that imports only the core (leaf nodes; they never import each other).

All modules share a single version number, tagged separately with Go's prefixed-submodule tag scheme:

• core: v1.6.0
• application: applications/redis/v1.6.0

Because an application requires the core at a concrete version, the core tag must exist before an application that depends on it can be tagged and fetched. Release order is therefore: publish the core first, then applications (each merged and tagged in its own PR).

Tag from the repo root with the Makefile:

make tag-core v1.6.0                # tag only the core
make tag-app redis v1.6.0           # tag applications/redis (same version)

A GitHub Release is created for every module tag (release.yml triggers on both v* and applications/*/v*), so each module gets its own Release with auto-generated notes.

During development, application go.mod files may carry a local replace github.com/teran/go-docker-testsuite => ../.. so a checkout builds against the unpublished core; this replace is removed before release (make lint fails if any go.mod has a replace). Local development and CI use go.work (generated by make work) so every module resolves the core and its siblings from the workspace instead of requiring a published tag.

Examples

Each application package includes testable examples. Run them with:

# Run all examples (needs Docker):
go test -run Example ./applications/... .

Project docs

• SPEC.md — Architecture and design specification
• AGENTS.md — Agent instructions for AI-assisted development
• CONTRIBUTING.md — How to contribute
• CODE_OF_CONDUCT.md — Community guidelines
• SECURITY.md — Security policy and vulnerability reporting

License

This project is licensed under the Apache License, Version 2.0.