Integration Testing with TestContainers

When to Use This Skill

Use this skill when:

• Writing integration tests that need real infrastructure (databases, caches, message queues)
• Testing data access layers against actual databases
• Verifying message queue integrations
• Testing Redis caching behavior
• Avoiding mocks for infrastructure components
• Ensuring tests work against production-like environments
• Testing database migrations and schema changes

Reference Files

• database-patterns.md: SQL Server, PostgreSQL, and migration testing examples
• infrastructure-patterns.md: Redis, RabbitMQ, multi-container networks, container reuse, and Respawn

Core Principles

1. Real Infrastructure Over Mocks - Use actual databases/services in containers, not mocks
2. Test Isolation - Each test gets fresh containers or fresh data
3. Automatic Cleanup - TestContainers handles container lifecycle and cleanup
4. Fast Startup - Reuse containers across tests in the same class when appropriate
5. CI/CD Compatible - Works seamlessly in Docker-enabled CI environments
6. Port Randomization - Containers use random ports to avoid conflicts

TestContainers 4.x API

This skill targets TestContainers 4.x with the 3.0+ module builder API. The pre-3.0 types were renamed and removed, so code that uses TestcontainersBuilder<T> or TestcontainersContainer does not compile against the modern packages:

Old (pre-3.0)	New (3.0+)
new TestcontainersBuilder<T>()	Module builder (e.g. new PostgreSqlBuilder(...)) or new ContainerBuilder(...)
TestcontainersContainer	DockerContainer / module container (e.g. PostgreSqlContainer)
TestcontainersNetworkBuilder	NetworkBuilder
GetMappedPublicPort(port)	GetMappedPublicPort(port) (still available)