testcontainers-go_skill

Overview

This skill is a practical guide to using Testcontainers for Go to write reliable integration tests that run real services in disposable Docker containers. It covers 62+ pre-configured modules, generic container usage, networking, lifecycle hooks, and patterns for stable tests in CI and locally. The focus is on actionable examples, safe defaults, and avoiding common pitfalls that lead to flaky tests.

How this skill works

The skill explains how to start and manage containers from Go tests using the testcontainers-go library and its modules. It shows how to prefer pre-configured modules (sensible defaults, helpers, snapshots) and fall back to generic containers with explicit wait strategies when needed. It also covers cleanup registration, network creation, configuration options, and lifecycle hooks for custom initialization and teardown.

When to use it

• When integration tests require real services (databases, queues, search engines) instead of mocks
• When you need reproducible, versioned test environments for CI pipelines
• When testing multiple dependency versions or configurations in table-driven tests
• When you want ephemeral test infrastructure isolated per test or per suite
• When you need to simulate multi-service networking or service discovery

Best practices

• Prefer module packages over generic containers for tested defaults and helper methods
• Always register CleanupContainer immediately after starting a container to avoid leaks
• Use explicit wait strategies (ForListeningPort, ForHTTP, ForLog) instead of time.Sleep
• Expose only needed ports and use networks for inter-container communication within tests
• Keep container configuration minimal in tests; override with module-specific options only when necessary

Example use cases

• Start a Postgres module, get ConnectionString(), run migrations, take/restore snapshots for isolation
• Run Kafka module in tests and use Brokers() to obtain bootstrap servers for producers/consumers
• Spin up Redis or Elasticsearch modules for end-to-end API tests
• Create a custom network, start a database and app container on it, and validate inter-service calls
• Use table-driven tests to run the same test suite against multiple image tags or versions