Testcontainers-Go: Docker en pruebas con Go

En el desarrollo de software moderno, probar integraciones con servicios externos (bases de datos, brokers de mensajes, cachés) es uno de los mayores desafíos. Los enfoques tradicionales, como usar bases de datos compartidas o mocks, suelen generar problemas: las pruebas se vuelven frágiles, dependen del entorno o no reflejan el comportamiento real del sistema. La librería Testcontainers-Go ofrece una solución elegante: permite ejecutar contenedores Docker aislados directamente desde el código de prueba en Go, proporcionando un entorno limpio, reproducible y cercano a producción para cada ejecución de pruebas.

La idea principal de Testcontainers-Go es gestionar el ciclo de vida de los contenedores Docker de forma programática. Tú describes el servicio necesario (por ejemplo, PostgreSQL, Redis, Kafka) en el código de la prueba, la librería descarga automáticamente la imagen (si no existe), inicia el contenedor, espera a que esté listo y te proporciona los parámetros de conexión (host, puerto, credenciales). Al finalizar la prueba, el contenedor se detiene y elimina automáticamente, sin dejar residuos en el sistema. Esto hace que las pruebas sean independientes, rápidas y seguras.

Testcontainers-Go es la implementación en Go del popular proyecto Testcontainers, que nació en Java y luego se portó a otros lenguajes. La librería cuenta con un sólido respaldo de la comunidad y ofrece módulos listos para usar con los servicios más populares: PostgreSQL, MySQL, Redis, MongoDB, Kafka, RabbitMQ, Elasticsearch y muchos más. Es ideal para escribir pruebas de integración, pruebas end-to-end e incluso para desarrollo local cuando necesitas levantar un entorno rápidamente.

Instalación

Para instalar Testcontainers-Go, usa el gestor de paquetes estándar de Go. Asegúrate de tener Docker (o Podman) y Go versión 1.19 o superior instalados.

go get github.com/testcontainers/testcontainers-go

Para trabajar con servicios específicos (por ejemplo, PostgreSQL), necesitarás instalar el módulo correspondiente:

go get github.com/testcontainers/testcontainers-go/modules/postgres
go get github.com/testcontainers/testcontainers-go/modules/redis
go get github.com/testcontainers/testcontainers-go/modules/mongodb
go get github.com/testcontainers/testcontainers-go/modules/kafka
# etc.

Después de la instalación, importa los paquetes en tu archivo de prueba:

import (
    "context"
    "testing"
    
    "github.com/testcontainers/testcontainers-go"
    "github.com/testcontainers/testcontainers-go/wait"
    "github.com/testcontainers/testcontainers-go/modules/postgres"
)

Inicio rápido: ejemplo mínimo funcional

Escribamos una prueba simple que inicie un contenedor PostgreSQL, cree una tabla, inserte datos y los verifique. Esto te mostrará los principios básicos de la librería.

package main

import (
    "context"
    "database/sql"
    "testing"
    "time"

    "github.com/testcontainers/testcontainers-go"
    "github.com/testcontainers/testcontainers-go/modules/postgres"
    "github.com/testcontainers/testcontainers-go/wait"
    _ "github.com/lib/pq" // driver PostgreSQL
)

func TestPostgresIntegration(t *testing.T) {
    ctx := context.Background()

    // 1. Iniciamos el contenedor PostgreSQL
    postgresContainer, err := postgres.RunContainer(ctx,
        testcontainers.WithImage("postgres:16-alpine"),
        postgres.WithDatabase("testdb"),
        postgres.WithUsername("testuser"),
        postgres.WithPassword("testpass"),
        testcontainers.WithWaitStrategy(
            wait.ForLog("database system is ready to accept connections").
                WithOccurrence(2).
                WithStartupTimeout(60*time.Second)),
    )
    if err != nil {
        t.Fatal(err)
    }
    defer postgres