Testcontainers .NET para C# (.NET): guia completo com exemplos

No desenvolvimento de software moderno, o teste de integração é uma etapa crucial para verificar a interação da sua aplicação com dependências externas: bancos de dados, brokers de mensagens, caches e outros serviços. Tradicionalmente, os desenvolvedores usavam mocks/stubs, que não garantem total confiança na correção do funcionamento, ou configuravam instâncias de teste manualmente, o que é complexo, lento e não reproduzível. A biblioteca Testcontainers .NET resolve esse problema de forma radical: ela permite gerenciar contêineres Docker programaticamente diretamente dos seus testes, fornecendo ambientes leves, descartáveis e isolados para cada cenário de teste.

A ideia principal do Testcontainers é tornar os testes de integração tão simples e rápidos quanto os testes unitários. Você simplesmente escreve um teste declarando que precisa, por exemplo, de PostgreSQL ou Redis. A biblioteca baixa automaticamente a imagem Docker correspondente (se ainda não existir), inicia o contêiner, aguarda sua prontidão e fornece a string de conexão. Após a conclusão do teste, o contêiner é automaticamente parado e removido. Isso garante um ambiente de teste limpo, sem "lixo" e total reprodutibilidade em qualquer máquina do desenvolvedor ou servidor de CI.

Testcontainers .NET é o port oficial da popular biblioteca Java Testcontainers. Ele oferece suporte completo ao ecossistema .NET, incluindo xUnit, NUnit e MSTest. A biblioteca fornece módulos prontos para a maioria dos serviços populares (bancos de dados, NoSQL, filas, servidores web) e permite criar facilmente contêineres personalizados para qualquer imagem Docker. Usar Testcontainers .NET é o padrão moderno para escrever testes de integração confiáveis e de alta qualidade na comunidade .NET.

Instalação

Para instalar a biblioteca Testcontainers .NET, use o gerenciador de pacotes NuGet. Execute o seguinte comando no terminal na raiz do seu projeto ou através do console do gerenciador de pacotes do Visual Studio:

dotnet add package Testcontainers

Este comando instalará o pacote principal Testcontainers, que inclui as classes base e suporte para contêineres personalizados. Para trabalhar com serviços específicos (por exemplo, PostgreSQL, MSSQL, Redis), você pode precisar de pacotes adicionais. Eles são instalados de forma semelhante:

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

Após instalar os pacotes, certifique-se de que o Docker Daemon está em execução na sua máquina (Docker Desktop para Windows/Mac ou Docker Engine para Linux). O Testcontainers se comunica com o Docker através da sua API.

Início rápido: exemplo mínimo funcional

Vamos escrever um teste simples usando xUnit, que inicia um contêiner PostgreSQL, cria uma tabela, insere dados e verifica sua leitura. Este exemplo demonstra o princípio básico de funcionamento da biblioteca.

using Testcontainers.PostgreSql;
using Xunit;
using Npgsql;

namespace MyIntegrationTests;

public class PostgresQuickStartTest : IAsyncLifetime
{
    private PostgreSqlContainer _postgresContainer;

    // IAsyncLifetime permite gerenciar o ciclo de vida do contêiner
    public async Task InitializeAsync()
    {
        // 1. Definimos o contêiner com as configurações padrão
        _postgresContainer = new PostgreSqlBuilder()
            .WithImage("postgres:15-alpine") // Especificamos a imagem
            .WithDatabase("testdb")          // Nome do banco
            .WithUsername("testuser")        // Usuário
            .WithPassword("testpassword")    // Senha
            .Build();