testcontainers-go: Docker in Go Tests

In modern software development, testing integrations with external services (databases, message brokers, caches) is one of the most challenging tasks. Traditional approaches, such as using shared test databases or mocks, often lead to problems: tests become fragile, depend on the environment, or do not reflect the real behavior of the system. The testcontainers-go library offers an elegant solution: it allows you to run isolated Docker containers directly from Go test code, providing a clean, reproducible, and production-like environment for each test run.

The main idea of testcontainers-go is to manage the lifecycle of Docker containers programmatically. You describe the required service (e.g., PostgreSQL, Redis, Kafka) in the test code, the library automatically downloads the image (if not present), starts the container, waits for it to be ready, and provides you with connection parameters (host, port, credentials). After the test finishes, the container is automatically stopped and removed, leaving no garbage in the system. This makes tests independent, fast, and safe.

testcontainers-go is the Go implementation of the popular Testcontainers project, which originally appeared in Java and was later ported to other languages. The library is actively maintained by the community and provides ready-made modules for most popular services: PostgreSQL, MySQL, Redis, MongoDB, Kafka, RabbitMQ, Elasticsearch, and many others. It is ideal for writing integration tests, end-to-end tests, and even for local development when you need to quickly spin up an environment.

Installation

To install testcontainers-go, use the standard Go package manager. Make sure you have Docker (or Podman) and Go version 1.19 or higher installed.

go get github.com/testcontainers/testcontainers-go\n

To work with specific services (e.g., PostgreSQL), you will need to install the corresponding module:

go get github.com/testcontainers/testcontainers-go/modules/postgres\ngo get github.com/testcontainers/testcontainers-go/modules/redis\ngo get github.com/testcontainers/testcontainers-go/modules/mongodb\ngo get github.com/testcontainers/testcontainers-go/modules/kafka\n# etc.\n

After installation, import the packages into your test file:

import (\n    "context"\n    "testing"\n    \n    "github.com/testcontainers/testcontainers-go"\n    "github.com/testcontainers/testcontainers-go/wait"\n    "github.com/testcontainers/testcontainers-go/modules/postgres"\n)\n

Quick Start: Minimal Working Example

Let's write a simple test that starts a PostgreSQL container, creates a table, inserts data, and verifies it. This will show you the basic principles of working with the library.

package main\n\nimport (\n    "context"\n    "database/sql"\n    "testing"\n    "time"\n\n    "github.com/testcontainers/testcontainers-go"\n    "github.com/testcontainers/testcontainers-go/modules/postgres"\n    "github.com/testcontainers/testcontainers-go/wait"\n    _ "github.com/lib/pq" // PostgreSQL driver\n)\n\nfunc TestPostgresIntegration(t *testing.T) {\n    ctx := context.Background()\n\n    // 1. Start the PostgreSQL container\n    postgresContainer, err := postgres.RunContainer(ctx,\n        testcontainers.WithImage("postgres:16-alpine"),\n        postgres.WithDatabase("testdb"),\n        postgres.WithUsername("testuser"),\n        postgres.WithPassword("testpass"),\n        testcontainers.WithWaitStrategy(\n            wait.ForLog("database system is ready to accept connections").\n                WithOccurrence(2).\n                WithStartupTimeout(60*time.Second)),\n