¿Cómo ejecutar pruebas de API desde Apidog CLI?

Sus pruebas de API pasan en su computadora portátil. Luego, alguien fusiona un cambio a las 2 a.m., el endpoint de staging comienza a devolver una carga útil malformada, y nadie se da cuenta hasta que un cliente presenta un ticket a la mañana siguiente. Las pruebas existían. Simplemente nunca se ejecutaron donde importaba: dentro de la pipeline, en cada push, sin que un humano hiciera clic en un botón.

Esa brecha entre "pruebas que existen" y "pruebas que se ejecutan automáticamente" es exactamente lo que cierra un ejecutor de línea de comandos. La CLI de Apidog toma los escenarios de prueba que ya construyó en la aplicación de escritorio o web de Apidog y los ejecuta sin interfaz gráfica desde un terminal. Sin GUI, sin clics manuales. Lo instala con un comando npm, lo apunta a un escenario de prueba, y sale con un código de estado limpio y un informe que puede publicar en cualquier sistema CI. Eso lo convierte en el puente entre el constructor visual de pruebas y su plataforma CI/CD.

En resumen

• La CLI de Apidog es un paquete npm llamado apidog-cli. Instálelo globalmente con npm install -g apidog-cli, luego ejecute escenarios con el comando apidog run.
• Ejecuta los escenarios de prueba que diseña en Apidog. No reescribe las pruebas como código; la CLI ejecuta el mismo escenario por ID, utilizando un token de acceso para la autenticación.
• Ejecución principal: apidog run --access-token $APIDOG_ACCESS_TOKEN -t <scenarioId> -e <environmentId> -n 1 -r html,cli.
• Los reportes cubren cli, html, json y junit. El XML de JUnit es lo que se conecta directamente a los paneles de pruebas de CI.
• Un código de salida distinto de cero en caso de fallo de la prueba es lo que convierte a la CLI en una verdadera puerta de calidad. Las pruebas fallidas fallan la compilación por defecto.
• Funciona en cualquier ejecutor de CI que tenga Node.js: GitHub Actions, GitLab CI, Jenkins, CircleCI, Azure Pipelines y más.

Qué es realmente la CLI de Apidog

Apidog es una plataforma API todo en uno: usted diseña el esquema, depura solicitudes, construye escenarios de prueba automatizados, simula endpoints y publica documentación en un solo espacio de trabajo. La mayor parte de ese trabajo se realiza en una interfaz visual. Encadena solicitudes en un escenario de prueba, agrega aserciones, extrae valores de una respuesta a la siguiente y recorre un archivo de datos.

La CLI es el ejecutor sin interfaz gráfica para esos escenarios. No tiene su propio formato de prueba. Accede a su proyecto de Apidog, encuentra el escenario que nombra por ID y lo ejecuta exactamente como lo haría la aplicación, luego informa los resultados. Piense en ello como la relación entre una herramienta de compilación y su código fuente: la fuente de la verdad reside en el proyecto, y la CLI es lo que lo ejecuta sin la presencia de una persona.

Esto importa porque elimina la razón más común por la que las pruebas de API se echan a perder. Cuando las pruebas existen solo como pasos clicables en una aplicación de escritorio, se ejecutan cuando alguien se acuerda. Cuando se ejecutan desde un comando de una sola línea, puede conectarlas a una pipeline y se ejecutan en cada commit, cada fusión, cada programación nocturna. El constructor visual le ofrece una autoría rápida; la CLI le ofrece automatización. Obtiene ambos sin tener que elegir.

Si viene del mundo de Postman, el modelo mental se mapea limpiamente. La CLI de Apidog desempeña el papel que la CLI de Postman o Newman desempeñan para las colecciones de Postman, excepto que ejecuta escenarios de prueba de Apidog y se entrega como un único paquete. Hemos cubierto esa comparación en profundidad en Postman CLI vs Newman, y la pregunta más amplia de ejecutar colecciones en CI sin Newman si está migrando.

Requisitos previos

Antes de ejecutar un solo comando, necesita tres cosas:

1. Node.js v16 o posterior. La CLI se envía como un paquete npm, por lo que un entorno de ejecución de Node es la única dependencia del sistema. Verifique el suyo con node -v. Cualquier imagen de CI con Node 16+ ya califica.
2. Un escenario de prueba de Apidog. La CLI ejecuta escenarios, no solicitudes sueltas. Construya uno en la aplicación Apidog primero: encadene sus solicitudes, agregue aserciones, configure cualquier iteración impulsada por datos que necesite. Si es nuevo en la creación de aserciones, Aserciones de API: una guía práctica le guiará a través de la validación de respuestas.
3. Un token de acceso. Esto autentica la CLI en su cuenta de Apidog para que pueda recuperar y ejecutar el escenario. Lo genera dentro de la pestaña CI/CD del escenario de prueba; más sobre esto a continuación.

Eso es todo. Sin instalación separada de Apidog en el servidor de CI, sin GUI, sin archivo de licencia. El paquete y un token son suficientes.

Instalación de la CLI de Apidog

Instálelo globalmente con npm:

npm install -g apidog-cli

Luego confirme que todo se resolvió correctamente:

node -v && apidog -v && which node && which npm && which apidog

Si eso imprime los números de versión y las rutas, ha terminado. El binario es apidog, por lo que cada comando comienza con apidog run.

En una máquina de desarrollador, una instalación global está bien. En CI, tiene dos patrones razonables. El primero es instalarlo desde cero en cada ejecución de pipeline, lo que garantiza que esté en la última versión:

npm install -g apidog-cli
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r cli

El segundo es ejecutarlo sin una instalación global persistente a través de npx, lo que evita mutar los paquetes globales del ejecutor:

npx apidog-cli run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r cli

Ambos funcionan. El enfoque npx es más limpio para los ejecutores de CI efímeros; la instalación global es ligeramente más rápida cuando la almacena en caché entre ejecuciones.

Obteniendo su token de acceso y ID de escenario

La CLI necesita saber dos cosas: qué escenario ejecutar y que está autorizada para ejecutarlo. Apidog genera ambos para usted para que no tenga que buscarlos en la interfaz de usuario.

Abra el escenario de prueba que desea automatizar. Cambie a su pestaña CI/CD. Elija la opción de línea de comandos, luego haga clic en "Agregar token de acceso" y "Generar token". Apidog construye el comando completo apidog run para usted, con el token de acceso, el ID del escenario y el ID del entorno ya completados. Haga clic en el comando para copiarlo.

Ese comando generado es el punto de partida canónico. Se ve así:

apidog run --access-token YOUR_ACCESS_TOKEN -t 605067 -e 1629989 -n 1 -r html,cli

Los números son IDs reales de su proyecto. 605067 es el ID del escenario de prueba. 1629989 es el ID del entorno. Casi nunca los escribirá a mano; los copiará de la pestaña CI/CD una vez y luego parametrizará el token.

Una regla que vale la pena establecer temprano: trate el token de acceso como una contraseña. No lo pegue en un archivo de configuración confirmado o en una definición de pipeline pública. Almacénelo como un secreto en su sistema CI y haga referencia a él como una variable de entorno. Cada ejemplo a continuación usa $APIDOG_ACCESS_TOKEN exactamente por esta razón.

El comando apidog run, bandera por bandera

Toda la CLI gira en torno a un comando. Aquí está la superficie completa de opciones, agrupadas por lo que controla cada grupo.

Selección de qué ejecutar

Usted elige una de -t, -f o --test-suite dependiendo del alcance. Un solo escenario para una prueba de humo enfocada, una carpeta para un área de características, un conjunto de pruebas cuando desea que un conjunto curado de escenarios se ejecuten juntos como un trabajo lógico.

Autenticación

Esta es la única bandera que necesita cada comando de CI. Pásela desde un secreto, nunca en línea.

Entorno e iteración

La bandera de entorno es cómo se apunta el mismo escenario a staging en una verificación de pull-request y a producción en una prueba de humo post-despliegue, sin duplicar el escenario. Los datos de iteración son cómo se ejecuta un escenario a través de cincuenta filas de entrada y se trata cada fila como un paso separado. Cubrimos el patrón impulsado por datos más completamente en la guía sobre escalado de pruebas de API automatizadas con conjuntos de pruebas.

Informes

Aquí es donde la CLI se gana su lugar en una pipeline. Pase múltiples formatos a la vez, separados por comas:

apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -r html,junit --out-dir ./test-reports

cli le brinda una salida de terminal legible para humanos que leen el registro de compilación. html produce un informe autocontenido que puede archivar como un artefacto de compilación y abrir en un navegador. junit emite XML en el formato JUnit estándar, que casi todos los paneles de CI saben cómo analizar en un árbol de aprobación/falla. json le brinda el resultado estructurado sin procesar si desea posprocesarlo.

Manejo de errores y comportamiento de salida

--on-error controla lo que sucede a mitad del escenario. end detiene la ejecución en el primer fallo, que es lo que normalmente desea para una prueba de humo que falla rápidamente. continue ejecuta cada paso para que vea todos los fallos en un solo informe. ignore es para el caso raro en el que un paso es conocido por ser inestable y no desea que descarrile la ejecución.

TLS y certificados

Úselos cuando pruebe endpoints detrás de TLS mutuo o con cadenas de CA internas. Use -k solo contra hosts internos de confianza donde el certificado sea autofirmado; nunca contra nada público.

Salida y diagnóstico

--verbose es su primer movimiento cuando una prueba pasa localmente pero falla en CI; le muestra la solicitud exacta que el ejecutor envió y la respuesta exacta que recibió. --silent es para trabajos nocturnos ruidosos donde solo le importa el código de salida y el informe guardado.

Códigos de salida: la parte que hace que CI funcione

Un ejecutor de pruebas solo es útil en una pipeline si le dice a la pipeline si las pruebas pasaron. La CLI de Apidog hace esto de la manera en que lo hace toda herramienta de línea de comandos bien comportada: sale con el código 0 cuando cada aserción pasa y un código distinto de cero cuando algo falla.

Ese único comportamiento es lo que convierte a apidog run en una puerta de calidad. Los sistemas de CI leen el código de salida de cada paso. Una salida distinta de cero marca el paso como fallido, lo que falla el trabajo, lo que bloquea la fusión o el despliegue. No configura nada extra. Siempre que el paso apidog run esté en su pipeline, una prueba fallida detiene la línea.

Puede dar forma a esto con --on-error. El comportamiento predeterminado falla en la primera aserción rota, lo que mantiene la retroalimentación rápida. Cambie a --on-error continue cuando prefiera ver todos los fallos en un solo informe antes de que la compilación se ponga roja. De cualquier manera, la ejecución aún termina en una salida distinta de cero si algo falló, por lo que la puerta se mantiene.

Ejecución en GitHub Actions

workflow completo que ejecuta un escenario de Apidog en cada pull request y publica el informe como un artefacto.

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

El token reside en los secretos del repositorio y llega al paso como una variable de entorno. El if: always() en el paso de carga significa que aún obtiene el informe incluso cuando las pruebas fallan, que es exactamente cuando desea leerlo. Si una prueba falla, el paso apidog run sale con un valor distinto de cero, el trabajo se pone rojo y el PR muestra una verificación fallida.

Ejecución en GitLab CI

El mismo patrón en .gitlab-ci.yml:

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

Dos cosas a tener en cuenta. Almacene APIDOG_ACCESS_TOKEN como una variable de CI/CD enmascarada y protegida en Configuración, no en el archivo. Y el bloque reports: junit: le dice a GitLab que analice el XML de JUnit y muestre los resultados en el widget de la solicitud de fusión, para que un revisor vea qué aserciones fallaron sin descargar nada.

Ejecución en Jenkins

En una pipeline declarativa, almacene el token como una credencial de Jenkins o una variable de entorno global, luego llame a la CLI en una etapa:

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 sus agentes de compilación ya tienen la CLI instalada y en caché, elimine la línea npm install y llame directamente a apidog run. El paso junit en el bloque post alimenta el XML a los gráficos de tendencias de pruebas de Jenkins; archiveArtifacts mantiene el informe HTML adjunto a la compilación. Si está sopesando Jenkins frente a otros ejecutores, la comparación en Configuración de ReadyAPI Jenkins CI y una alternativa más sencilla cubre las compensaciones.

Patrones y recetas comunes

Prueba de humo después del despliegue. Ejecute un escenario rápido contra producción justo después de un lanzamiento, apuntando al entorno de producción:

apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e <prodEnvId> -r cli --on-error end

Regresión completa nocturna. Ejecute una carpeta completa de escenarios según un cronograma, con todos los fallos recopilados en un solo informe:

apidog run --access-token $APIDOG_ACCESS_TOKEN -f <folderId> -r html,junit --on-error continue --out-dir ./nightly-reports

Ejecución basada en datos. Repita un escenario sobre un CSV de casos de prueba:

apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -d ./test-data.csv -r junit

Verificación específica de la rama. Ejecuta los escenarios tal como existen en una rama de características, no en main:

apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 --branch feature-payments -e 1629989 -r cli

Depurar un fallo solo en CI. Cuando un escenario pasa localmente pero falla en la pipeline, agregue --verbose para ver la solicitud a nivel de cable exacta que envió el ejecutor y la respuesta exacta que recibió.

Solución de problemas

Errores de autenticación. Si la ejecución falla con un error de autenticación, el token es incorrecto, ha caducado o no llega al comando. Realice una verificación enmascarada (nunca el token completo) y confirme que su secreto de CI está realmente poblado. Vuelva a generar el token 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. Vuelva a copiar el comando de la pestaña CI/CD para garantizar que los ID sean actuales y confirme que --branch apunta donde espera.

Las pruebas pasan localmente pero fallan en CI. Casi siempre es una diferencia de entorno. El ejecutor de CI puede apuntar a un entorno -e diferente, acceder a un host al que no puede llegar o carecer de una variable de la que depende su escenario. Ejecute con --verbose y compare la solicitud que envió el ejecutor de CI con lo que usted envía localmente.

Fallos de red o TLS contra hosts internos. Si su endpoint utiliza una CA interna, pase --ssl-extra-ca-certs. Use -k solo como último recurso en hosts internos de confianza donde el certificado sea autofirmado.

La compilación permanece en verde incluso cuando una prueba debería fallar. Confirme que el código de salida del paso apidog run realmente está llegando a CI. Si lo ha envuelto en una pipeline de shell o le ha agregado || true, la salida distinta de cero se ignora y la puerta deja de funcionar. Elimine cualquier cosa que enmascare el código de salida.

Cómo la CLI de Apidog encaja en un flujo de trabajo real

La CLI es una parte de un ciclo. Usted diseña y depura solicitudes en la aplicación Apidog. Las encadena en un escenario con aserciones. Confirma su trabajo y la CLI ejecuta ese escenario en CI con cada cambio. Cuando algo se rompe, el informe le dice qué aserción falló y el código de salida detiene el despliegue. Lo arregla, vuelve a hacer push y la misma puerta confirma la solución.

La ventaja de construir pruebas visualmente y ejecutarlas sin interfaz gráfica es que nadie tiene que mantener dos representaciones de la misma prueba. El escenario en el proyecto es la prueba. La CLI simplemente lo ejecuta donde un humano no puede estar. Ese es un modelo diferente de los ejecutores script-first, donde la prueba y su ejecución son el mismo archivo frágil, y es una gran parte de por qué los equipos se están cambiando a Apidog como una alternativa a Postman para pruebas de API.

Si aún no ha creado las pruebas, comience en la aplicación, haga que un escenario pase, luego configure el comando CLI desde su pestaña CI/CD. Descargue Apidog para configurar su primer escenario automatizado y lo tendrá protegiendo su pipeline esa misma tarde.

Preguntas frecuentes

¿La CLI de Apidog es gratuita? La CLI en sí es un paquete npm gratuito. Se instala con npm install -g apidog-cli. Ejecuta los escenarios de prueba de su proyecto Apidog, por lo que lo que puede ejecutar depende de su plan Apidog, pero el ejecutor de línea de comandos no es un producto de pago separado.

¿Tengo que reescribir mis pruebas como código para usar la CLI? No. Esa es la principal diferencia con los ejecutores "script-first". Usted construye escenarios visualmente en Apidog, y la CLI los ejecuta por ID. El escenario es la prueba; la CLI es solo el ejecutor.

¿Cuál es la diferencia entre la CLI de Apidog y 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 ejecutor de Apidog ejecuta escenarios que usted creó en la aplicación Apidog y se distribuye como un único paquete apidog-cli. Consulte Postman CLI vs Newman para la parte de Postman de esa comparación.

¿Qué formato de informe debo usar en CI? Use junit para el resultado legible por máquina que su panel de CI analiza en un árbol de aprobación/falla, y agregue html si desea un informe navegable guardado como un artefacto de compilación. Una opción común es -r html,junit. Mantenga también cli activado si desea una salida legible en el registro de compilación.

¿Cómo hace la CLI que una compilación falle? A través de su código de salida. Cuando cualquier aserción falla, apidog run sale con un código 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 necesita configurar nada adicional para que esto funcione.

¿Puedo ejecutar la CLI sin instalarla globalmente? Sí. Use npx apidog-cli run ... para ejecutarla sin una instalación global persistente, lo cual es conveniente en ejecutores de CI efímeros.

¿Qué versión de Node.js necesito? Node.js v16 o posterior. Cualquier imagen moderna de CI con Node 16+ ya satisface el requisito.

¿Dónde obtengo el token de acceso y el ID del escenario? Ambos provienen de la pestaña CI/CD del escenario de prueba en Apidog. Elija la opción de línea de comandos, genere un token de acceso y copie el comando apidog run completo que Apidog le construye con los ID ya rellenos. Luego mueva el token a un secreto de CI.