testcontainers_skill

Overview

This skill teaches writing integration tests for .NET using Testcontainers and xUnit so you run real databases, caches, and message brokers in Docker instead of using mocks. It focuses on reliable infrastructure tests, test isolation, and CI-friendly setups to validate migrations, queries, transactions, caching, and messaging behavior.

How this skill works

Tests start disposable Docker containers via the Testcontainers .NET API, map ports, and expose a real connection string to the test code. Each test class can start containers in InitializeAsync, run migrations or schema setup, exercise real operations (SQL, Redis, RabbitMQ), and then dispose containers to ensure cleanup. Patterns cover SQL Server, PostgreSQL, Redis, Rabbitmq, and multi-container networks.

When to use it

• Validating data access layer behavior against a real database (queries, constraints, indexes)
• Testing database migrations and schema changes in CI
• Verifying message production/consumption using RabbitMQ or other brokers
• Checking cache semantics and TTL behavior with Redis
• Replacing infrastructure mocks to catch integration issues before production

Best practices

• Isolate tests: create fresh state or containers per test/class to avoid cross-test flakiness
• Run migrations or explicit schema setup in InitializeAsync to keep tests deterministic
• Reuse containers within a test class when startup time matters, but ensure data reset between tests
• Use random port binding and wait strategies to avoid race conditions on CI agents
• Clean up connections and call DisposeAsync on containers and networks to prevent resource leaks

Example use cases

• Run repository tests against a SQL Server container to catch SQL syntax or constraint errors
• Assert transaction behavior by rolling back inserts in a PostgreSQL container
• Validate Redis caching and expiration semantics using a redis:alpine container
• Publish and consume messages from a RabbitMQ container to verify end-to-end messaging
• Start a dedicated network with multiple containers when services must resolve each other by alias