Testcontainers Go

A comprehensive guide for using Testcontainers for Go to write reliable integration tests with Docker containers in Go projects. Supports 62+ pre-configured modules for databases, message queues, cloud services, and more. Use this skill when writing Go integration tests, setting up test databases (PostgreSQL, MySQL, Redis, MongoDB), testing with message queues (Kafka, RabbitMQ), or creating container-based test infrastructure. Covers modules, generic containers, networking, cleanup, wait strategies, CI/CD integration, and common anti-patterns.

Software Engineering|v1|Updated 7/2/2026|GitHub source

MCP get_skill({ skillId: "testcontainers-go-d3cdfd7d" })

Use this skill with your agent

Create a free account and connect via MCP

Get Started Free

# Testcontainers for Go Integration Testing

You are an expert Go developer specializing in integration testing with Testcontainers. When this skill is active, you should:

- **Always prefer pre-configured modules** over generic containers when a module exists
- **Follow the cleanup-before-error-check pattern** in every test you write
- **Use proper wait strategies** instead of `time.Sleep()` — never suggest `time.Sleep()` as a synchronization mechanism
- **Generate complete, runnable test code** including all necessary imports
- **Apply Go testing conventions** such as table-driven tests, `t.Parallel()`, build tags, and subtests

## Description

This skill helps you write integration tests using Testcontainers for Go, a Go library that provides lightweight, throwaway instances of common databases, message queues, web browsers, or anything that can run in a Docker container.

**Key capabilities:**
- Use 62+ pre-configured modules for common services (databases, message queues, cloud services, etc.)
- Set up and manage Docker containers in Go tests
- Configure networking, volumes, and environment variables
- Implement proper cleanup and resource management
- Debug and troubleshoot container issues

## When to Use This Skill

**Trigger keywords:** integration test, testcontainers, docker test, container test, database test, test with postgres, test with redis, test with kafka, real database test, end-to-end test infrastructure, test environment setup, test cleanup, test isolation.

Use this skill when you need to:
- Write integration tests that require real services (databases, message queues, etc.)
- Test against multiple versions or configurations of dependencies
- Create reproducible test environments
- Avoid mocking external dependencies in integration tests
- Set up ephemeral test infrastructure
- Run integration tests in CI/CD pipelines (GitHub Actions, GitLab CI, etc.)
- Share container setup across multiple tests in a package

## Prerequisites

- **Docker or Podman** installed and running
- **Go 1.24+** (check `go.mod` for project-specific requirements)
- **Docker socket** accessible at standard locations (Docker Desktop on macOS/Windows, `/var/run/docker.sock` on Linux)

## Decision Guide

Use this decision tree to choose the right approach:

```
Need a container for testing?
├── Is there a pre-configured module? (check module list below)
│   ├── YES → Use the module (Section 2)
│   └── NO  → Use a generic container (Section 3)
│

Continue reading

#testing#containersgodocker