testcontainers-go

Testcontainers for Go is a Go package that makes it simple to create and clean up container-based dependencies for automated integration and smoke tests. Instead of mocking a database, message broker, or third-party service, tests spin up the real thing in a Docker container, run against it, and let the library handle teardown when the test session ends.

The library ships a core testcontainers package for defining arbitrary ContainerRequests plus a large catalog of purpose-built modules — Postgres, MySQL, Kafka, Redis, LocalStack, and dozens more — that wrap the raw container API with typed, service-specific constructors and connection-string helpers. A wait package provides composable readiness strategies (HTTP, log line, SQL ping, exec, health check) so tests only proceed once a container is actually ready to serve traffic.

What You Get

• A core testcontainers API (GenericContainer, ContainerRequest, Container interface) for running any Docker image as a test dependency, with full control over ports, env vars, mounts, and networks.
• Over 80 ready-made modules under modules/ (Postgres, MySQL, MongoDB, Kafka, Redis, Elasticsearch, LocalStack, RabbitMQ, and more) that expose typed constructors and connection-string helpers instead of raw container config.
• A composable wait package with strategies for HTTP readiness, log-line matching, SQL connectivity, exec-based checks, TLS, and health-check polling, combinable via wait.ForAll.
• Automatic resource cleanup via a Ryuk-based reaper process and testcontainers.CleanupContainer/terminate helpers, so containers don’t leak between test runs even on failure or interruption.
• Podman and Docker Desktop compatibility with auto-detection of the container runtime via ProviderType, plus support for building images from a Dockerfile on the fly for testing custom builds.
• A network package for creating isolated Docker networks so multi-container test scenarios (e.g. an app container talking to a database container) can communicate without touching the host network.

Common Use Cases

• Running integration tests against a real Postgres or MySQL instance instead of an in-memory or mocked database, catching driver- and dialect-specific bugs that mocks miss.
• Testing message-queue-driven code end-to-end by spinning up Kafka, RabbitMQ, or Redis Streams in CI without a shared, stateful test environment.
• Verifying Docker Compose-based application stacks in CI by launching multiple interconnected containers on a shared test network and asserting on their combined behavior.
• Smoke-testing a custom Docker image by building it directly from a Dockerfile inside the test and asserting the container starts, becomes healthy, and serves expected responses.
• Testing cloud-service integrations locally and in CI using LocalStack or provider-emulator modules instead of hitting real AWS/GCP/Azure accounts from the test suite.

Under The Hood

Architecture The library is organized around a small core (testcontainers.go, container.go, provider.go, generic.go) that defines the Container and GenericProvider interfaces, with a DockerProvider implementation in docker.go that talks to the Docker/Podman engine via the moby/moby/client SDK. Everything else — the wait package for readiness strategies, the network package for Docker network management, the exec package for in-container command execution, and 80+ modules under modules/ — is built as composable, independent packages layered on top of that core Container/ContainerRequest abstraction, so a change to the core request/response types is the one place that would ripple across the entire module catalog. Internal concerns like Docker host resolution and session bookkeeping live under internal/core and internal/config, kept separate from the public API surface.

Tech Stack Written in Go (module targets Go 1.25, toolchain 1.25.9) with github.com/moby/moby/client and github.com/moby/moby/api as the low-level Docker engine client, github.com/cpuguy83/dockercfg for registry auth, github.com/moby/go-archive and github.com/moby/patternmatcher for build-context handling, github.com/google/uuid for session IDs, github.com/shirou/gopsutil/v4 for host introspection, and github.com/stretchr/testify as the test-assertion library used throughout its own test suite. Each of the 80+ modules under modules/ (Postgres, Kafka, Redis, LocalStack, etc.) is a self-contained Go package with its own go.mod, pulling in the relevant client driver for that service only when that module is used.

Code Quality The root package alone carries around 29 _test.go files, and nearly every module and the wait package ship parallel _test.go coverage, all built on testify for assertions. The project enforces golangci-lint with errorlint, govet, gocritic, nakedret, nolintlint, and perfsprint enabled, plus gofumpt/gci formatting with import-section ordering, run via dedicated ci-lint-go.yml and ci-test-go.yml GitHub Actions workflows alongside CodeQL and OSSF Scorecard scans. Errors are returned as typed Go error values throughout rather than panicking, with errors.Is/errors.As-style wrapping expected by the errorlint lint rule.

What Makes It Unique Rather than a single generic “run a container” helper, the project maintains an extensive, community-curated catalog of per-service modules that encode the correct readiness strategy, default ports, and connection-string format for each supported service, removing a large class of flaky-test bugs that come from hand-rolled wait logic. Its Ryuk-based reaper guarantees container cleanup even when a test process crashes or is killed mid-run, which ad hoc docker run-based test setups typically don’t handle.