testcontainers-integration-tests

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

Why TestContainers Over Mocks?

The Problem with Mocking Infrastructure

// BAD: Mocking a database
public class OrderRepositoryTests
{
    private readonly Mock<IDbConnection> _mockDb = new();

    [Fact]
    public async Task GetOrder_ReturnsOrder()
    {
        // This doesn't test real SQL behavior, constraints, or performance
        _mockDb.Setup(db => db.QueryAsync<Order>(It.IsAny<string>()))
            .ReturnsAsync(new[] { new Order { Id = 1 } });

        var repo = new OrderRepository(_mockDb.Object);
        var order = await repo.GetOrderAsync(1);

        Assert.NotNull(order);
    }
}

Problems: doesn't test actual SQL queries, misses constraints/indexes, gives false confidence, doesn't catch SQL syntax errors.

Better: TestContainers with Real Database