Cómo ejecutar pruebas de API con Apidog CLI en GitHub Actions (Flujo de trabajo completo)

Tus pruebas de API pasan en tu máquina. Luego, un compañero de equipo fusiona un cambio que rompe el endpoint de inicio de sesión, y nadie se da cuenta hasta que un cliente abre un ticket. Las pruebas existían. Simplemente nunca se ejecutaron en el momento en que importaban: en la solicitud de extracción (pull request), antes de la fusión.

Esa brecha es lo que cierra la integración continua. Trasladas las pruebas de tu terminal local a una pipeline que las ejecuta automáticamente, en cada push, contra cada cambio. Específicamente para las pruebas de API, la forma más limpia de hacerlo es un ejecutor de línea de comandos que ejecuta los escenarios exactos que ya construiste, devuelve un código de salida de aprobado/fallido, y permite que la CI decida si la compilación se muestra en verde o rojo.

TL;DR

• La CLI de Apidog es un paquete npm, apidog-cli. Instálalo en un paso de flujo de trabajo con npm install -g apidog-cli, luego ejecuta escenarios con apidog run.
• Ejecuta los escenarios de prueba que diseñas en la aplicación Apidog por ID. No trasladas las pruebas a código; la CLI ejecuta el mismo escenario utilizando un token de acceso para la autenticación.
• Un trabajo mínimo de GitHub Actions consta de cuatro pasos: checkout, configurar Node, instalar la CLI, ejecutar apidog run --access-token "$APIDOG_ACCESS_TOKEN" -t <scenarioId> -e <environmentId> -r junit,cli.
• La CLI sale con un código distinto de cero cuando falla alguna aserción. GitHub lee ese código de salida, marca la verificación como fallida y bloquea la fusión. Esa es la puerta de calidad completa; no configuras nada extra.
• Almacena el token de acceso como un secreto de GitHub Actions y pásalo a través de env:. Nunca lo subas al repositorio.
• Usa -r junit para enviar los resultados a un panel, -r html para un artefacto navegable, y if: always() en el paso de carga para que aún recibas el informe cuando las pruebas fallen.

¿Por qué ejecutar pruebas de API en CI?

Una prueba que solo se ejecuta cuando recuerdas ejecutarla es una prueba en la que no puedes confiar. Las ejecuciones locales están bien mientras escribes el escenario. Se desmoronan en el momento en que un equipo se involucra, porque la máquina de cada desarrollador es ligeramente diferente y nadie ejecuta el conjunto completo antes de cada push.

CI soluciona el problema de confianza al hacer que la ejecución sea automática y uniforme. Cada solicitud de extracción (pull request) activa el mismo trabajo, en el mismo ejecutor limpio, contra el mismo entorno. Cuando un endpoint comienza a devolver un 500 o un esquema de respuesta se desvía, la verificación falla en la PR que lo causó, con el nombre de la persona que lo envió adjunto. La retroalimentación llega en minutos, mientras el cambio aún está reciente, en lugar de días después en producción.

Las pruebas de API son muy adecuadas para esto porque son rápidas y deterministas. Un escenario golpea endpoints reales, afirma sobre códigos de estado y cuerpos de respuesta, y aprueba o falla. No hay un navegador inestable, no hay renderizado que esperar. Eso las hace ideales como puerta de fusión: lo suficientemente rápidas como para ejecutarse en cada PR, lo suficientemente decisivas como para bloquear una mala. Si quieres un contexto más amplio sobre qué es CI/CD y cómo encajan las piezas, el manual sobre qué es CI/CD y cómo funciona cubre los fundamentos.

Lo que realmente hace la CLI de Apidog

Aquí está la parte que te ahorra más tiempo: no escribes código de prueba para la CLI.

Construyes tus escenarios de prueba visualmente en la aplicación Apidog, con las solicitudes, aserciones, variables de entorno y datos que necesitas. La CLI es un ejecutor. Dado un ID de escenario y un token de acceso, recupera ese escenario de tu proyecto Apidog y lo ejecuta, solicitud por solicitud, evaluando cada aserción exactamente como lo haría la aplicación. El resultado es un informe y un código de salida.

Ese diseño es importante para la CI. La mayoría de los ejecutores de pruebas te piden que mantengas una representación de código separada de tus pruebas; lo que ejecutas en la pipeline se desvía de lo que diseñaste. Con Apidog, la pipeline ejecuta el mismo escenario que tu equipo ya mantiene en la aplicación. Actualiza una aserción en el editor visual y la próxima ejecución de CI la capturará. No hay una segunda copia que mantener sincronizada.

El binario es apidog, distribuido como el paquete npm apidog-cli. Cada comando comienza con apidog run. Si deseas ver el ejecutor integrado en un flujo de trabajo de automatización más completo, el tutorial sobre integración de la CLI de Apidog con Claude Skills para la automatización de pruebas de API cubre ese ángulo; este artículo se centra en los indicadores que necesitas para una pipeline de GitHub Actions.

Antes de empezar: tres cosas que necesitas

Necesitas tres datos antes de que se ejecute el flujo de trabajo. Dos son IDs de tu proyecto Apidog; uno es un token.

1. Un escenario de prueba. Constrúyelo en la aplicación Apidog si aún no lo has hecho. Esto es lo que ejecuta la CLI. Un único escenario de inicio de sesión y obtención de perfil es suficiente para empezar; puedes escalar más tarde.
2. El ID del escenario y el ID del entorno. El ID del escenario le dice a la CLI qué ejecutar; el ID del entorno le dice dónde (dev, staging, production). Ambos son visibles en la aplicación.
3. Un token de acceso. Esto autentica la CLI en tu cuenta de Apidog para que pueda obtener y ejecutar el escenario.

La forma más limpia de obtener todo esto a la vez es la pestaña CI/CD del escenario. Abre el escenario de prueba que deseas automatizar, cambia a su pestaña CI/CD y elige la opción de línea de comandos. Haz clic para agregar un token de acceso y generar uno. Apidog ensambla el comando completo apidog run para ti, con el token de acceso, el ID del escenario (-t) y el ID del entorno (-e) ya rellenados. Copia ese comando; es la base para tu paso de CI.

Una regla que vale la pena mencionar de antemano: trata el token de acceso como una contraseña. No lo pegues en un archivo de flujo de trabajo comprometido. Almacénalo como un secreto de GitHub Actions y referéncialo como una variable de entorno. Cada ejemplo a continuación usa $APIDOG_ACCESS_TOKEN precisamente por esa razón.

Paso 1: almacena el token de acceso como un secreto de GitHub

Abre tu repositorio en GitHub. Ve a Settings (Configuración), luego Secrets and variables (Secretos y variables), luego Actions (Acciones), y haz clic en New repository secret (Nuevo secreto de repositorio).

• Nombre: APIDOG_ACCESS_TOKEN
• Secreto: pega el token que Apidog generó para ti

Guárdalo. El token ahora está cifrado en reposo y expuesto solo a las ejecuciones del flujo de trabajo, nunca impreso en los registros. En el flujo de trabajo lo referenciarás como ${{ secrets.APIDOG_ACCESS_TOKEN }} y lo pasarás a la CLI a través de un bloque env:. El ID del escenario y el ID del entorno no son secretos; son IDs inofensivos, por lo que puedes escribirlos directamente en el archivo del flujo de trabajo. Solo el token necesita protección.

Si tu equipo trabaja en varios repositorios que acceden al mismo proyecto Apidog, define el secreto una vez a nivel de organización y otorga acceso a los repositorios relevantes. El mismo nombre, un solo lugar para rotarlo.

Paso 2: el flujo de trabajo mínimo

Crea .github/workflows/api-tests.yml en tu repositorio. Este es el flujo de trabajo más pequeño que hace algo útil: ejecuta tu escenario en cada solicitud de extracción (pull request) dirigida a main.

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 \
            -r cli
        env:
          APIDOG_ACCESS_TOKEN: ${{ secrets.APIDOG_ACCESS_TOKEN }}

Reemplaza 605067 con tu ID de escenario y 1629989 con tu ID de entorno. Confirma este archivo, abre una solicitud de extracción (pull request) y observa la pestaña Checks (Verificaciones). El trabajo inicia un ejecutor de Ubuntu, instala Node 20, instala la CLI y ejecuta tu escenario. Si todas las aserciones pasan, la verificación se pone en verde. Si una falla, apidog run sale con un código distinto de cero, GitHub marca la verificación como fallida y la PR muestra una X roja.

Esa X roja es el objetivo. Nadie tiene que leer un registro para saber que algo falló; la verificación fallida está justo allí en la solicitud de extracción.

Una nota sobre el paso de instalación: el npm install -g apidog-cli global es simple y funciona. Si prefieres no mutar los paquetes globales del ejecutor, puedes omitir el paso de instalación y llamar a la CLI a través de npx en su lugar:

      - name: Run API test scenario
        run: npx apidog-cli run --access-token "$APIDOG_ACCESS_TOKEN" -t 605067 -e 1629989 -r cli
        env:
          APIDOG_ACCESS_TOKEN: ${{ secrets.APIDOG_ACCESS_TOKEN }}

Ambos enfoques ejecutan el escenario idéntico. npx es más limpio en ejecutores efímeros; la instalación global es marginalmente más rápida cuando almacenas en caché node_modules entre ejecuciones. Elige el que mejor se adapte a tu estilo.

Paso 3: publica un informe que realmente puedas leer

Una verificación verde o roja te indica el resultado. Cuando una prueba falla, quieres saber por qué, y para eso quieres el informe.

El indicador -r (o --reporters) controla los formatos de informe. Acepta cli, html, json y junit, separados por comas. Para la CI, dos formatos se ganan su lugar:

• junit emite XML en el formato estándar de JUnit. Casi todos los paneles de CI y herramientas de informes de pruebas saben cómo analizarlo en un árbol de aprobado/fallido.
• html produce un informe autónomo que puedes guardar como un artefacto de compilación y abrir en un navegador, con la solicitud y respuesta completas para cada paso.

Mantén cli también si quieres una salida legible en el propio registro de compilación. Aquí está el paso de ejecución actualizado para producir ambos formatos de informe y escribirlos en un directorio, además de un paso de carga para que el informe sobreviva a la ejecución:

      - name: Run API test scenario
        run: |
          apidog run \
            --access-token "$APIDOG_ACCESS_TOKEN" \
            -t 605067 \
            -e 1629989 \
            -n 1 \
            -r html,junit,cli \
            --out-dir ./apidog-reports
        env:
          APIDOG_ACCESS_TOKEN: ${{ secrets.APIDOG_ACCESS_TOKEN }}

      - name: Upload test report
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: apidog-report
          path: ./apidog-reports

Dos detalles hacen que esto funcione como quieres. El indicador --out-dir le dice a la CLI dónde escribir los informes; aquí es ./apidog-reports, que luego el paso de carga toma. Y if: always() en el paso de carga es el importante: por defecto GitHub salta los pasos posteriores una vez que un paso falla, pero quieres el informe más cuando las pruebas fallaron. if: always() fuerza la carga para que se ejecute independientemente del resultado de la prueba. Después de que finalice el trabajo, el informe aparece en Artifacts (Artefactos) en la página de resumen de la ejecución, listo para descargar.

El indicador -n 1 establece el recuento de iteraciones en una ejecución; auméntalo si quieres que el escenario se ejecute varias veces seguidas.

Si quieres que GitHub muestre los resultados de JUnit en línea como una verificación anotada en lugar de un archivo descargable, agrega una acción de publicación de resultados de prueba después del paso de ejecución y apúntala a ./apidog-reports/*.xml. Eso convierte el XML en un resumen de aprobado/fallido adjunto a la ejecución, lo cual es útil para suites más grandes donde desplazarse por el registro no es práctico.

Paso 4: prueba el entorno correcto en el momento adecuado

Una solicitud de extracción (pull request) debe probarse contra el entorno de staging. Un despliegue a producción debe verificarse contra producción. El mismo escenario puede hacer ambas cosas; solo cambias el ID del entorno con -e.

Una configuración común y duradera utiliza dos disparadores en un archivo de flujo de trabajo. Las solicitudes de extracción (pull requests) ejecutan el escenario contra tu entorno de staging como una puerta de fusión. Los pushes a main (que es lo que produce una fusión) ejecutan el mismo escenario contra producción como una prueba de humo post-despliegue.

name: API tests

on:
  pull_request:
    branches: [main]
  push:
    branches: [main]

jobs:
  pr-check:
    if: github.event_name == 'pull_request'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm install -g apidog-cli
      - name: Test staging
        run: |
          apidog run \
            --access-token "$APIDOG_ACCESS_TOKEN" \
            -t 605067 \
            -e 1629989 \
            -r junit,cli \
            --out-dir ./apidog-reports
        env:
          APIDOG_ACCESS_TOKEN: ${{ secrets.APIDOG_ACCESS_TOKEN }}
      - uses: actions/upload-artifact@v4
        if: always()
        with:
          name: staging-report
          path: ./apidog-reports

  prod-smoke:
    if: github.event_name == 'push'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm install -g apidog-cli
      - name: Smoke test production
        run: |
          apidog run \
            --access-token "$APIDOG_ACCESS_TOKEN" \
            -t 605067 \
            -e 1730055 \
            -r cli \
            --on-error end
        env:
          APIDOG_ACCESS_TOKEN: ${{ secrets.APIDOG_ACCESS_TOKEN }}

Los dos ID de entorno (1629989 para staging, 1730055 para producción) son la única diferencia significativa. El trabajo de PR construye y archiva un informe JUnit para que los revisores puedan inspeccionar los fallos; la prueba de humo de producción se ejecuta de forma optimizada y falla rápidamente con --on-error end, lo que se detiene en la primera aserción rota para que descubras rápidamente que un despliegue salió mal.

Vale la pena conocer --on-error. Controla lo que sucede cuando un paso falla a mitad del escenario. end detiene la ejecución en el primer fallo (retroalimentación rápida, bueno para pruebas de humo). continue ejecuta todos los pasos restantes para que veas todos los fallos en un solo informe (bueno para una verificación exhaustiva de PR). ignore omite un paso conocido por ser inestable sin descarrilar la ejecución. Sea cual sea tu elección, la ejecución seguirá terminando con un código de salida distinto de cero si algo falló, por lo que la puerta se mantiene de cualquier manera.

Avanzando: ejecuciones matriciales, carpetas y pruebas impulsadas por datos

Una vez que la puerta básica está en su lugar, algunos indicadores la extienden sin mucho YAML adicional.

Ejecuta un área de funcionalidad completa, no un solo escenario. Cambia -t <scenarioId> por -f <folderId> para ejecutar cada escenario dentro de una carpeta, o --test-suite <testSuiteId> para ejecutar una suite curada. Las suites son la herramienta adecuada cuando quieres que un conjunto específico y ordenado de escenarios se ejecuten juntos como un único trabajo lógico; la guía sobre escalado de pruebas de API automatizadas con suites de prueba cubre cuándo recurrir a ellas.

Prueba varios entornos en paralelo. Una matriz ejecuta el mismo trabajo en múltiples ID de entorno a la vez:

jobs:
  api-tests:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        env-id: [1629989, 1730055]
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm install -g apidog-cli
      - name: Run scenario against ${{ matrix.env-id }}
        run: |
          apidog run \
            --access-token "$APIDOG_ACCESS_TOKEN" \
            -t 605067 \
            -e ${{ matrix.env-id }} \
            -r cli
        env:
          APIDOG_ACCESS_TOKEN: ${{ secrets.APIDOG_ACCESS_TOKEN }}

GitHub activa un ejecutor por cada valor de la matriz, por lo que los entornos de staging y producción se prueban simultáneamente y cada uno informa su propio aprobado/fallido.

Impulsa las iteraciones desde un archivo de datos. El indicador -d ejecuta un escenario a través de filas de un archivo CSV o JSON, tratando cada fila como un paso separado: apidog run --access-token "$APIDOG_ACCESS_TOKEN" -t 605067 -d ./test-data.csv -r junit. Así es como validas el mismo endpoint contra cincuenta entradas sin construir cincuenta escenarios.

Ejecutar contra una rama. Si tu equipo utiliza la función de ramas de Apidog, --branch <branchName> apunta la ejecución a una rama específica en lugar de main, lo que permite que la PR de una rama de características pruebe contra las definiciones de escenario de esa rama.

Solución de problemas comunes de fallos de CI

El trabajo está en verde pero una prueba debería haber fallado. Verifica que el código de salida del paso apidog run esté llegando realmente a GitHub. Si envolviste el comando en una pipeline de shell o le añadiste || true, la salida no-cero se ignora y la puerta deja de funcionar silenciosamente. Elimina cualquier cosa que oculte el código de salida. Ejecuta el comando en su propia línea, o como el último comando en un bloque run:, para que su estado de salida sea el estado de salida del paso.

La autenticación falla. La causa más común es que el nombre del secreto no coincide. La clave env:, la referencia de valor ${{ secrets.APIDOG_ACCESS_TOKEN }} y el secreto que creaste en Settings (Configuración) deben usar el mismo nombre. También confirma que el token no ha sido regenerado en Apidog desde que lo guardaste; la regeneración invalida el anterior.

Pasa localmente, falla en CI. Agrega --verbose al comando de ejecución temporalmente. Imprime la solicitud completa que envió el ejecutor y la respuesta completa que recibió, lo que generalmente revela la diferencia, a menudo una variable de entorno que está configurada en tu máquina pero no en el entorno de CI, o un servicio de staging que se comporta de manera diferente al tuyo local.

Los informes no aparecen como artefactos. Asegúrate de que --out-dir en el paso de ejecución y path: en el paso de carga apunten al mismo directorio, y de que el paso de carga tenga if: always(). Sin if: always(), una prueba fallida omite la carga y pierdes el informe exactamente cuando lo necesitas.

El ejecutor no puede acceder a tu API. Si tu entorno de staging o producción se encuentra detrás de un firewall o una VPN, un ejecutor público alojado en GitHub no puede acceder a él. Necesitarás un ejecutor autoalojado dentro de tu red, o una entrada en la lista de permitidos para los rangos de IP de GitHub.

Cómo se compara esto con las alternativas

Podrías escribir pruebas de API como código con un framework, conectarlas a un ejecutor de pruebas y llamarlo desde Actions. Eso funciona, pero ahora estás manteniendo una suite de código que tiene que permanecer sincronizada con la API y con lo que sea que tu equipo diseñe en su herramienta de API. El enfoque de Apidog evita esa duplicación: el escenario que tu equipo ya mantiene en la aplicación es la prueba que se ejecuta en CI.

También podrías scriptar llamadas curl crudas en un paso de flujo de trabajo. Está bien para una única verificación de salud, pero es doloroso más allá de eso, porque estás construyendo manualmente aserciones, cambios de entorno e informes que la CLI te ofrece de forma gratuita.

GitHub Actions tampoco es el único lugar para esto. El mismo comando apidog run se puede usar en GitLab CI, Jenkins, CircleCI o cualquier ejecutor que pueda ejecutar un comando de shell y leer un código de salida. Si GitHub Actions no es tu plataforma, los patrones aquí se transfieren directamente; consulta la guía para automatizar pruebas de API en CI/CD para la vista multiplataforma, o el tutorial sobre integración de pruebas automatizadas de Apidog con Jenkins si usas Jenkins.

Para construir los escenarios que ejecutarás, descarga Apidog, diseña tus pruebas en la aplicación y obtén el comando de la CLI de la pestaña CI/CD del escenario. El ejecutor es un paquete npm gratuito; lo que puedes ejecutar depende de tu proyecto Apidog, pero el ejecutor de línea de comandos en sí no es un producto de pago separado.

Conclusión

La configuración es más pequeña de lo que parece. Construye un escenario en Apidog, almacena un token de acceso como un secreto de GitHub y añade unos pocos pasos a un archivo de flujo de trabajo. A partir de ahí, cada solicitud de extracción (pull request) ejecuta tus pruebas de API automáticamente, un endpoint fallido pone la verificación en rojo antes de la fusión, y el informe espera en la pestaña Artifacts (Artefactos) siempre que necesites ver qué falló.

La razón por la que se mantiene simple es la división del trabajo. La aplicación Apidog es dueña de las pruebas; la CLI las ejecuta; GitHub lee el código de salida. Nada tiene que duplicarse o mantenerse sincronizado. Cuando actualizas una aserción en la aplicación, la próxima ejecución de CI la utiliza. Eso es lo que hace que valga la pena hacer esto el primer día de un proyecto en lugar de implementarlo después del primer incidente de producción.