Testcontainers .NET para C#: guía completa con ejemplos prácticos

En el desarrollo de software moderno, las pruebas de integración son una etapa crítica para verificar cómo tu aplicación interactúa con dependencias externas: bases de datos, brokers de mensajes, cachés y otros servicios. Tradicionalmente, los desarrolladores usaban mocks o stubs, que no garantizan un funcionamiento correcto, o levantaban instancias de prueba manualmente, un proceso lento, complejo y poco reproducible. La librería Testcontainers .NET resuelve este problema de raíz: te permite gestionar contenedores Docker directamente desde tus tests, proporcionando entornos ligeros, desechables y aislados para cada escenario de prueba.

La idea principal de Testcontainers es hacer que las pruebas de integración sean tan simples y rápidas como las pruebas unitarias. Solo tienes que declarar en tu test qué necesitas, por ejemplo, PostgreSQL o Redis. La librería descarga automáticamente la imagen Docker correspondiente (si no existe), inicia el contenedor, espera a que esté listo y te devuelve la cadena de conexión. Al finalizar el test, el contenedor se detiene y se elimina automáticamente. Esto garantiza un entorno de pruebas limpio, sin residuos y completamente reproducible en cualquier máquina o servidor de integración continua.

Testcontainers .NET es el puerto oficial de la popular librería Java Testcontainers. Es compatible con todo el ecosistema .NET, incluyendo xUnit, NUnit y MSTest. La librería ofrece módulos listos para los servicios más comunes (bases de datos, NoSQL, colas, servidores web) y permite crear contenedores personalizados para cualquier imagen Docker. Usar Testcontainers .NET es el estándar moderno para escribir pruebas de integración robustas y de calidad en la comunidad .NET.

Instalación

Para instalar la librería Testcontainers .NET se usa el gestor de paquetes NuGet. Ejecuta el siguiente comando en la terminal en la raíz de tu proyecto o desde la consola del administrador de paquetes de Visual Studio:

dotnet add package Testcontainers

Este comando instalará el paquete principal Testcontainers, que incluye las clases base y soporte para contenedores personalizados. Para trabajar con servicios específicos (por ejemplo, PostgreSQL, MSSQL, Redis), necesitarás paquetes adicionales. Se instalan de forma similar:

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

Después de instalar los paquetes, asegúrate de que Docker Daemon esté ejecutándose en tu máquina (Docker Desktop para Windows/Mac o Docker Engine para Linux). Testcontainers se comunica con Docker a través de su API.

Inicio rápido: ejemplo mínimo funcional

Escribamos un test simple con xUnit que inicia un contenedor PostgreSQL, crea una tabla, inserta datos y verifica su lectura. Este ejemplo muestra el principio básico de funcionamiento de la librería.

using Testcontainers.PostgreSql;
using Xunit;
using Npgsql;

namespace MyIntegrationTests;

public class PostgresQuickStartTest : IAsyncLifetime
{
    private PostgreSqlContainer _postgresContainer;

    // IAsyncLifetime permite gestionar el ciclo de vida del contenedor
    public async Task InitializeAsync()
    {
        // 1. Definimos el contenedor con la configuración por defecto
        _postgresContainer = new PostgreSqlBuilder()
            .WithImage("postgres:15-alpine") // Especificamos la imagen
            .WithDatabase("testdb")          // Nombre de la BD
            .WithUsername("testuser")        // Usuario
            .WithPassword("testpassword")    // Contraseña
            .Build();