Pruebas de integración de una API Quarkus con PostgreSQL y Testcontainers

Una prueba de integración puede recorrer una API Quarkus por HTTP y comprobar que los datos escritos en PostgreSQL se pueden recuperar. Dev Services ofrece un punto de partida para preparar la base de datos; Testcontainers también permite gestionar un contenedor de PostgreSQL de forma explícita.

Preparar el entorno de prueba

La guía Dev Services for databases describe el arranque automático de una base de datos y su configuración para la aplicación cuando se cumplen las condiciones indicadas en la guía. Antes de aplicarlo, consulta sus apartados sobre activación y selección de imagen, y comprueba la configuración y las dependencias de tu proyecto.

Como alternativa para un control explícito, consulta el módulo PostgreSQL de Testcontainers y el ejemplo de recurso de prueba de la guía de pruebas de Quarkus. La investigación suministrada no incluye los fragmentos originales completos necesarios para reproducir aquí una configuración verificable de ese recurso.

Comprobar el recorrido HTTP

La guía de pruebas de Quarkus presenta una prueba con @QuarkusTest y REST Assured. Sobre la URL, indica que la integración «automatically sets the correct URL».

Como ejemplo hipotético, una prueba de una API de artículos podría seguir estos pasos:

1. Generar un identificador único para el artículo.
2. Enviar una petición a POST /items y comprobar que la respuesta indica creación.
3. Consultar GET /items/{id} y comparar el identificador y el nombre devueltos con los enviados.
4. Intentar eliminar el artículo al terminar, incluso si falla una comprobación anterior.

Estos endpoints y sus respuestas son supuestos, no un contrato proporcionado por Quarkus. Adapta la secuencia, los códigos de estado y los datos al comportamiento real de tu API. La investigación no incluye un proyecto ni una ejecución que verifique este ejemplo.

Aislar los datos y conservar los fallos

Como recomendación práctica, prepara los datos que necesita cada prueba y límpialos después, u ofrece otro mecanismo de aislamiento. Un identificador único ayuda a localizar el registro creado, pero la limpieza por HTTP depende de que exista una operación de borrado adecuada y no cubre una caída del proceso.

Si tanto una comprobación principal como la limpieza fallan, conserva el fallo principal y adjunta el de limpieza como excepción suprimida. Si solo falla la limpieza, propaga ese fallo. Así el diagnóstico muestra ambas causas sin sustituir la primera.

No presupongas que revertir la transacción del método de prueba también revierta una transacción independiente confirmada por un endpoint HTTP. Comprueba el alcance de las transacciones y el mecanismo de aislamiento de tu aplicación.

Ampliar la cobertura al artefacto empaquetado

Si necesitas comprobar también el artefacto que vas a distribuir, revisa la sección sobre @QuarkusIntegrationTest de la guía de pruebas. Antes de reutilizar una prueba HTTP, verifica cómo se inicia la aplicación y qué configuración recibe en esa modalidad.

Límites de este borrador: no se han compilado ni ejecutado los ejemplos, y no se proporcionó un proyecto para verificar dependencias, migraciones o disponibilidad de un runtime de contenedores. La investigación identifica documentación de Quarkus 3.40, pero no incluye los pasajes completos para cotejar todos los detalles de versión y configuración; compruébalos en las guías para la versión que uses.