# Testcontainers Integration Tests

Write integration tests using TestContainers for .NET with xUnit.

- Repository: https://github.com/Aaronontheweb/dotnet-skills (1244 stars)
- Category: Testing
- License: MIT
- Last updated: 2026-10-28
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add Aaronontheweb/dotnet-skills --skill testcontainers-integration-tests -g -a claude-code -y`
Codex: `npx skills add Aaronontheweb/dotnet-skills --skill testcontainers-integration-tests -g -a codex -y`
Cursor: `npx skills add Aaronontheweb/dotnet-skills --skill testcontainers-integration-tests -g -a cursor -y`
Gemini CLI: `npx skills add Aaronontheweb/dotnet-skills --skill testcontainers-integration-tests -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add Aaronontheweb/dotnet-skills`

## Description

Write integration tests using TestContainers for .NET with xUnit. Covers infrastructure testing with real databases, message queues, and caches in Docker containers instead of mocks.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# 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](database-patterns.md): SQL Server, PostgreSQL, and migration testing examples
- [infrastructure-patterns.md](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) |

The rest: https://github.com/Aaronontheweb/dotnet-skills/blob/HEAD/skills/testcontainers/SKILL.md