Una ejecución de prueba que no imprime nada útil es una ejecución de prueba en la que nadie confía. Su pipeline se pone en rojo, alguien abre el registro de compilación y todo lo que encuentra es una pared de marcas de tiempo y un código de salida distinto de cero. ¿Qué aserción falló? ¿Contra qué entorno? ¿En qué fila del archivo de datos? La ejecución lo sabía. Simplemente nunca lo escribió en ningún lugar donde pudiera leerlo más tarde.
Esa es la brecha que llena un reportero. Cuando ejecuta pruebas de API desde la línea de comandos, el informe es la parte con la que realmente convive: el artefacto que archiva, el archivo que analiza su panel de CI, lo que le entrega a un compañero de equipo a las 9 a.m. que no estaba monitoreando el pipeline a las 2 a.m. El veredicto de la prueba es solo la mitad del trabajo. La otra mitad es hacer que ese veredicto sea legible para un humano y para una máquina al mismo tiempo.
El ejecutor de línea de comandos de Apidog maneja ambos. Apidog ofrece una CLI que ejecuta los escenarios de prueba que construyó visualmente en la aplicación, y una única bandera controla cada informe que produce: -r, --reporters. Usted le pasa una lista separada por comas, el ejecutor escribe cada formato en el disco y usted decide quién lee qué. Esta guía trata sobre esa bandera y los archivos que produce: para qué sirve cada reportero, qué se guarda en el disco, dónde se guarda y cómo conectar cada uno a un flujo de trabajo real. Si desea un recorrido más amplio por cada bandera que acepta el ejecutor, la referencia del comando apidog run cubre toda la superficie; esta página se centra en los informes.
Por qué el informe importa más que la ejecución
Ejecute un escenario localmente y verá cómo sucede. Ve cada solicitud dispararse, cada aserción ponerse verde, el resumen al final. El ciclo de retroalimentación es la terminal frente a usted, en vivo.
En CI, ese ciclo desaparece. La ejecución ocurre en una máquina que nunca ve, en un momento en el que no estaba observando, y el único registro es lo que se escribió en el disco antes de que el ejecutor terminara. Si la ejecución no produjo ningún informe, un fallo solo le indica que algo se rompió. Le queda volver a ejecutar todo localmente y esperar que falle de la misma manera.
Un buen informe cierra esa distancia. Captura qué escenario se ejecutó, contra qué entorno, cuántas iteraciones, qué aserciones pasaron, cuáles fallaron y el detalle de la solicitud y la respuesta detrás de cada fallo. Obtener eso en el disco convierte un fallo a las 2 a.m. en una lectura de cinco minutos a la mañana siguiente, en lugar de una búsqueda de reproducción. Esa es la razón principal por la que existe la bandera del reportero, y es por eso que elegir el formato correcto para cada audiencia vale unos minutos de reflexión.
La única bandera que controla todos los informes
La CLI de Apidog es un paquete npm llamado apidog-cli. Instálelo una vez y obtendrá un único binario, apidog, cuyo subcomando principal es run. Instálelo globalmente:
npm install -g apidog-cli
Cada informe que el ejecutor puede producir proviene de una bandera en ese comando: -r, --reporters. Acepta una lista separada por comas, y los cuatro valores que acepta son cli, html, json y junit. El valor predeterminado, si no pasa nada, es cli.
Una ejecución completa con dos reporteros se ve así:
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -n 1 -r html,cli
Eso se autentica con un token, ejecuta el escenario de prueba 605067 contra el entorno 1629989 una vez, y emite un archivo HTML y una salida legible en la terminal. Los ID son el ID del escenario y el ID del entorno; se copian ambos, junto con el token de acceso, de la pestaña CI/CD del escenario en Apidog en lugar de escribirlos a mano. Si alguna de estas configuraciones no le es familiar, la guía completa de Apidog CLI le guiará a través de la instalación, los tokens y su primera ejecución de principio a fin.
La idea clave: una ejecución puede producir varios informes a la vez. No está eligiendo un solo formato. Está eligiendo una audiencia para cada salida y listándolos juntos. Una línea de CI típica emite un archivo HTML legible para humanos y un archivo JUnit legible por máquina de la misma ejecución, por lo que la misma ejecución sirve tanto a una persona como a un panel de control.
cli: el informe que lee en el registro de compilación
El reportero cli imprime un resumen legible directamente en la terminal. Es el predeterminado y es el que un humano escanea primero.
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r cli
Lo que le da es el veredicto en vivo: cuántas solicitudes se ejecutaron, cuántas aserciones pasaron y fallaron, y qué aserciones específicas se rompieron. En un registro de compilación de CI, este es el bloque que alguien lee cuando hace clic en un trabajo fallido. Le dice de un vistazo si el fallo es una aserción rota o cincuenta, y qué endpoint está involucrado, antes de que se molesten en descargar algo.
Mantenga cli activado incluso cuando esté escribiendo formatos de máquina. No cuesta nada y mantiene el registro de compilación útil por sí mismo. Un pipeline que emite solo XML de JUnit produce un panel perfecto y un registro inútil; cualquiera que lea la salida sin procesar no ve nada más que el inicio y la salida del ejecutor. Agregar cli a la lista soluciona eso:
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r cli,junit --out-dir ./apidog-reports
Dos banderas más dan forma a lo que imprime cli. --verbose lo expande a la solicitud y respuesta completas para cada paso, lo cual es su primera medida cuando un escenario pasa en su computadora portátil pero falla en el pipeline; el detalle de la conexión le muestra exactamente lo que el ejecutor envió y recibió. --silent hace lo contrario y suprime completamente la salida de la consola, lo que se adapta a un trabajo programado ruidoso donde solo le importan el código de salida y el archivo guardado.
html: el informe que le entrega a un humano
El reportero html escribe un archivo HTML autocontenido. Ábralo en cualquier navegador y obtendrá la ejecución completa presentada visualmente: cada solicitud, las aserciones sobre ella, el estado de aprobado y fallido, y el detalle de la solicitud y la respuesta detrás de cada paso. Nada que instalar, ningún servidor que ejecutar; es un archivo en el que hace doble clic.
Este es el formato que archiva y comparte. Guárdelo como un artefacto de compilación y el informe sobrevivirá a la ejecución del pipeline, de modo que una semana después aún podrá abrir el informe exacto del despliegue que falló. También es lo que le envía a la persona que pregunta "¿qué falló?" sin hacer que instalen la CLI o vuelvan a ejecutar nada. Abren el archivo, ven el paso en rojo, leen el cuerpo de la respuesta que activó la aserción y listo.
HTML cobra más importancia en una ejecución basada en datos. Cuando un escenario recorre un CSV de cincuenta filas, el informe HTML le muestra el resultado por iteración, para que pueda ver que las filas 1 a 49 pasaron y la fila 50 falló porque una cuenta tenía un token caducado. Un recuento de aprobados o fallidos por sí solo no puede decirle eso. Si ejecuta escenarios con archivos de datos, el patrón se cubre en pruebas de API basadas en datos con CSV y JSON.
La desventaja: HTML es para los ojos, no para analizar. No intente rasparlo para obtener el estado de aprobación/fallo en un script. Para eso están JSON y JUnit.
junit: el informe que analiza su panel de control de CI
El reportero junit emite XML en el formato estándar de JUnit. Ese formato es importante porque es la lengua franca de los informes de prueba de CI. Casi todos los sistemas de CI, GitHub Actions, GitLab CI, Jenkins, CircleCI, Azure Pipelines, saben cómo leer XML de JUnit y convertirlo en un árbol de aprobado/fallido, mostrar fallos en un widget de solicitud de fusión y mostrar tendencias de resultados a lo largo de las compilaciones con el tiempo.
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r junit --out-dir ./apidog-reports
Si elige exactamente un formato de máquina para CI, elija este. La recompensa es que los resultados de sus pruebas dejan de vivir solo en un archivo de registro y comienzan a vivir en el panel de control que su equipo ya consulta. Un revisor abre una solicitud de extracción y ve qué aserciones fallaron renderizadas en línea, sin necesidad de buscar en el registro, sin descargar artefactos.
Configurarlo consta de dos pasos: producir el XML y luego indicarle a su sistema de CI dónde encontrarlo. En GitLab CI, ese segundo paso es el bloque `reports: junit:`:
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
En Jenkins, el equivalente es el paso `junit` en un bloque `post` que apunta a los mismos archivos. En GitHub Actions, usted sube el directorio como un artefacto y deja que una acción que reconoce JUnit lo renderice. El flujo de trabajo completo de GitHub, incluyendo la carga de artefactos que se ejecuta incluso cuando las pruebas fallan, se encuentra en ejecución de pruebas de Apidog CLI en GitHub Actions.
json: el informe que sus scripts post-procesan
El reportero json produce el resultado estructurado sin procesar. Donde HTML es para los ojos y JUnit para los paneles de control, JSON es para el código que usted mismo escribe.
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r json --out-dir ./apidog-reports
Recúrralo cuando los formatos incorporados no se ajusten a lo que desea hacer con el resultado. Envíe métricas de tasa de aprobación a un sistema de monitoreo. Cree un resumen personalizado de Slack. Alimente el resultado en un script que decida si revertir un despliegue. Compare la ejecución de hoy con la de ayer. Cualquier cosa programática comienza desde JSON, porque es el formato que puede analizar sin adivinar la estructura.
Una bandera de informe está diseñada específicamente para la salida JSON. `--out-json-failures-separated` divide los fallos en su propio archivo JSON. Eso le proporciona un documento solo con fallos, que es mucho más fácil de leer y comparar que escanear un resultado completo en busca de los pocos pasos que fallaron. En una gran barrida de regresión donde la mayoría de los pasos pasan, un archivo solo con fallos es la diferencia entre un vistazo y una búsqueda con grep.
Dónde aterrizan los archivos: --out-dir, --out-file y marcadores de posición
Elegir formatos es la mitad del panorama. La otra mitad es controlar dónde aterrizan los archivos y cómo se nombran, lo cual es importante en el momento en que conserva informes de más de una ejecución.
--out-dir <dir> establece el directorio donde se escriben los informes. El valor predeterminado es ./apidog-reports. En CI, apúntelo a un lugar donde su paso de artefacto pueda encontrarlo, y manténgalo consistente para que su configuración de carga nunca tenga que cambiar:
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r html,junit --out-dir ./apidog-reports
--out-file <name> establece el nombre del archivo del informe, y aquí es donde se vuelve útil. Sin él, cada ejecución tiende a sobrescribir la anterior, por lo que solo conserva el informe más reciente. La bandera acepta marcadores de posición que el ejecutor rellena al momento de la escritura:
{SCENARIO_NAME}se convierte en el nombre del escenario que se ejecutó.{FOLDER_NAME}se convierte en el nombre de la carpeta cuando ejecuta una carpeta de escenarios.{GENERATE_TIME}se convierte en una marca de tiempo.
Estampe un nombre de archivo con el nombre del escenario y una marca de tiempo y cada ejecución escribirá un archivo distinto y autoexplicativo en lugar de sobrescribir el anterior:
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r html --out-file "{SCENARIO_NAME}-{GENERATE_TIME}"
Ahora, su directorio de informes se lee como un historial. Puede saber de qué escenario provino cada informe y cuándo se ejecutó sin abrir un solo archivo, que es exactamente lo que desea cuando escanea una carpeta de ejecuciones nocturnas para encontrar aquella donde las cosas salieron mal por primera vez.
Una bandera de informe más completa el lado de la nube. --upload-report [value] sube una descripción general del informe a la nube de Apidog, por lo que la ejecución también aparece en el historial de su proyecto junto con los archivos locales. Es la opción a elegir cuando desea que el resultado sea visible dentro del propio Apidog, no solo como un archivo en el ejecutor de CI.
Una estrategia de reportero por audiencia
La forma más limpia de decidir es asignar cada reportero a quién lo lee y luego pasar los que necesita juntos.
- Una persona que escanea el registro de compilación en este momento lee
cli. Inclúyalo siempre. - Una persona que abre un informe guardado más tarde lee
html. Archívelo como un artefacto. - El panel de control de CI lee
junit. Es lo que renderiza los fallos en la solicitud de fusión y las tendencias de los resultados a lo largo de las compilaciones. - Un script que usted escribió lee
json. Es el único formato diseñado para ser analizado por su propio código.
Para la mayoría de los pipelines de CI, la combinación principal es HTML para humanos más JUnit para el panel de control, con CLI activado para que el registro sin procesar siga siendo legible:
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r cli,html,junit --out-dir ./apidog-reports
Esa única ejecución produce un registro legible, un artefacto navegable y un archivo XML analizable. Tres audiencias, una ejecución, sin duplicación.
Una precaución que vale la pena mencionar claramente: el informe le dice lo que sucedió, pero el código de salida es lo que hace que el pipeline actúe en consecuencia. La CLI de Apidog sale con un código distinto de cero cuando falla alguna aserción, y ese código de salida, no el informe, es lo que hace que la compilación falle y bloquea la fusión. El informe explica el fallo; el código de salida lo impone. No envuelva el comando en nada que oculte ese código, como agregar || true en un shell, o obtendrá un informe rojo perfecto adjunto a una compilación que aun así se puso en verde. La versión más profunda de esa lógica de puerta de calidad se encuentra en la guía para automatizar pruebas de API en CI/CD.
Armándolo todo
Ejecute un escenario en CI y emita los tres artefactos útiles para tres audiencias:
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -n 1 -r cli,html,junit --out-dir ./apidog-reports
Ejecute un barrido de carpetas nocturno, recopile todos los fallos en un solo informe y asigne a cada archivo un nombre autoexplicativo:
apidog run --access-token $APIDOG_ACCESS_TOKEN -f 88012 -r html,junit --on-error continue --out-dir ./nightly-reports --out-file "{FOLDER_NAME}-{GENERATE_TIME}"
Ejecute un escenario basado en datos y conserve un JSON solo con los fallos para comparaciones rápidas:
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -d ./accounts.csv -r json --out-json-failures-separated true --out-dir ./apidog-reports
Si prefiere no instalar la CLI globalmente en un ejecutor efímero, cambie la instalación por npx y mantenga las mismas banderas de reportero:
npx apidog-cli run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r html,junit --out-dir ./apidog-reports
El comportamiento del reportero es idéntico en ambos casos; la elección entre una instalación global y npx se trata de la higiene del ejecutor, no de los informes que obtiene.
Los nombres de las banderas, los valores predeterminados y los reporteros pueden cambiar entre las versiones de la CLI, por lo que el ejecutor es siempre su propia fuente de verdad. Ejecute apidog run --help en la versión que tenga instalada y confíe en eso más que en cualquier artículo, incluido este. Para configurar el escenario que la CLI ejecuta en primer lugar, descargue Apidog, cree un escenario en la aplicación, luego copie el comando generado de su pestaña CI/CD y agregue los reporteros que necesite.