Cómo ejecutar pruebas automatizadas de API en Bamboo CI (Paso a paso)

Tu compilación está en verde. Las pruebas unitarias pasan, el JAR está empaquetado, el artefacto está desplegado. Entonces la primera solicitud real llega a la API de staging y un servicio descendente devuelve un 500 porque alguien cambió un campo de respuesta dos commits atrás. La compilación decía que todo estaba bien. No lo estaba. Simplemente nunca comprobó la API.

Esta es la brecha que tienen la mayoría de los pipelines de CI de Bamboo. Atlassian Bamboo es bueno compilando código, ejecutando suites JUnit y enviando artefactos. Lo que no hace por sí solo es verificar que tus endpoints HTTP sigan comportándose como promete tu contrato. Si quieres esa red de seguridad, debes añadir pruebas de API automatizadas como una etapa en el pipeline. Esta guía explica exactamente cómo hacerlo, utilizando Apidog para construir las pruebas y la CLI de Apidog para ejecutarlas dentro de un trabajo de Bamboo.

Al final, tendrás un plan de Bamboo que, en cada push, golpea tus endpoints, comprueba los códigos de estado, valida los cuerpos de respuesta contra tu esquema y falla la compilación en el momento en que se rompe un contrato. Sin licencia de Postman por asiento, sin scripts de aserción escritos a mano que mantener, y un informe de prueba HTML real adjunto a cada compilación. Descarga Apidog si quieres seguir los pasos; la parte de la CLI es gratuita y de código abierto.

botón

Por qué las pruebas de API pertenecen a Bamboo, no después

Muchos equipos prueban sus APIs manualmente, o peor aún, en producción. Alguien hace clic en una colección de solicitudes guardadas antes de una versión y revisa las respuestas a ojo. Eso funciona hasta que deja de funcionar. La gente se olvida. Las versiones se lanzan un viernes. El único endpoint que nadie pensó en volver a comprobar es el que se rompe.

CI existe para eliminar esa variable humana. El objetivo principal de un servidor de compilación es que las mismas comprobaciones se ejecuten de la misma manera cada vez, automáticamente, sin que nadie tenga que recordar ejecutarlas. Tus pruebas unitarias ya están allí. Tus pruebas de integración probablemente también lo estén. Las pruebas de API merecen el mismo tratamiento, y por algunas razones concretas:

Los contratos se rompen silenciosamente. Un desarrollador de backend renombra un campo JSON de userId a user_id. Las pruebas unitarias siguen pasando porque prueban la función, no el formato de la transmisión. El equipo móvil se entera tres días después. Una prueba de API que afirma el cuerpo de la respuesta lo detecta en la misma compilación que lo introdujo.
Los códigos de estado mienten cuando nadie los mira. Un endpoint que debería devolver 201 Created comienza a devolver 200 OK después de una refactorización. Funcionalmente cercano, técnicamente incorrecto, y un cliente estricto lo rechazará. Una aserción del pipeline lo marca en segundos.
Las regresiones de autenticación son costosas. Un flujo de actualización de tokens mal configurado que devuelve 401 con credenciales válidas es el tipo de error que derriba una pantalla de inicio de sesión. Ejecutar una solicitud autenticada en cada compilación significa que lo encuentras antes que tus usuarios.
Los entornos se desvían. Staging recibe un cambio de configuración, una característica cambia, una dependencia se actualiza. Ejecutar la misma suite de API contra staging después de cada despliegue te dice inmediatamente si el entorno sigue siendo saludable.

El contexto más profundo es la misma razón por la que los equipos adoptan CI/CD en primer lugar: detectar los problemas a tiempo, cuando son baratos de solucionar, en lugar de tarde, cuando son caros y vergonzosos. Las pruebas de API son solo la capa de esa estrategia que la mayoría de los pipelines omiten.

Cómo encajan las pruebas de API en un plan de Bamboo

Antes del paso a paso, ayuda entender dónde encaja esto en el modelo de Bamboo. Bamboo organiza el trabajo en planes, y cada plan contiene una o más etapas que se ejecutan en orden. Cada etapa contiene trabajos, y cada trabajo es una secuencia de tareas. Las tareas son los comandos reales: checkout, compilar, ejecutar un script.

Tus pruebas de API se convierten en una tarea dentro de un trabajo dentro de una etapa. La ubicación natural es una etapa dedicada que se ejecuta después de que tu aplicación se construye y se despliega en un entorno de prueba, porque necesitas algo en vivo para enviar solicitudes. Un plan típico termina luciendo así:

Plan: servicio-de-pagos
├── Etapa: Construcción
│   └── Trabajo: Compilar y Probar Unitariamente
│       ├── Tarea: Extracción de Código Fuente
│       └── Tarea: Maven, clean package
├── Etapa: Desplegar a Staging
│   └── Trabajo: Despliegue
│       └── Tarea: Desplegar artefacto a staging
└── Etapa: Pruebas de API          <- esto es lo que estás añadiendo
    └── Trabajo: Ejecutar Suite de API
        ├── Tarea: Extracción de Código Fuente
        ├── Tarea: Script, instalar y ejecutar Apidog CLI
        └── Tarea: Final, publicar informe de prueba

Si una tarea en la etapa de Pruebas de API sale con un código distinto de cero, Bamboo marca la etapa como fallida y toda la compilación se pone en rojo. Ese es exactamente el comportamiento que deseas; un contrato roto debe detener la línea, no pasar desapercibido.

La herramienta que realiza el trabajo real en esa tarea de script es la CLI de Apidog, un ejecutor de línea de comandos que ejecuta escenarios de prueba que diseñas visualmente en Apidog. Construyes la prueba una vez, en una GUI, sin código, y la misma prueba se ejecuta sin cambios en tu terminal y en Bamboo. Este es el mismo patrón que los equipos usan para automatizar pruebas de API en cualquier sistema de CI/CD; Bamboo es un objetivo entre muchos.

Paso 1: Construye tus pruebas de API en Apidog

No puedes ejecutar pruebas en CI hasta que tengas pruebas. Apidog es donde las diseñas, y el diseño es visual, por lo que un ingeniero de QA que no escribe código puede construir la misma suite que un desarrollador de backend.

Abre Apidog y crea un escenario de prueba. Un escenario es una secuencia ordenada de solicitudes de API, ejecutadas de arriba a abajo, donde cada paso puede reutilizar datos de los pasos anteriores. Un escenario realista para un servicio de pagos podría ser:

POST /auth/login con credenciales válidas, luego extrae el token de portador de la respuesta.
POST /orders usando ese token, creando un nuevo pedido, luego guarda el orderId devuelto.
GET /orders/{orderId} y confirma que el pedido aparece con el estado correcto.
DELETE /orders/{orderId} para limpiar.

Para cada solicitud, añade aserciones. Esta es la parte que convierte una solicitud en una prueba. Apidog te permite asertar visualmente, sin necesidad de scripts:

El código de estado es igual a 200 (o 201, lo que diga el contrato).
Un campo JSON existe y coincide: $.data.status es igual a "pending".
La respuesta valida contra el esquema OpenAPI del endpoint, por lo que cualquier tipo de campo inesperado o propiedad requerida faltante hace que el paso falle.
El tiempo de respuesta se mantiene por debajo de un umbral, digamos 800ms, para que también se detecte una regresión lenta.

Las aserciones basadas en esquemas merecen ser mencionadas. Como Apidog es "schema-first", ya conoce la forma que tu endpoint prometió en su definición de API. Puedes afirmar "esta respuesta coincide con su esquema" con un solo clic, y esa única comprobación protege contra toda una categoría de desviación de contrato, campos renombrados, tipos incorrectos, propiedades eliminadas, sin que escribas una sola línea. Si vienes de una herramienta con muchos scripts, esto por sí solo elimina mucho mantenimiento. Es el mismo modelo de aserción visual que convierte a Apidog en una alternativa común a Postman para pruebas de API.

Agrupa escenarios relacionados en una suite de pruebas si tienes muchos. Una suite es solo una colección de escenarios que puedes ejecutar juntos, lo que simplifica tu comando de CI; apuntas el ejecutor a una suite en lugar de listar veinte escenarios.

Usa variables de entorno para todo lo que cambia entre local, staging y producción: URLs base, credenciales, claves de API. Define un entorno de staging en Apidog con baseUrl configurado a tu host de staging. Le dirás a la CLI qué entorno usar en tiempo de ejecución, de modo que el mismo escenario se ejecute contra staging en Bamboo y contra localhost en tu laptop.

Paso 2: Genera un token de acceso de Apidog y obtén los IDs

Bamboo se ejecuta sin interfaz gráfica en un agente de compilación. No puede iniciar sesión en tu cuenta de Apidog a través de un navegador, por lo que la CLI se autentica con un token de acceso en su lugar.

Dentro de tu escenario de prueba, abre la pestaña CI/CD. Haz clic en "Añadir token de acceso", luego en "Generar token". Copia el valor en un lugar seguro por un momento; lo almacenarás como una variable de Bamboo en breve, no lo pegarás en un script. El token es lo que permite a un agente de compilación extraer y ejecutar las pruebas de tu proyecto privado.

Mientras estás en esa pestaña CI/CD, Apidog genera el comando de ejecución completo para ti. Selecciona "Command line" como proveedor y te imprimirá algo que puedes copiar directamente, con tu ID de escenario de prueba y tu ID de proyecto ya completados. Ese comando copiado es la base de tu tarea de Bamboo. Las partes que te interesan:

Token de acceso: autenticación, pasado como --access-token.
ID de escenario de prueba: el ID numérico después de -t, que identifica qué escenario ejecutar.
ID de entorno: el ID numérico después de -e, que le indica a la CLI que se ejecute contra staging.

Mantén ese comando generado a mano. Los siguientes pasos lo adaptan para Bamboo.

Paso 3: Almacena el token como una variable de plan de Bamboo

Nunca codifiques un token directamente en una tarea de script. Cualquiera con acceso de lectura al plan, y cualquiera que lea los registros de compilación, lo vería.

En Bamboo, ve a tu plan, abre "Configuración del plan" y busca la pestaña "Variables". Agrega una nueva variable. Nómbrala de forma clara, como APIDOG_ACCESS_TOKEN, y pega el token como valor. Bamboo enmascara las variables cuyos nombres contienen password, secret o token, así que nómbrala en consecuencia y el valor se ocultará en los registros y la interfaz de usuario.

En tiempo de ejecución, Bamboo expone las variables del plan a los scripts como variables de entorno, con prefijo y en mayúsculas, y los puntos se convierten en guiones bajos. Una variable llamada APIDOG_ACCESS_TOKEN estará disponible para tu tarea de shell como $bamboo_APIDOG_ACCESS_TOKEN. Referenciarás eso, nunca el token en bruto, en el script de compilación.

Esta misma higiene se aplica a cualquier otro secreto que necesiten tus pruebas; contraseñas de bases de datos, claves de API de terceros, secretos de firma. Defínelos como variables enmascaradas de Bamboo y léelos a través del prefijo de entorno bamboo_.

Paso 4: Añade la etapa de prueba de API y una tarea de script

Ahora intégralo en el plan. En la configuración del plan, añade una nueva etapa y llámala "API Tests" (Pruebas de API). Añade un trabajo a esta, luego añade tareas al trabajo en este orden.

Tarea 1, "Source Code Checkout" (Extracción de código fuente). Aunque las pruebas residen en la nube de Apidog, extraer tu repositorio le da al agente un directorio de trabajo limpio y te permite guardar cualquier archivo de datos local (datos de iteración CSV, por ejemplo) junto con tu código.

Tarea 2, Script. Este es el corazón de todo. Elige una tarea de Script, establece el intérprete en Shell (o /bin/sh), y usa un cuerpo de script en línea. El script instala la CLI de Apidog en el agente y ejecuta tu escenario.

La CLI de Apidog es un paquete npm, por lo que el agente necesita Node.js v16 o superior. Si tus agentes ya tienen Node, puedes omitir la línea de instalación; si no, provéela a través de las capacidades de Bamboo o un agente basado en Docker. Aquí tienes un cuerpo de script completo:

#!/bin/sh
set -e

# Instala la CLI de Apidog globalmente en el agente
npm install -g apidog-cli

# Ejecuta el escenario de prueba contra staging, genera un informe HTML + CLI
apidog run \
  --access-token "$bamboo_APIDOG_ACCESS_TOKEN" \
  -t 637132 \
  -e 358171 \
  -r cli,html \
  --out-dir ./apidog-reports

Cambia 637132 por tu ID real de escenario de prueba y 358171 por tu ID de entorno de staging, los valores del comando que Apidog generó en el paso 2. Algunas notas sobre lo que hace cada bandera:

--access-token lee la variable enmascarada de Bamboo, para que el secreto nunca aparezca en el script.
-t (abreviatura de --test-scenario) selecciona el escenario a ejecutar. Para ejecutar una suite completa en su lugar, usa --test-suite <id>; para ejecutar una carpeta completa de escenarios, usa -f <folderId>.
-e (--environment) selecciona el entorno de staging que definiste en Apidog, para que las solicitudes vayan al host correcto con las variables correctas.
-r cli,html (--reporters) produce tanto un informe de consola que verás en el registro de compilación de Bamboo como un informe HTML que puedes publicar como un artefacto. La CLI también admite los formatos json y junit aquí.
--out-dir controla dónde se guardan los informes. El valor predeterminado es ./apidog-reports; establecerlo explícitamente hace que la ruta del artefacto sea predecible.

El set -e al principio importa. Hace que el shell salga en el primer comando que falla. La CLI de Apidog ya devuelve un código de salida distinto de cero cuando cualquier aserción falla, y ese código distinto de cero es lo que le dice a Bamboo que falle la compilación. Juntos garantizan que un contrato de API roto ponga la compilación en rojo en lugar de quedar enterrado en los registros.

Si ya has conectado pruebas de API a GitHub Actions, esto te resultará familiar; el ejecutor y las banderas son idénticos, solo difiere la envoltura de YAML frente a la UI de Bamboo.

Paso 5: Publica el informe de prueba como un artefacto de Bamboo

Una compilación en rojo te indica que algo falló. El informe HTML te dice qué falló. Configúralo para que cada compilación conserve el informe.

En el mismo trabajo, ve a la pestaña "Artifacts" (Artefactos) y define un nuevo artefacto compartido:

Nombre: Apidog Test Report (Informe de prueba de Apidog)
Ubicación: apidog-reports
Patrón de copia: **/*

Después de cada compilación, Bamboo recopila todo lo que hay en el directorio apidog-reports y lo adjunta al resultado de la compilación. Abre cualquier compilación, ve a la pestaña "Artifacts" y podrás descargar o ver el informe HTML; resultados solicitud por solicitud, las aserciones que se ejecutaron y el cuerpo exacto de la respuesta para cualquier cosa que fallara. Esa última parte ahorra un tiempo de depuración real. En lugar de volver a ejecutar la solicitud fallida manualmente, lees la respuesta capturada directamente de la compilación.

Para una visualización más enriquecida en Bamboo, el reportero junit también es útil. Añade junit a la lista de -r, luego añade una tarea de "JUnit Parser" apuntando al archivo XML de JUnit. Bamboo luego renderiza los recuentos de pruebas, desgloses de aprobado/fallido y tendencias de fallos de forma nativa en el resumen de la compilación, de la misma manera que muestra los resultados de tus pruebas unitarias.

Paso 6: Ejecútalo y lee el resultado

Activa el plan manualmente para la primera ejecución; en Bamboo, "Run plan" desde la página del plan. Observa el registro de compilación para la etapa "API Tests". Verás npm instalar la CLI, luego la salida de ejecución de Apidog fluir, el nombre del escenario, cada solicitud, cada aserción y una línea de resumen final con los totales.

Dos resultados:

Todas las aserciones pasan. La CLI sale con 0, la etapa se pone en verde, la compilación tiene éxito y el informe HTML se adjunta como un artefacto de todos modos, para que tengas un registro. Bien. Ahora hazlo automático; configura el plan para que se active en cada commit a tu rama principal (Configuración del plan, "Triggers", "Repository polling" o un webhook). A partir de ahora, cada push ejecuta tu suite de API con cero intervención humana.

Una aserción falla. La CLI sale con un código distinto de cero, set -e detiene el script, la etapa se pone en rojo y la compilación falla. Abre el artefacto, busca la solicitud fallida y lee la respuesta capturada. Tal vez un campo cambió. Tal vez staging devolvió un 502 porque una dependencia está caída. De cualquier manera, lo sabrás en uno o dos minutos después del commit que lo introdujo, que es la recompensa completa.

Un resumen de consola realista se ve así:

┌──────────────┬──────────┬──────────┐
│              │ ejecutado │   fallido │
├──────────────┼──────────┼──────────┤
│   iteraciones │        1 │        0 │
├──────────────┼──────────┼──────────┤
│     solicitudes │        4 │        0 │
├──────────────┼──────────┼──────────┤
│   aserciones │       11 │        1 │
└──────────────┴──────────┴──────────┘

  1 aserción fallida:
    GET /orders/{orderId}
      se esperaba que $.data.status fuera "pending" pero se obtuvo "failed"

Esa aserción fallida es la razón de ser de toda la etapa. Detectó una regresión de contrato que se compiló limpiamente y pasó todas las pruebas unitarias.

Haciendo la suite confiable en CI

Una prueba de API inestable es peor que ninguna prueba, porque entrena al equipo a ignorar las compilaciones en rojo. Algunos hábitos mantienen la suite confiable.

Aísla los datos de prueba. Cada ejecución debe crear lo que necesita y limpiarse a sí misma, como el flujo de creación y eliminación de pedidos anterior. Las pruebas que dependen de un registro creado por alguien el martes pasado se romperán en el momento en que ese registro cambie. Ejecuta contra un entorno de staging o prueba dedicado, nunca contra producción.

Utiliza ejecuciones basadas en datos para la cobertura sin duplicación. Si necesitas probar el mismo endpoint con veinte entradas diferentes, no construyas veinte escenarios. Usa un solo escenario con --iteration-data path/to/data.csv (o -d), y la CLI lo ejecutará una vez por fila. Sube el CSV a tu repositorio para que se extraiga con el código. Este es el mismo patrón de prueba basado en datos que usarías localmente, solo que impulsado por un archivo en CI.

Fija la versión de la CLI. npm install -g apidog-cli obtiene la última. Para compilaciones reproducibles, fija una versión conocida, npm install -g apidog-cli@<version>, para que una actualización de la CLI no cambie silenciosamente el comportamiento entre dos compilaciones del mismo commit.

Establece tiempos de espera sensibles. Añade --timeout-request 10000 para fallar rápidamente en un endpoint colgado en lugar de dejar que la compilación se quede colgada hasta que el propio tiempo de espera de Bamboo la detenga. Un claro "la solicitud ha agotado el tiempo de espera" es mejor que una compilación estancada vaga.

Controla los despliegues en la etapa de API. Dado que la etapa de "API Tests" se ejecuta antes de cualquier etapa de despliegue a producción, y una etapa fallida detiene el plan, un contrato roto no puede llegar a producción. Ese orden es tu puerta de lanzamiento. Es la versión práctica de construir un pipeline de CI/CD real en lugar de una compilación que solo compila.

Mantén los escenarios rápidos y enfocados. Una suite de CI que tarda veinte minutos no se ejecutará en cada commit; la gente la moverá a nocturna y perderá la retroalimentación rápida. Mantén la suite por commit en tus rutas críticas, autenticación, CRUD central, flujo de pago, y ejecuta la suite exhaustiva de casos extremos en un horario.

Conclusión

Bamboo ya te protege del código que no compila y de las pruebas unitarias que no pasan. Añadir una etapa de pruebas de API extiende esa protección a los contratos que tus servicios realmente exponen a través de la red, la capa donde se producen la mayoría de los incidentes de "pero funcionaba localmente".

La configuración es sencilla: construye pruebas visuales y conscientes del esquema en Apidog, genera un token de acceso, almacénalo como una variable enmascarada de Bamboo, y añade una tarea de script que ejecute apidog run con tu escenario y IDs de entorno. Publica el informe como un artefacto, protege tu etapa de despliegue con él y activa el plan en cada commit. Después de eso, es automático. Cada push verifica tu API, y un contrato roto pone la compilación en rojo antes de que pueda convertirse en una interrupción.

Descarga Apidog y construye tu primer escenario de prueba, luego pega el comando de la CLI generado en una tarea de script de Bamboo. La primera vez que detecte una regresión que se compiló limpiamente, la etapa habrá valido la pena por los diez minutos que tardaste en configurarla.

botón