Cómo automatizar pruebas de API en Travis CI con Apidog CLI

Tu API funciona en tu máquina. Las pruebas unitarias están en verde. Fusionas, despliegas, y una hora más tarde un compañero te avisa: el endpoint /checkout está devolviendo un 500 para cualquiera con un carrito vacío. El error nunca estuvo en el código que cambiaste; estaba en un contrato a dos servicios de distancia que nadie volvió a probar. Esta es la brecha que llenan las pruebas de API a nivel de integración, y es exactamente el tipo de verificación que quieres que se ejecute automáticamente en cada commit en lugar de depender de la memoria de alguien.

Travis CI es uno de los servicios de integración continua alojados más antiguos, y aún hace bien una cosa: vigila tu repositorio Git, levanta un entorno limpio para cada push y pull request, y ejecuta los comandos que pongas en un archivo .travis.yml. La mayoría de los equipos lo usan para bucles de compilación y pruebas unitarias. Muchos menos lo usan para ejecutar pruebas HTTP reales contra una API en ejecución, a pesar de que ahí es donde se esconden los errores costosos. La razón es la fricción. Conectar un ejecutor de pruebas de API a una caja de CI, pasar secretos de forma segura y obtener una señal de aprobado/fallido es lo suficientemente complicado como para que la gente lo omita.

Esta guía te mostrará cómo cerrar esa brecha con el ejecutor de línea de comandos de Apidog. Diseñas y depuras tus pruebas de API en la aplicación de escritorio de Apidog, donde puedes ver las solicitudes y aserciones visualmente, y luego ejecutas exactamente las mismas pruebas sin interfaz gráfica dentro de Travis CI con un solo comando. Sin reescribir la lógica de las pruebas como código, sin mantener un arnés de pruebas separado. El artículo cubre la ruta completa: un .travis.yml mínimo, la instalación del ejecutor, el paso seguro de tu token de acceso, la elección de qué ejecutar, la generación de informes y cómo hacer que la compilación falle ruidosamente cuando un endpoint se rompe. Descarga Apidog si quieres seguir la guía.

Por qué ejecutar pruebas de API en CI

Las pruebas unitarias confirman que una función devuelve el valor correcto. Las pruebas de API confirman que todo el ciclo de solicitud-respuesta se comporta correctamente: la ruta existe, la autenticación se aplica, el código de estado es correcto, el esquema JSON coincide y los valores dentro del cuerpo son coherentes. Estos son modos de fallo diferentes, y el segundo tipo es el que realmente experimentan tus usuarios.

Ejecutarlos localmente está bien hasta que deja de estarlo. Las ejecuciones locales dependen de que te acuerdes de ejecutarlas, de que tu máquina coincida con la configuración de producción y de que no estés a mitad del café cuando se cuela una regresión. La integración continua elimina las tres excusas. Cada push dispara la misma suite en el mismo entorno, y el resultado se adjunta al commit y a la pull request para que todos lo vean.

Hay una recompensa más profunda específicamente para los equipos de API. Cuando tus pruebas conviven con tu diseño de API, un cambio que rompe la funcionalidad aparece como una aserción fallida en el momento en que se envía, no como un ticket de soporte. Si quieres el contexto conceptual de dónde encaja esto en una pipeline de entrega, el explicador qué es CI/CD es una buena lectura complementaria; este artículo se centra en la construcción práctica de Travis CI.

Qué necesitas antes de empezar

Tres cosas, y probablemente ya tengas dos de ellas.

• Un repositorio Git conectado a Travis CI. El nivel gratuito en travis-ci.com funciona para repositorios públicos y privados dentro de los límites de uso.

• Un proyecto de Apidog con al menos un escenario de prueba que ya hayas construido y ejecutado con éxito en la aplicación de escritorio. Un escenario de prueba en Apidog es un conjunto ordenado de solicitudes de API con aserciones; piénsalo como un flujo de extremo a extremo, como "iniciar sesión, crear un pedido, obtener el pedido, eliminarlo".
• Node.js. La CLI de Apidog se ejecuta en Node, y necesita la versión 16 o posterior. Travis proporciona Node de forma predeterminada en el entorno de lenguaje node_js, por lo que esto es principalmente una declaración de una sola línea.

Si aún no has construido un escenario de prueba, hazlo primero en la aplicación. Todo el sentido de este flujo de trabajo es que depures visualmente una vez, y luego automatices para siempre. Intentar crear pruebas a ciegas dentro de un registro de CI es el camino lento. Para los fundamentos de cómo escribir buenas comprobaciones, Aserciones de API: una guía práctica cubre cómo validar códigos de estado, cuerpos de respuesta y esquemas JSON antes de hacer cualquier push.

Paso 1: Obtén tu token de acceso y el ID del escenario

La CLI de Apidog ejecuta tus pruebas almacenadas en la nube sin interfaz gráfica, por lo que necesita dos elementos de identidad:

1. Un token de acceso que demuestre que el ejecutor tiene permiso para leer tu proyecto. Genéralo desde la configuración de tu cuenta de Apidog en tokens de acceso. Trátalo como una contraseña; otorga acceso a la API a los datos de tu proyecto.
2. Un ID de escenario de prueba. Abre el escenario en la aplicación de escritorio y copia su ID, o usa la opción "Ejecutar en CI/CD", que genera un comando listo con el ID ya rellenado.

La forma más fácil de obtener un primer comando correcto es dejar que Apidog lo escriba por ti. Dentro de un escenario de prueba, la opción de ejecución de CI/CD produce algo como esto:

apidog run --access-token <tu-token-de-acceso> -t 5564321 -e 4417023 -r cli

Esa es la forma completa: autenticar, apuntar a un escenario (-t), apuntar a un entorno (-e) y elegir un reportero (-r). Cópialo, confirma que se ejecuta primero en tu propia computadora portátil y solo entonces muévelo a Travis. Verificar localmente te ahorra una docena de compilaciones fallidas dedicadas a depurar un error tipográfico en un token.

Paso 2: Almacena el token como una variable cifrada de Travis

Nunca pegues tu token de acceso en .travis.yml. Ese archivo se envía a Git, y un token filtrado le da a cualquiera acceso de lectura a tu proyecto de API. Travis tiene dos opciones seguras.

La forma limpia son las variables de entorno del repositorio configuradas en la interfaz de usuario web de Travis. Ve a la configuración de tu repositorio en Travis, busca las variables de entorno y añade:

• APIDOG_ACCESS_TOKEN con el valor de tu token
• APIDOG_ENV_ID con el ID del entorno contra el que quieres probar

Deja la opción "mostrar valor en el registro de compilación" desactivada para que el token nunca se imprima. Travis los inyecta en cada compilación como variables de entorno reales, y tu configuración los referencia por su nombre. Esto mantiene los secretos completamente fuera del repositorio, que es el comportamiento que deseas; si un colaborador bifurca el repositorio, tu token no lo acompaña.

Si prefieres que todo esté en el archivo, Travis también admite variables cifradas a través de su CLI:

travis encrypt APIDOG_ACCESS_TOKEN="tu-token-aquí" --add env.global

Esto escribe un fragmento cifrado en .travis.yml que solo la compilación de tu repositorio puede descifrar. Cualquiera de los dos enfoques funciona. La ruta de la interfaz de usuario es más simple para la mayoría de los equipos y más fácil de rotar cuando un token expira.

Paso 3: Escribe el .travis.yml

Aquí tienes una configuración completa y mínima que instala la CLI de Apidog y ejecuta un escenario en cada push y pull request:

language: node_js
node_js:
  - "18"

cache:
  npm: true

install:
  - npm install -g apidog-cli

script:
  - apidog run --access-token $APIDOG_ACCESS_TOKEN -t 5564321 -e $APIDOG_ENV_ID -r cli

Tres bloques hacen el trabajo. language: node_js con una versión te proporciona un entorno de ejecución de Node lo suficientemente nuevo para la CLI. El paso install instala apidog-cli globalmente para que el comando apidog esté en la ruta. El paso script ejecuta tus pruebas. El reportero -r cli imprime un resumen de aprobado/fallido legible directamente en el registro de Travis, que es lo que mirarás cuando algo falle.

Observa que el ID del escenario está codificado, pero los secretos provienen de variables de entorno. Esa es la división correcta: el ID no es sensible, el token sí. Envía este archivo, haz un push, y Travis ejecutará tus pruebas de API automáticamente. La primera compilación en verde es el momento en que tu API obtiene una red de seguridad.

Si mantienes varios servicios y quieres un modelo mental compartido entre los ejecutores, el tutorial automatizar pruebas de API en CI/CD muestra el mismo patrón aplicado a otras plataformas, y la versión para GitHub Actions es casi idéntica en espíritu si alguna vez migras.

Paso 4: Haz que la compilación falle cuando una prueba falla

Esta es la parte que los equipos olvidan, y que silenciosamente anula todo el ejercicio. Un trabajo de CI solo es útil si una prueba fallida pone la compilación en rojo. Si el ejecutor sale con cero sin importar qué, has construido una impresora de logs muy cara.

Buenas noticias: la CLI de Apidog ya hace lo correcto. Cuando una aserción falla, el proceso apidog run sale con un código de estado distinto de cero, y Travis trata cualquier salida distinta de cero en la fase script como un fallo de compilación. Así que la configuración mínima anterior ya falla correctamente de forma predeterminada. No necesitas pegamento adicional.

Lo que sí puedes ajustar es cómo se comporta la ejecución a mitad del escenario cuando una única solicitud falla. La bandera --on-error controla esto:

• --on-error end detiene el escenario en el primer fallo. Retroalimentación más rápida, menos salida.
• --on-error continue ejecuta los pasos restantes para que veas todos los fallos en una sola pasada.
• --on-error ignore continúa y no permite que los errores detengan la ejecución.

Para CI, continue suele ser el punto óptimo: quieres una imagen completa de lo que falló sin que el trabajo se detenga después de la primera aserción roja, mientras que sigue terminando con una salida no nula para que la compilación falle. Una línea de script razonable se ve así:

script:
  - apidog run --access-token $APIDOG_ACCESS_TOKEN -t 5564321 -e $APIDOG_ENV_ID -r cli --on-error continue

Evita la tentación de añadir || true al comando para "hacer que la compilación pase". Eso ignora el código de salida y reintroduce el mismo punto ciego que intentabas eliminar.

Paso 5: Generar y conservar un informe HTML

El reportero cli está bien para un vistazo rápido, pero cuando una compilación falla, a menudo deseas un artefacto más rico: qué solicitud, qué aserción, cuál fue el cuerpo de respuesta real. La CLI genera un informe HTML con el reportero html, y puedes apilar reporteros en una sola ejecución.

script:
  - apidog run --access-token $APIDOG_ACCESS_TOKEN -t 5564321 -e $APIDOG_ENV_ID -r cli,html --out-dir ./apidog-reports

-r cli,html imprime en el registro y escribe un archivo HTML independiente. --out-dir establece dónde se guarda el informe, con un valor predeterminado de ./apidog-reports. Para que ese informe sobreviva después de que finalice la compilación, despliégalo en algún lugar donde Travis pueda publicarlo, como un bucket S3 o GitHub Pages, en un bloque deploy. Un patrón común:

deploy:
  provider: pages
  skip_cleanup: true
  github_token: $GITHUB_TOKEN
  local_dir: apidog-reports
  on:
    branch: main

Si prefieres no gestionar el almacenamiento de artefactos en absoluto, la CLI puede subir el informe a la nube de Apidog con --upload-report, donde tu equipo podrá abrirlo desde un enlace sin necesidad de alojamiento adicional. Esa es la opción de menor mantenimiento para equipos distribuidos.

Paso 6: Añade entornos, datos y ejecuciones matriciales

Un escenario único contra un entorno único es un buen comienzo. Los pipelines reales crecen en tres direcciones, y las banderas de la CLI se asignan limpiamente a cada una.

Múltiples entornos. La bandera -e selecciona qué URLs base y variables del entorno usar. Ejecuta el mismo escenario contra el entorno de staging en cada push y contra producción en una compilación nocturna programada, simplemente intercambiando el ID del entorno. Los trabajos programados de Travis se configuran por repositorio en la interfaz de usuario de configuración.

Ejecuciones basadas en datos. La bandera -d (forma larga --iteration-data) alimenta un archivo CSV o JSON a tu escenario para que se ejecute una vez por fila. Así es como cubres los casos límite: entrada válida, campos faltantes, cargas útiles sobredimensionadas, caracteres especiales, todo desde una única definición de escenario. Combínala con -n (--iteration-count) cuando quieras un número fijo de repeticiones en lugar de iteraciones impulsadas por archivos.

apidog run --access-token $APIDOG_ACCESS_TOKEN -t 5564321 -e $APIDOG_ENV_ID -d ./test-data.csv -r cli

Escenarios paralelos. Las matrices de compilación de Travis te permiten ejecutar varios escenarios a la vez en trabajos paralelos. Define una matriz de variables de entorno donde cada entrada tenga un ID de escenario diferente, y cada trabajo de la matriz ejecute uno. La compilación solo se pone en verde cuando todos ellos pasan.

env:
  - SCENARIO_ID=5564321   # flujo de pago
  - SCENARIO_ID=5564322   # flujo de autenticación
  - SCENARIO_ID=5564323   # flujo de búsqueda

script:
  - apidog run --access-token $APIDOG_ACCESS_TOKEN -t $SCENARIO_ID -e $APIDOG_ENV_ID -r cli

A medida que las suites crecen, organizar los escenarios en suites de pruebas para pruebas de API automatizadas mantiene la matriz manejable en lugar de convertirse en una pared de IDs.

Por qué esto supera la codificación manual de pruebas en tu script de CI

Podrías escribir pruebas de API directamente en un script de Travis con curl y jq, o como una ejecución de Newman de una colección exportada. Ambos funcionan, y ambos envejecen mal.

El enfoque de curl más shell convierte cada aserción en una comparación de cadenas frágil. Comprobar un campo JSON anidado se convierte en un encantamiento de jq; comprobar un esquema es básicamente imposible; y en el momento en que tu API añade un campo, la mitad de tus greps necesitan ser reescritos. Terminas manteniendo una segunda copia, peor, de tu conocimiento de API en Bash.

El enfoque de ejecutor de colecciones es mejor, pero acopla tu CI a un ritual de exportación y sincronización: editas pruebas en una herramienta, exportas, envías el JSON, y esperas que no se haya desviado de la realidad. La desviación es real, y es la fuente de las quejas de "las pruebas pasan pero la API está rota". Hemos escrito sobre este modo de fallo exacto en por qué tus colecciones de Postman no son una fuente de verdad, y si hoy ejecutas colecciones en CI, cómo ejecutar colecciones de Postman en CI sin Newman cubre el camino de migración.

El modelo Apidog cierra el ciclo. Tus pruebas, tu diseño de API, tus entornos y tus servidores simulados viven en un solo lugar. La CLI ejecuta la versión en vivo y actual de esas pruebas; no hay nada que exportar ni nada que se desvíe. Depuras una aserción inestable visualmente en la aplicación, guardas, y la siguiente ejecución de CI recoge el cambio. Esa única fuente de verdad es la razón principal para usar un ejecutor diseñado para ello en lugar de un montón de scripts de shell. Si lo estás evaluando frente a tu configuración actual, el resumen de las mejores alternativas a Postman para pruebas de API compara las opciones.

Una nota sobre Travis CI específicamente

Travis fue el CI de código abierto predeterminado durante años, y muchos repositorios antiguos todavía lo usan. Si empiezas de cero en 2026, vale la pena saber que el campo ha cambiado; GitHub Actions, GitLab CI y CircleCI ahora manejan la mayoría de los proyectos nuevos, y nuestra comparación de las mejores herramientas de CI/CD desglosa dónde encaja cada una. La buena noticia es que la CLI de Apidog es independiente de la plataforma por diseño. El mismo comando apidog run que funciona en tu .travis.yml funciona en un paso de GitHub Actions, en un .gitlab-ci.yml de GitLab o en una etapa de Jenkins. Si alguna vez te cambias de Travis, tus pruebas de API se mueven contigo sin cambios; solo las claves YAML circundantes difieren. Esa portabilidad es un beneficio silencioso pero real de mantener la lógica de las pruebas fuera de la sintaxis específica de CI.

Preguntas frecuentes

¿Necesito instalar la aplicación de escritorio de Apidog en el servidor de CI? No. La aplicación de escritorio es para diseñar y depurar pruebas. Travis solo necesita el paquete npm apidog-cli y un entorno de ejecución de Node 16+ o superior, que el entorno de lenguaje node_js ya proporciona. La CLI recupera y ejecuta tus escenarios almacenados en la nube sin interfaz gráfica.

¿Dónde encuentro mi token de acceso y el ID del escenario? Genera el token de acceso en la configuración de tu cuenta de Apidog, en la sección de tokens de acceso. El ID del escenario es visible en la aplicación de escritorio en cada escenario de prueba; la opción integrada "Ejecutar en CI/CD" también genera un comando completo con el ID pre-rellenado, que es la forma más rápida de obtener una base de trabajo.

¿Cómo mantengo el token fuera de mi repositorio? Configúralo como una variable de entorno del repositorio en la interfaz de usuario web de Travis con la visualización del registro de compilación desactivada, luego haz referencia a ella como $APIDOG_ACCESS_TOKEN en tu configuración. Alternativamente, usa travis encrypt para almacenar un valor cifrado en .travis.yml. Nunca hagas commit del token sin cifrar.

¿Fallará realmente la compilación si una prueba falla? Sí. El comando apidog run sale con un valor distinto de cero cuando una aserción falla, y Travis trata cualquier salida distinta de cero en la fase script como una compilación fallida. Simplemente no suprimas el código de salida con || true. Usa --on-error continue si quieres que se informe de cada fallo en una sola ejecución mientras la compilación sigue fallando.

¿Puedo ejecutar pruebas en múltiples entornos o con múltiples conjuntos de datos? Sí. Usa -e para cambiar de entorno (staging en el push, producción en una tarea programada nocturna), -d para alimentar un archivo de datos CSV o JSON para iteraciones basadas en datos, y una matriz de compilación de Travis para ejecutar varios escenarios en trabajos paralelos.

¿Puedo usar esto si no estoy en Travis CI? Sí. El comando CLI es idéntico en todas las plataformas. Cambia el YAML circundante para GitHub Actions, GitLab CI o Jenkins y la línea apidog run permanece igual.

Conclusión

Integrar pruebas de API en Travis CI se reduce a cuatro pasos: almacenar tu token de acceso como una variable cifrada, instalar apidog-cli en el paso de instalación, ejecutar tu escenario con apidog run en el paso de script y dejar que el código de salida no nulo falle la compilación. A partir de ahí, añades informes HTML, múltiples entornos, iteraciones basadas en datos y una matriz paralela a medida que tu suite crece.

La razón para hacerlo con un ejecutor dedicado en lugar de una pared de llamadas curl es la fuente única de verdad. Diseñas y depuras visualmente, luego ejecutas la versión en vivo de esas pruebas exactas en cada commit, sin ningún paso de exportación que pueda desincronizarse. Tu regresión de /checkout se detecta en la pull request, no en producción.

Crea tu primer escenario de prueba, luego descarga Apidog y conéctalo a tu próximo push. Una vez que la primera compilación esté en verde, cada commit posterior se enviará con una red de seguridad.