Testcontainers .NET for C#: Complete Guide with Examples

In modern software development, integration testing is a critical step that verifies how your application interacts with external dependencies: databases, message brokers, caches, and other services. Traditionally, developers either used mocks and stubs (which don't guarantee correct behavior) or manually spun up test service instances (which is complex, slow, and non-reproducible). The Testcontainers .NET library solves this problem radically: it lets you programmatically manage Docker containers directly from your tests, providing lightweight, disposable, and isolated environments for each test scenario.

The core idea behind Testcontainers is to make integration tests as simple and fast as unit tests. You simply write a test where you declare that you need, for example, PostgreSQL or Redis. The library automatically downloads the appropriate Docker image (if not already present), starts the container, waits for it to be ready, and provides you with the connection string. After the test finishes, the container is automatically stopped and removed. This ensures a clean test environment, no leftover "junk," and full reproducibility on any developer machine or CI server.

Testcontainers .NET is the official port of the popular Java library Testcontainers. It fully supports the .NET ecosystem, including xUnit, NUnit, and MSTest. The library provides ready-made modules for most popular services (databases, NoSQL, queues, web servers) and makes it easy to create custom containers for any Docker image. Using Testcontainers .NET is the modern standard for writing reliable, high-quality integration tests in the .NET community.

Installation

To install the Testcontainers .NET library, use the NuGet package manager. Run the following command in your terminal at the project root or via the Visual Studio Package Manager Console:

dotnet add package Testcontainers

This command installs the core Testcontainers package, which includes base classes and support for custom containers. For working with specific services (e.g., PostgreSQL, MSSQL, Redis), you may need additional packages. Install them similarly:

dotnet add package Testcontainers.PostgreSql
dotnet add package Testcontainers.Redis
dotnet add package Testcontainers.MsSql
dotnet add package Testcontainers.MongoDb
dotnet add package Testcontainers.RabbitMq

After installing the packages, make sure Docker Daemon is running on your machine (Docker Desktop for Windows/Mac or Docker Engine for Linux). Testcontainers communicates with Docker through its API.

Quick Start: Minimal Working Example

Let's write a simple test using xUnit that starts a PostgreSQL container, creates a table, inserts data, and verifies reading it back. This example demonstrates the library's basic workflow.

using Testcontainers.PostgreSql;
using Xunit;
using Npgsql;

namespace MyIntegrationTests;

public class PostgresQuickStartTest : IAsyncLifetime
{
    private PostgreSqlContainer _postgresContainer;

    // IAsyncLifetime lets you manage the container lifecycle
    public async Task InitializeAsync()
    {
        // 1. Define the container with default settings
        _postgresContainer = new PostgreSqlBuilder()
            .WithImage("postgres:15-alpine") // Specify the image
            .WithDatabase("testdb")          // Database name
            .WithUsername("testuser")        // Username
            .WithPassword("testpassword")    // Password
            .Build();