Artículo

Testcontainers con Spring Boot: tests con una base de datos real

Cómo usar Testcontainers en Spring Boot 4 para probar con PostgreSQL real en Docker: dependencias, @ServiceConnection, esquema y errores frecuentes.

En resumen: Testcontainers arranca contenedores Docker desde tus tests (PostgreSQL, Kafka, Redis…) y los destruye al terminar. En Spring Boot basta con un campo @Container @ServiceConnection static PostgreSQLContainer: Spring configura la URL, el usuario y la contraseña solos. Así pruebas contra la misma base de datos que en producción, no contra H2. Probado con Spring Boot 4.1.2, Testcontainers 2 y PostgreSQL 17 en Docker.

Vídeo explicativo

Por qué no basta con H2

H2 es cómodo, pero no es PostgreSQL: tipos como jsonb, funciones, índices parciales, el comportamiento de las secuencias o las migraciones de Flyway pueden funcionar en H2 y fallar en producción, o al revés. Con Testcontainers el test usa el motor real.

Dependencias

<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-testcontainers</artifactId>
  <scope>test</scope>
</dependency>
<dependency>
  <groupId>org.testcontainers</groupId>
  <artifactId>testcontainers-junit-jupiter</artifactId>
  <scope>test</scope>
</dependency>
<dependency>
  <groupId>org.testcontainers</groupId>
  <artifactId>testcontainers-postgresql</artifactId>
  <scope>test</scope>
</dependency>
<dependency>
  <groupId>org.postgresql</groupId>
  <artifactId>postgresql</artifactId>
  <scope>runtime</scope>
</dependency>

Las versiones las gestiona el spring-boot-starter-parent. En Testcontainers 2 los módulos se llaman testcontainers-postgresql y testcontainers-junit-jupiter, y la clase vive en org.testcontainers.postgresql; en la versión 1.x eran postgresql, junit-jupiter y org.testcontainers.containers. Muchos tutoriales antiguos usan los nombres viejos.

El test

import org.springframework.boot.testcontainers.service.connection.ServiceConnection;
import org.testcontainers.junit.jupiter.Container;
import org.testcontainers.junit.jupiter.Testcontainers;
import org.testcontainers.postgresql.PostgreSQLContainer;

@SpringBootTest(properties = "spring.jpa.hibernate.ddl-auto=create-drop")
@Testcontainers
class PostgresContainerTest {

    @Container
    @ServiceConnection
    static PostgreSQLContainer postgres = new PostgreSQLContainer("postgres:17-alpine");

    @Autowired
    LibroRepository libros;

    @Autowired
    DataSource dataSource;

    @Test
    void guardaYConsultaEnUnPostgresReal() throws Exception {
        try (var conn = dataSource.getConnection()) {
            System.out.println("Conectado a: " + conn.getMetaData().getDatabaseProductName()
                    + " " + conn.getMetaData().getDatabaseProductVersion());
            System.out.println("URL: " + conn.getMetaData().getURL());
        }
        libros.saveAll(List.of(new Libro("Clean Code", 464), new Libro("Refactoring", 448),
                new Libro("Domain-Driven Design", 560)));

        var gordos = libros.findByPaginasGreaterThan(450, PageRequest.of(0, 10));
        System.out.println("Libros de más de 450 páginas: "
                + gordos.map(Libro::getTitulo).getContent());
        assertThat(gordos.getTotalElements()).isEqualTo(2);
    }
}

Salida:

Container is started (JDBC URL: jdbc:postgresql://localhost:65019/test?loggerLevel=OFF)
Conectado a: PostgreSQL 17.10
URL: jdbc:postgresql://localhost:65019/test?loggerLevel=OFF
Libros de más de 450 páginas: [Clean Code, Domain-Driven Design]
Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 3.719 s

Testcontainers eligió un puerto libre (65019) y @ServiceConnection pasó esa URL a Spring sin tocar application.properties. La primera vez tarda más, porque Docker descarga la imagen.

El error que nos encontramos

La primera ejecución falló con un error de este tipo (en nuestro caso la secuencia tenía otro nombre porque las entidades eran clases anidadas):

ERROR: relation "libro_seq" does not exist

Con H2 todo funcionaba. La razón: Spring Boot solo crea el esquema automáticamente para bases de datos embebidas. Con PostgreSQL, ddl-auto vale none y no hay tablas. Tienes dos soluciones:

  • En un ejemplo o en tests sencillos: spring.jpa.hibernate.ddl-auto=create-drop, como arriba.
  • En un proyecto real: deja que Flyway o Liquibase creen el esquema. Así el test valida también tus migraciones, que es justo lo que H2 no puede comprobar.

Que vaya más rápido

  • Contenedor static: se arranca una vez por clase, no por test.
  • Reutiliza el contexto de Spring: si varias clases de test comparten configuración, Spring cachea el contexto y el contenedor.
  • Imágenes alpine y fijadas a una versión concreta: más pequeñas y reproducibles.
  • Un contenedor para toda la suite: declara el contenedor en una clase base o en una @TestConfiguration con un @Bean @ServiceConnection, e impórtala en cada test.

Preguntas frecuentes

¿Necesito Docker instalado?

Sí, Docker (o un entorno compatible) debe estar en marcha en la máquina y en el servidor de CI. Si no, el test falla con Could not find a valid Docker environment.

¿Sirve para algo más que bases de datos?

Sí: Kafka, RabbitMQ, Redis, MongoDB, Elasticsearch, LocalStack (servicios de AWS) o cualquier imagen con GenericContainer.

¿Puedo usarlo en desarrollo, no solo en tests?

Sí. Spring Boot permite arrancar la aplicación con los contenedores definidos para tests (SpringApplication.from(...).with(...)), así no necesitas instalar PostgreSQL en tu máquina.

¿Y los tests de repositorio sin arrancar toda la aplicación?

Funciona igual con los tests de slice de JPA. Tienes el resto de tipos de prueba en pruebas de integración en Spring Boot.

Sigue aprendiendo

Las pruebas de integración con Testcontainers forman parte del curso Spring Data JPA 4.1. Para las pruebas unitarias, JUnit 5 y Mockito.

testcontainers spring boot docker postgresql pruebas de integración junit

Newsletter Semanal de Java

Cada viernes recibe lo más nuevo del ecosistema Java: frameworks, herramientas y mejores prácticas.

Sin spam. Cancela cuando quieras.

Compartir artículo