Cómo ejecutar pruebas de API en CI con apidog run

Copió un comando de una pestaña de CI/CD, lo pegó en una pipeline y funcionó. Luego, un compañero pregunta por qué la compilación sigue en verde cuando una prueba claramente falló, o si se puede apuntar la misma ejecución a staging en lugar de a producción, o cómo obtener un informe que su panel de CI realmente pueda analizar. De repente, la línea única no es suficiente. Necesita saber qué hace cada parte.

apidog run es el único comando en el corazón del ejecutor de línea de comandos de Apidog. Ejecuta los escenarios de prueba de API que construyó en Apidog sin interfaz gráfica (headless), desde una terminal, sin GUI y sin un humano haciendo clic en un botón. Todo lo que el ejecutor puede hacer, lo hace a través de indicadores en este único comando: qué escenario ejecutar, qué entorno apuntar, cuántas veces iterar, qué informes emitir y qué se considera un fallo. Aprenda la superficie de los indicadores una vez y dejará de copiar y pegar a ciegas.

Qué es apidog run

La CLI de Apidog se distribuye como un paquete npm llamado apidog-cli. La instala una vez y obtiene un único binario, apidog, cuyo subcomando principal es run. Ese subcomando toma uno de sus escenarios de prueba de Apidog y lo ejecuta de la misma manera que lo haría la aplicación de escritorio, luego informa con un código de salida y cualquier archivo de informe que haya solicitado.

Instálelo globalmente:

npm install -g apidog-cli

Confirme que se resolvió:

apidog -v

Lo que hay que entender antes de los indicadores es sobre qué opera `apidog run`. No define su propio formato de prueba. La prueba es el escenario que usted creó en la aplicación Apidog: solicitudes encadenadas, aserciones, valores extraídos de una respuesta a la siguiente, iteración opcional basada en datos. La CLI accede a su proyecto, encuentra el escenario por ID y lo ejecuta. Por lo tanto, la mayoría de los indicadores son para decirle al ejecutor qué buscar y cómo comportarse mientras se ejecuta, no para escribir pruebas en línea.

Un comando real mínimo se ve así:

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

Eso dice: autentíquese con este token, ejecute el escenario de prueba `605067`, contra el entorno `1629989`, una vez, y produzca un informe HTML más una salida de terminal legible. Cada indicador en esa línea se explica a continuación, junto con los que ese comando omite.

La superficie completa de opciones de un vistazo

Aquí está el conjunto completo de opciones agrupadas por función. Úselo como tabla de consulta; las secciones posteriores explican las que necesitan más de una frase.

Los nombres de los indicadores y sus valores predeterminados pueden cambiar entre las versiones de la CLI. En caso de duda, el ejecutor es su propia fuente de verdad: ejecute apidog run --help en la versión que tenga instalada y confíe en eso antes que en cualquier artículo, incluido este.

Eligiendo qué ejecutar

Tres indicadores deciden el alcance de una ejecución, y usted elige exactamente uno de ellos por comando.

-t, --test-scenario <id> ejecuta un único escenario. Este es el caso cotidiano: una prueba de humo enfocada, un escenario de regresión, algo que desea proteger en una solicitud de extracción.

-f, --test-scenario-folder <id> ejecuta cada escenario dentro de una carpeta. Utilícelo cuando haya organizado un área de características en una carpeta y desee que todo el grupo se ejecute como un solo trabajo, como una revisión de regresión nocturna.

--test-suite <id> ejecuta una suite de pruebas curada, que es un conjunto de escenarios que usted ha reunido para ejecutar juntos como una unidad lógica. Una suite es la herramienta adecuada cuando los escenarios que desea no están todos en una sola carpeta, pero aún pertenecen a la misma pasada de prueba.

Dos selectores más refinan dónde busca el ejecutor. --project <id> nombra el proyecto en el que reside un escenario, útil cuando su token tiene acceso a más de uno. --branch <name> ejecuta el escenario tal como existe en una rama específica en lugar de main, lo que le permite validar cambios en las pruebas en una rama de características antes de que se fusionen.

# un escenario
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r cli

# una carpeta completa
apidog run --access-token $APIDOG_ACCESS_TOKEN -f 88012 -r html,junit

# una suite curada
apidog run --access-token $APIDOG_ACCESS_TOKEN --test-suite 40231 -r junit

Autenticando la ejecución

--access-token <token> es el único indicador que necesita cada ejecución en línea. Demuestra que la ejecución tiene permiso para buscar y ejecutar su escenario. Usted genera el token dentro de la pestaña CI/CD de un escenario de prueba en Apidog, donde la aplicación también construye el comando completo apidog run para usted con el ID del escenario y el ID del entorno ya completados.

Trate el token como una contraseña. No lo pegue en un archivo de pipeline comprometido o en un script compartido. Almacénelo como un secreto en su sistema de CI y páselo a través de una variable de entorno, por lo que cada ejemplo aquí hace referencia a $APIDOG_ACCESS_TOKEN en lugar de una cadena literal. Si un token se filtra, genérelo de nuevo desde la misma pestaña de CI/CD y el anterior dejará de funcionar.

Apuntando a un entorno e iterando

El indicador de entorno es lo que permite que un escenario sirva para múltiples propósitos. -e, --environment <id> apunta la ejecución a un entorno específico, de modo que el mismo escenario puede verificar el entorno de staging en una puerta de pull-request y el de producción en una prueba de humo posterior al despliegue sin que usted duplique nada. Si administra valores en diferentes entornos, la guía sobre gestión de entornos y secretos para clientes API cubre cómo fluyen esos valores.

-n, --iteration-count <n> ejecuta el escenario n veces consecutivas. Útil para una comprobación rápida de estabilidad o para repetir un flujo que debería ser idempotente.

-d, --iteration-data <path> es el indicador basado en datos. Apúntelo a un archivo JSON o CSV y el ejecutor ejecutará el escenario una vez por fila, tratando cada fila como su propia pasada con sus propios valores de entrada. Así es como se ejecuta un escenario de inicio de sesión en cincuenta cuentas, o un flujo de creación de pedidos a través de una tabla de cargas útiles. El patrón más profundo se encuentra en pruebas de API basadas en datos con CSV y JSON.

Tres indicadores inyectan valores sin editar el escenario. --variables <path> carga variables de un archivo local. --global-var key=value establece una variable global en línea. --env-var key=value sobrescribe una única variable de entorno solo para esta ejecución. Son útiles en CI cuando un valor (una URL base, una bandera de característica) difiere por pipeline y no desea un entorno separado para cada uno. Si las variables en Apidog son nuevas para usted, dominar las variables en Apidog explica los alcances.

# ejecutar un escenario 50 veces a través de un CSV de entradas
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -d ./accounts.csv -r junit

# sobrescribir una variable de entorno solo para esta ejecución
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 --env-var baseUrl=https://staging.internal -r cli

Informes: cada formato de salida que apidog run puede producir

Este es el grupo que la gente más busca, así que aquí está cada informe y para qué sirve. Los selecciona con -r, --reporters y puede pasar varios a la vez, separados por comas. El predeterminado es cli.

cli imprime un resumen legible en la terminal. Es lo que un humano escanea en el registro de compilación para ver el recuento de aprobaciones/fallos y qué aserciones fallaron. Manténgalo activado incluso junto a los formatos de máquina para que el registro siga siendo útil.

html escribe un informe HTML autocontenido. Archívelo como un artefacto de compilación y ábralo en un navegador para ver la ejecución completa con detalles de solicitud y respuesta. Este es el formato que le entrega a alguien que no estaba monitoreando la pipeline.

junit emite XML en el formato estándar de JUnit. Casi todos los paneles de CI saben cómo analizar XML de JUnit en un árbol de aprobaciones/fallos, mostrar los fallos en un widget de solicitud de fusión y mostrar tendencias de resultados a lo largo del tiempo. Si solo elige un formato de máquina para CI, elija este.

json produce el resultado estructurado sin procesar. Recurra a él cuando desee post-procesar el resultado usted mismo: aliméntelo a un script, envíe métricas a algún lugar o construya un resumen personalizado.

Una combinación común de CI es HTML para humanos más JUnit para el panel de control:

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

Los indicadores de informe restantes controlan dónde se guarda la salida y qué extras incluye:

• --out-dir <dir> establece el directorio donde se escriben los informes. El valor predeterminado es ./apidog-reports.
• --out-file <name> establece el nombre del archivo de informe y acepta los marcadores de posición {FOLDER_NAME}, {SCENARIO_NAME} y {GENERATE_TIME}, para que pueda sellar los archivos con el nombre del escenario y una marca de tiempo en lugar de sobrescribir un archivo en cada ejecución.
• --out-json-failures-separated <value> divide los fallos en su propio archivo JSON, lo que facilita la lectura de una diferencia solo con fallos.
• --upload-report [value] sube una descripción general del informe a la nube de Apidog para que la ejecución aparezca en el historial de su proyecto junto con los archivos locales.

Controlando los fallos: manejo de errores y códigos de salida

Un ejecutor solo es útil en una pipeline si le informa a la pipeline si las pruebas pasaron. apidog run hace esto de la misma manera que las herramientas de línea de comandos bien diseñadas: sale con 0 cuando todas las aserciones pasan y con un código distinto de cero cuando algo falla. Ese único comportamiento es la puerta de calidad completa. CI lee el código de salida, marca el paso como fallido y bloquea la fusión o el despliegue. Usted no configura una puerta; el código de salida es la puerta.

--on-error <comportamiento> define lo que sucede cuando un paso falla a mitad del escenario, y tiene tres valores:

• end detiene la ejecución en el primer paso fallido. Úselo para una prueba de humo de fallo rápido donde desea retroalimentación en el instante en que algo falla.
• continue ejecuta cada paso restante para que recopile todos los fallos en un solo informe. Úselo para una revisión de regresión donde ver cada fallo a la vez ahorra un viaje de ida y vuelta.
• ignore permite que la ejecución continúe más allá de un paso que se sabe que es inestable sin tratarlo como fatal. Úselo con moderación; un paso ignorado no debería ocultar una regresión real.

De cualquier manera, si alguna aserción falló, la ejecución seguirá terminando con un código distinto de cero, por lo que la puerta se mantiene independientemente del comportamiento que haya elegido. Algo que rompe silenciosamente la puerta: envolver el comando en algo que "se traga" su código de salida, como añadir || true en un shell. No lo haga. La salida no nula es el objetivo principal.

Cuatro indicadores ajustan el comportamiento de la solicitud durante la ejecución:

• --ignore-redirects evita que el ejecutor siga automáticamente las redirecciones HTTP, lo que le permite hacer aserciones sobre la propia respuesta de redirección.
• --delay-request [n] espera n milisegundos entre solicitudes, lo que ayuda contra los límites de velocidad o los endpoints sensibles a la carga.
• --timeout-request [n] limita el tiempo que puede tardar una sola solicitud, en milisegundos.
• --timeout-script [n] limita el tiempo que puede ejecutarse un script pre o post-solicitud, en milisegundos.

# prueba de humo: detener en el primer fallo
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r cli --on-error end

# regresión: ejecutar todo, recopilar todos los fallos
apidog run --access-token $APIDOG_ACCESS_TOKEN -f 88012 -r html,junit --on-error continue --out-dir ./nightly-reports

TLS y certificados

Cuando prueba endpoints detrás de TLS mutuo o una autoridad de certificación interna, este grupo es cómo establece la conexión.

-k, --insecure deshabilita completamente la verificación del certificado SSL. Recurra a él solo contra un host interno de confianza con un certificado autofirmado; nunca lo apunte a algo público, porque desactiva la verificación que protege la conexión.

Para un TLS mutuo adecuado, proporcione las credenciales del cliente en su lugar: --ssl-client-cert <ruta> para el certificado PEM, --ssl-client-key <ruta> para su clave privada, y --ssl-client-passphrase <frase_contraseña> si la clave está cifrada. Cuando diferentes hosts necesitan diferentes certificados, --ssl-client-cert-list <ruta> apunta a un archivo de configuración que los mapea. Y --ssl-extra-ca-certs <ruta> añade certificados CA de confianza, que es la solución limpia para una cadena CA interna que el ejecutor de otra manera no reconocería, mejor que recurrir a -k.

Salida y diagnósticos

El último grupo controla lo que imprime el ejecutor y un puñado de detalles de ejecución.

--verbose imprime la solicitud y respuesta completas para cada paso. Este es su primer paso cuando un escenario pasa localmente pero falla en CI: muestra los bytes exactos que el ejecutor envió y recibió, para que pueda comparar con lo que envía manualmente. --silent hace lo contrario, suprimiendo la salida de la consola para trabajos programados ruidosos donde solo le importa el código de salida y el informe guardado. --color <valor> fuerza la salida de color activada o desactivada, útil cuando un visor de registros de CI altera los códigos ANSI.

El resto son para características específicas del escenario:

• --external-program-path <ruta> apunta a un archivo de programas externos para la lógica personalizada a la que llama un escenario.
• --database-connection <ruta> proporciona una configuración de base de datos para escenarios con pasos que consultan directamente una base de datos.
• --preferred-http-version <versión> establece la versión del protocolo HTTP que prefiere el ejecutor.
• -b, --bigint habilita el manejo de BigInt para que los valores numéricos grandes no pierdan precisión.
• --lang <idioma> establece el idioma de visualización de la CLI.
• -h, --help imprime el texto de ayuda, que es la lista autorizada para su versión instalada.

Armándolo todo: comandos que realmente ejecutará

Prueba de humo contra producción justo después de un despliegue, fallando rápidamente:

apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e $PROD_ENV_ID -r cli --on-error end

Regresión nocturna completa sobre una carpeta, cada fallo en un informe HTML y JUnit:

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

Ejecución basada en datos sobre un CSV, salida legible por máquina para CI:

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

Validar cambios en las pruebas en una rama de características antes de que se fusionen:

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

Depurar un fallo solo de CI volcando los detalles de la comunicación:

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

Si está ejecutando la CLI en un ejecutor de CI efímero y prefiere no instalar globalmente, cambie la instalación por npx:

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

Eso cubre la misma superficie. La elección entre una instalación global y npx tiene que ver con la higiene del ejecutor, no con la capacidad. Para configurar el escenario que ejecuta la CLI, Descargue Apidog, construya un escenario en la aplicación, luego copie el comando generado de su pestaña de CI/CD y parametrice el token.