Escribiste las pruebas de API. Pasan en tu máquina. Y ahí es exactamente donde se quedan, porque ejecutarlas es algo que alguien tiene que recordar hacer. Un compañero de equipo implementa un cambio un viernes por la tarde, el endpoint de autenticación comienza a devolver un 500 silenciosamente en una ruta de código, y la primera persona en enterarse es un usuario el lunes. La cobertura estuvo ahí todo el tiempo. Nadie la ejecutó en el momento en que habría detectado la regresión.
La solución es mover las pruebas de tu editor a la pipeline, para que se ejecuten en cada push sin intervención humana. Eso significa que necesitas un comando que ejecute tus pruebas de API de forma desatendida, que devuelva un resultado claro de aprobado o fallido, y que encaje en cualquier sistema de CI que ya utilices. La CLI de Apidog hace eso. Creas tus escenarios de prueba visualmente en Apidog, luego los ejecutas desde un solo comando de terminal que cualquier runner de CI con Node.js puede ejecutar. Sin interfaz gráfica, sin reescribir pruebas como código, sin servicio adicional que alojar.
Esta es una guía de copiar y pegar. A continuación, encontrarás archivos de pipeline listos para usar para GitHub Actions, GitLab CI, Jenkins, CircleCI y Azure Pipelines, además de los patrones que mantienen una compilación limpia. Toma el bloque para tu plataforma, intercambia tus IDs y un secreto, y tendrás pruebas de API bloqueando cada fusión al final del día. Si prefieres la referencia exhaustiva de banderas, el tema más amplio de cómo automatizar pruebas de API en CI/CD cubre la estrategia; esta página trata de pegar una pipeline funcional.
Qué estás conectando
La CLI de Apidog es un paquete npm, apidog-cli. Ejecuta los escenarios de prueba que creas en la aplicación Apidog: solicitudes encadenadas, aserciones, valores extraídos de una respuesta a la siguiente, iteración basada en datos. La CLI no inventa su propio formato de prueba. Accede a tu proyecto, encuentra el escenario por ID, lo ejecuta de la misma manera que lo haría la aplicación y reporta con un código de salida.
Ese código de salida es el punto clave. Cuando todas las aserciones pasan, la ejecución sale con 0. Cuando algo falla, sale con un valor distinto de cero. Los sistemas de CI leen ese código de salida, marcan el paso como fallido y bloquean la fusión o el despliegue. No configuras una puerta; la puerta es el código de salida. Mientras el paso apidog run esté en tu pipeline, una aserción fallida detiene la línea.
Tres cosas hacen que una ejecución funcione, y las verás en cada bloque a continuación:
- Un token de acceso, que demuestra que la ejecución está autorizada para ejecutar tu escenario. Trátalo como una contraseña. Almacénalo como un secreto de CI, nunca en un archivo versionado.
- Un ID de escenario (o ID de carpeta, o ID de suite de pruebas), que indica qué ejecutar.
- Un ID de entorno, que indica dónde ejecutarlo: desarrollo, staging o producción.
No escribes esos IDs a mano. Abre el escenario de prueba en Apidog, ve a su pestaña CI/CD, elige la opción de línea de comandos y genera un token de acceso. Apidog te entrega el comando completo apidog run con el ID de escenario y el ID de entorno ya completados. Cópialo una vez, luego mueve el token a un secreto. Si aún no has creado un escenario, comienza con cómo escribir escenarios de prueba con Apidog y vuelve cuando tengas uno que pase.
El único comando en el que se basa todo
Aquí está la ejecución canónica. Cada archivo de pipeline es un envoltorio alrededor de esta línea:
apidog run \
--access-token $APIDOG_ACCESS_TOKEN \
-t 605067 \
-e 1629989 \
-n 1 \
-r html,junit \
--out-dir ./apidog-reports
Lo que hace cada parte:
--access-tokenautentica la ejecución. Lee de la variable de entorno$APIDOG_ACCESS_TOKEN, que se rellena desde un secreto.-t 605067ejecuta el escenario de prueba con ese ID. Cambia-tpor-f <folderId>para ejecutar una carpeta completa, o--test-suite <id>para ejecutar una suite seleccionada.-e 1629989apunta a un entorno. Así es como el mismo escenario llega a staging en una verificación de PR y a producción en una prueba de humo post-despliegue.-n 1ejecuta el escenario una vez. Auméntalo para hacer un bucle, o combínalo con-d <file>para impulsar iteraciones desde un archivo de datos CSV o JSON.-r html,junitselecciona los formatos de informe.junitemite el XML que tu panel de CI analiza en un árbol de aprobado/fallido;htmles un informe navegable que guardas como un artefacto de construcción. Añadeclisi también quieres una salida legible en el registro.--out-dir ./apidog-reportses donde se guardan los informes.
Los reportes son la diferencia entre "la compilación falló" y "aquí está la aserción que falló y la respuesta que la rompió". JUnit XML es el que casi todas las plataformas entienden de forma nativa, por lo que aparece en los cinco bloques siguientes.
GitHub Actions
Pega esto en .github/workflows/api-tests.yml. Ejecuta tu escenario en cada solicitud de extracción contra main, sube el informe como un artefacto y falla la verificación si alguna aserción falla.
name: API tests
on:
pull_request:
branches: [main]
jobs:
api-tests:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Set up Node.js
uses: actions/setup-node@v4
with:
node-version: '20'
- name: Install Apidog CLI
run: npm install -g apidog-cli
- name: Run API test scenario
run: |
apidog run \
--access-token "$APIDOG_ACCESS_TOKEN" \
-t 605067 \
-e 1629989 \
-n 1 \
-r html,junit \
--out-dir ./apidog-reports
env:
APIDOG_ACCESS_TOKEN: ${{ secrets.APIDOG_ACCESS_TOKEN }}
- name: Upload report
if: always()
uses: actions/upload-artifact@v4
with:
name: apidog-report
path: ./apidog-reports
Dos detalles importantes. El token reside en Configuración → Secretos y variables → Acciones como APIDOG_ACCESS_TOKEN y llega al paso a través de env:. Y if: always() en el paso de carga significa que aún obtendrás el informe cuando las pruebas fallen, que es la única vez que realmente necesitas leerlo. Si un escenario falla, el paso apidog run sale con un valor distinto de cero, el trabajo se pone en rojo y la PR muestra una verificación fallida. Para una explicación más detallada de esta plataforma específicamente, consulta cómo automatizar pruebas de API en GitHub Actions.
GitLab CI
La misma idea en .gitlab-ci.yml. La imagen node:20 ya tiene el tiempo de ejecución, por lo que la única configuración es la instalación.
stages:
- test
api-tests:
stage: test
image: node:20
script:
- npm install -g apidog-cli
- >
apidog run
--access-token "$APIDOG_ACCESS_TOKEN"
-t 605067
-e 1629989
-r junit,cli
--out-dir ./apidog-reports
artifacts:
when: always
paths:
- apidog-reports/
reports:
junit: apidog-reports/*.xml
Almacena APIDOG_ACCESS_TOKEN en Configuración → CI/CD → Variables como una variable enmascarada y protegida para que nunca se imprima en un registro. El bloque reports: junit: es la parte que los usuarios de GitLab suelen pasar por alto: le indica a GitLab que analice el XML y muestre los resultados directamente en el widget de la solicitud de fusión. Un revisor ve qué aserciones fallaron sin descargar nada.
Jenkins
Para una pipeline declarativa, almacena el token como una credencial de Jenkins e incorpóralo al entorno, luego llama a la CLI en una etapa. El bloque post alimenta el XML de JUnit a los gráficos de tendencias de pruebas de Jenkins y mantiene el informe HTML en la compilación.
pipeline {
agent any
environment {
APIDOG_ACCESS_TOKEN = credentials('apidog-access-token')
}
stages {
stage('API tests') {
steps {
sh 'npm install -g apidog-cli'
sh '''
apidog run \
--access-token $APIDOG_ACCESS_TOKEN \
-t 605067 \
-e 1629989 \
-n 1 \
-r html,junit \
--out-dir apidog-reports
'''
}
}
}
post {
always {
junit 'apidog-reports/*.xml'
archiveArtifacts artifacts: 'apidog-reports/**', allowEmptyArchive: true
}
}
}
Si tus agentes de compilación ya tienen la CLI en caché, elimina la línea npm install y llama a apidog run directamente. Apidog también ofrece una guía de integración específica para Jenkins si prefieres la ruta del plugin en lugar de un paso de shell: integrar pruebas automatizadas de Apidog con Jenkins para CI/CD.
CircleCI
En .circleci/config.yml, usa la imagen de conveniencia de Node y almacena el token como una variable de entorno del proyecto en Configuración del proyecto → Variables de entorno.
version: 2.1
jobs:
api-tests:
docker:
- image: cimg/node:20.11
steps:
- checkout
- run:
name: Install Apidog CLI
command: npm install -g apidog-cli
- run:
name: Run API test scenario
command: |
apidog run \
--access-token "$APIDOG_ACCESS_TOKEN" \
-t 605067 \
-e 1629989 \
-r junit,cli \
--out-dir ./apidog-reports
- store_test_results:
path: ./apidog-reports
- store_artifacts:
path: ./apidog-reports
destination: apidog-reports
workflows:
test:
jobs:
- api-tests
store_test_results es el equivalente de CircleCI al bloque JUnit de GitLab; apúntalo al directorio de informes y CircleCI mostrará las aserciones fallidas en su pestaña de Pruebas. store_artifacts mantiene el informe HTML adjunto para que puedas abrirlo desde la página de compilación.
Azure Pipelines
En azure-pipelines.yml, instala Node con la tarea, ejecuta la CLI y publica los resultados de JUnit. Añade APIDOG_ACCESS_TOKEN como una variable secreta en la pipeline (o extráelo de un grupo de variables de Azure Key Vault), luego mapealo al env del paso de script.
trigger:
- main
pool:
vmImage: ubuntu-latest
steps:
- task: NodeTool@0
inputs:
versionSpec: '20.x'
displayName: 'Install Node.js'
- script: npm install -g apidog-cli
displayName: 'Install Apidog CLI'
- script: |
apidog run \
--access-token "$APIDOG_ACCESS_TOKEN" \
-t 605067 \
-e 1629989 \
-r junit,html \
--out-dir ./apidog-reports
displayName: 'Run API test scenario'
env:
APIDOG_ACCESS_TOKEN: $(APIDOG_ACCESS_TOKEN)
- task: PublishTestResults@2
condition: always()
inputs:
testResultsFormat: 'JUnit'
testResultsFiles: 'apidog-reports/*.xml'
testRunTitle: 'Apidog API tests'
La macro $(APIDOG_ACCESS_TOKEN) lee la variable secreta de la pipeline; mapearla a través de env la mantiene fuera de la línea de comandos visible. PublishTestResults@2 con condition: always() hace que los resultados aparezcan en la pestaña de Pruebas, independientemente de si la ejecución pasó o falló. Para un tratamiento más completo de esta plataforma, Apidog tiene un tutorial dedicado sobre las pruebas de API de pipeline en Azure DevOps.
Patrones que mantienen la puerta honesta
Una pipeline que ejecuta tus pruebas es la base. Estas recetas son lo que la hace útil en el día a día.
Prueba de humo justo después de un despliegue. Ejecuta un escenario rápido contra producción en el momento en que se lanza una versión, apuntando al entorno de producción, y detente en el primer fallo:
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e <prodEnvId> -r cli --on-error end
Regresión completa durante la noche. Ejecuta una carpeta completa de escenarios según un horario y recopila todos los fallos en un solo informe en lugar de detenerte en el primero:
apidog run --access-token $APIDOG_ACCESS_TOKEN -f <folderId> -r html,junit --on-error continue --out-dir ./nightly-reports
--on-error es el control aquí. end falla rápidamente, lo que deseas para una puerta de despliegue. continue ejecuta cada paso para que un informe nocturno muestre todas las fallas a la vez. De cualquier manera, la ejecución sigue saliendo con un valor distinto de cero si algo falla, por lo que la puerta se mantiene.
Ejecuta un escenario sobre múltiples entradas. Impulsa iteraciones desde un archivo de datos y trata cada fila como su propia aprobación:
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -d ./test-data.csv -r junit
Prueba una rama de características, no main. Ejecuta los escenarios exactamente como existen en una rama:
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 --branch feature-payments -e 1629989 -r cli
Depura un fallo solo en CI. Cuando un escenario pasa localmente pero falla en la pipeline, añade --verbose. Imprime la solicitud exacta que envió el runner y la respuesta exacta que recibió, que es casi siempre cómo encuentras la diferencia de entorno que causa la brecha.
Cuando la compilación te miente
Algunos modos de fallo aparecen con la suficiente frecuencia como para destacarlos, porque cada uno anula silenciosamente la puerta.
La compilación permanece en verde cuando una prueba debería fallar. Este es el peligroso. Casi siempre significa que el código de salida está siendo ignorado. Si envolviste el comando en una pipeline de shell, o añadiste || true para "evitar que rompa la compilación", también impediste que detectara cualquier cosa. Elimina cualquier cosa que enmascare la salida no nula. El paso apidog run debe ser lo que el paso de CI lea.
Errores de autenticación. El token es incorrecto, ha caducado o nunca llegó al comando. Confirma que el secreto de CI realmente está poblado (un eco enmascarado de su longitud, nunca el valor), y regenéralo desde la pestaña CI/CD del escenario si es necesario.
"Escenario no encontrado". El ID del escenario, el ID del proyecto o la rama no coinciden. Vuelve a copiar el comando de la pestaña CI/CD para garantizar que los IDs sean actuales, y verifica dos veces que --branch apunte a donde crees.
Pasa localmente, falla en CI. Casi siempre una diferencia de entorno. El runner puede apuntar a un entorno -e diferente, estar detrás de un firewall que no puede alcanzar tu host, o carecer de una variable que el escenario necesita. Ejecuta con --verbose y compara la solicitud que produjo el runner con la que envías localmente.
Fallos de TLS contra hosts internos. Si tu endpoint utiliza una CA interna, pasa el certificado CA adicional en lugar de deshabilitar la verificación. Recurre a -k (omitir verificación SSL) solo como último recurso en un host interno de confianza con un certificado autofirmado, nunca contra algo público.
Por qué construir visualmente y ejecutar de forma desatendida
Hay una verdadera elección de diseño detrás de todo esto, y vale la pena un párrafo. Con los runners script-first, la prueba y su ejecución son el mismo archivo, por lo que un script frágil es tanto tu prueba como tu cuello de botella. Con Apidog, el escenario en tu proyecto es la prueba, y la CLI simplemente lo ejecuta donde una persona no puede estar. Nadie mantiene dos representaciones de la misma verificación. Creas rápidamente en el constructor visual, ejecutas automáticamente en la pipeline, y ambos se mantienen sincronizados porque son el mismo artefacto. Esa es una gran parte de por qué los equipos tratan a Apidog como una alternativa a Postman para pruebas de API una vez que CI entra en escena, y por qué las aseriones de API sólidas importan más que el runner en el que las envuelves.
El ciclo es simple una vez que está en marcha. Diseña y depura solicitudes en la aplicación. Encadénalas en un escenario con aserciones. Envía tu código, y la CLI ejecuta ese escenario en CI en cada cambio. Cuando algo falla, el informe nombra la aserción y el código de salida detiene el despliegue. Lo arreglas, envías de nuevo, y la misma puerta confirma la solución.
Si tus pruebas todavía viven en el editor de alguien, esa es la brecha a cerrar esta semana. Descarga Apidog, haz que un escenario pase, copia el comando apidog run de su pestaña CI/CD y pega el bloque anterior para tu plataforma. Tendrás pruebas de API bloqueando cada fusión la misma tarde.
Preguntas frecuentes
¿Es gratis usar la CLI de Apidog en CI? La CLI es un paquete npm gratuito: npm install -g apidog-cli. Ejecuta los escenarios de tu proyecto Apidog, por lo que lo que puedes ejecutar depende de tu plan Apidog, pero el ejecutor de línea de comandos en sí no es un producto de pago aparte.
¿Tengo que reescribir mis pruebas como código? No. Creas escenarios visualmente en Apidog y la CLI los ejecuta por ID. El escenario es la prueba; la CLI es solo el ejecutor. Esa es la principal diferencia con los runners script-first.
¿Cómo falla realmente una prueba mi compilación? A través del código de salida. Cuando cualquier aserción falla, apidog run sale con un valor distinto de cero. Tu sistema de CI lo lee, marca el paso como fallido y bloquea la fusión o el despliegue. No añades ninguna configuración adicional para que la puerta funcione.
¿Qué formato de informe debo usar? Usa junit para el XML legible por máquina que tu panel de CI analiza en resultados de aprobado/fallido, y añade html si quieres un informe navegable guardado como un artefacto de compilación. Una combinación común es -r junit,html. Mantén cli también si quieres una salida legible en el registro de compilación.
¿Necesito instalar Apidog en el servidor de CI? No. El runner de CI solo necesita Node.js (v16 o posterior) y el paquete apidog-cli. Sin aplicación de escritorio, sin GUI, sin archivo de licencia en la máquina. El paquete más un token de acceso es suficiente.
¿Puedo ejecutarlo sin una instalación global? Sí. Usa npx apidog-cli run ... para ejecutarlo sin una instalación global persistente, lo cual es más limpio en runners efímeros que se eliminan después de cada trabajo.
¿En qué se diferencia esto de Newman? Newman ejecuta colecciones de Postman desde la línea de comandos. La CLI de Apidog ejecuta escenarios de prueba de Apidog. Los roles son paralelos, pero el runner de Apidog ejecuta escenarios que creaste en la aplicación y se envía como el único paquete apidog-cli. Consulta Postman CLI vs Newman para la parte de Postman de esa comparación.
¿De dónde obtengo el token de acceso y los IDs? Todo desde la pestaña CI/CD del escenario de prueba en Apidog. Elige la opción de línea de comandos, genera un token de acceso y copia el comando completo apidog run que Apidog construye con los IDs de escenario y entorno ya completados. Luego mueve el token a un secreto de CI y haz referencia a él como $APIDOG_ACCESS_TOKEN.