Dockertest

Dockertest is a Go library that lets integration tests boot real, ephemeral Docker containers — a Postgres database, a Redis cache, a Kafka broker — instead of relying on mocks or stubs. A small Pool/Resource API wraps the Docker Engine API, auto-detects the right connection method for the current OS, and provides an exponential-backoff Retry helper so tests can wait for a service to become ready before running assertions.

Containers are torn down automatically when the test suite finishes, so CI runners don’t accumulate leftover state between runs. The examples directory ships ready-to-copy patterns for common services (Postgres, MySQL, MongoDB, Redis, Kafka, Cassandra, and more), and network/exec helpers support multi-container integration scenarios where several services need to talk to each other during a test.

What You Get

• Pool/Resource API - NewPool auto-detects the Docker connection (Unix socket or TLS/TCP) per OS, and Pool.Run/RunWithOptions return a Resource wrapping the live container.
• Exponential-backoff retry helper - Pool.Retry wraps cenkalti/backoff so tests can poll a just-started service until it accepts connections, without hand-rolling a wait loop.
• Automatic cleanup - Pool.Purge removes a container, and RunOptions/config.AutoRemove clean up stopped containers so CI runners don’t accumulate leftover state.
• Curated service examples - 13 ready-to-copy examples for Postgres, MySQL, MongoDB, Redis, Kafka, Cassandra, CockroachDB, Minio, RethinkDB, and more.
• Network and exec support - CreateNetwork/ConnectToNetwork for multi-container tests and Resource.Exec to run commands inside a running container.

Common Use Cases

• Database integration tests - Boot a real Postgres or MySQL container in TestMain, run migrations against it, and tear it down after the suite.
• Testing against Redis/Kafka - Start a disposable cache or message broker for tests that exercise real client behavior instead of an in-memory fake.
• Multi-service integration suites - Wire several containers together on a dockertest-managed network to test service-to-service behavior end-to-end.
• CI pipelines with Docker-in-Docker - Run the same container-backed tests locally and in GitHub Actions/GitLab CI using a docker:dind service.

Under The Hood

Architecture A single flat package (dockertest.go, 707 lines) built around two core types: Pool (wraps a docker.Client connection; NewPool/NewTLSPool construct it by auto-detecting DOCKER_HOST/TLS certs) and Resource (wraps a running docker.Container). All container lifecycle operations — Run, RunWithOptions, BuildAndRun, Purge, Retry, ContainerByName — are methods on Pool, while Resource exposes accessor methods (GetPort, GetHostPort, GetBoundIP, Exec, Expire, ConnectToNetwork) for consuming a running container from test code. A vendored, trimmed fork of fsouza/go-dockerclient lives under docker/ and provides the actual Docker Engine API bindings that Pool delegates to, so behavior is fully owned in-repo with no external Docker SDK dependency. Extension happens through functional options (RunOptions, hcOpts ...func(*dc.HostConfig)) rather than an interface or plugin system, so a change to the core docker.Client abstraction would touch every Pool method.

Tech Stack Standard library Go (go 1.22) plus a small, deliberate dependency set: cenkalti/backoff/v4 for the exponential-backoff retry loop, Microsoft/go-winio and moby/term/opencontainers/* for cross-platform (Windows/Unix) named-pipe and terminal handling, and docker/go-connections/docker/go-units for Docker API URL/size parsing. Test-only drivers (go-sql-driver/mysql, lib/pq) are used in the package’s own integration tests against MySQL/Postgres. There is no web framework or ORM — this is a pure library, not a service. Build/test tooling is a Makefile plus GitHub Actions running go test ./... against a live docker:dind service, with separate workflows for CVE scanning and license checks. Consumers just go get the module and call it from their own TestMain.

Code Quality Testing is thorough for a testing library: dockertest_test.go (518 lines) exercises NewPool, Run, RunWithOptions, BuildAndRun, Retry, Purge, and network operations against a real Docker daemon — it tests itself by actually spinning up containers rather than mocking — plus focused unit tests in the vendored docker/types/* subpackages. Error handling is idiomatic Go: every public method returns error explicitly, wrapped with context, with sentinel errors like ErrNotInContainer; no swallowed errors were observed. Naming is consistent and exported-API-conscious (Pool, Resource, RunOptions, ExecOptions). CI enforces tests via GitHub Actions on every push, and a separate formatting workflow checks style.

API Design The core idea — spin up throwaway Docker containers for integration tests instead of mocking — isn’t unique to dockertest (Testcontainers does the same across languages), but the Go-specific execution is clean: NewPool("") auto-detects the right connection method per OS with zero configuration in the common case, and Pool.Retry bakes exponential backoff directly into the pool so callers don’t need a separate retry library to wait for a container’s service to become ready. The API surface is small and mostly copy-pasteable from the README’s TestMain pattern, and the examples directory (13 markdown files covering Postgres, MySQL, Kafka, Redis, MongoDB, Cassandra, CockroachDB, Minio, RethinkDB, Mountebank, a GCS emulator, and multi-container setups) covers most common service dependencies out of the box — that curated examples library is the practical differentiator versus rolling your own docker-client wrapper.