Apidog CLI vs Newman: Ejecutar Pruebas API en CI (2026)

Sus pruebas de API pasan en su portátil. La pregunta más difícil es si se ejecutan en cada pull request, cada fusión y cada compilación nocturna sin que un humano haga clic en nada. Ese trabajo pertenece a un ejecutor de línea de comandos. Toma las pruebas que ya escribió, las ejecuta sin interfaz gráfica dentro de su pipeline, sale con un código de estado que su CI puede leer y escribe un informe que su panel de control puede analizar. Sin GUI, sin paso manual, sin excusas para omitir la ejecución.

Durante años, la respuesta predeterminada a esa necesidad ha sido Newman, el ejecutor de colecciones de línea de comandos de código abierto de Postman. Es una herramienta sólida y bien comprendida, y muchos equipos aún la eligen primero. Pero si usted crea sus pruebas en Apidog en lugar de Postman, tiene una segunda opción: la CLI de Apidog, que ejecuta los mismos escenarios de prueba que construye visualmente en la aplicación, sin interfaz gráfica en CI. Este artículo es una comparación honesta, a nivel de comando, de los dos. Cubre lo que Newman hace bien, dónde encaja la CLI de Apidog y cómo se siente cada uno una vez que está conectado a un pipeline real.

TL;DR

• Newman (newman, instalado vía npm install -g newman) ejecuta un archivo JSON de colección de Postman exportado. Es de código abierto, gratuito y lee una colección más un archivo de entorno desde el disco o una URL. Soporta entornos, archivos de datos, recuentos de iteración y reportadores JUnit/JSON/HTML, y sale con un código distinto de cero cuando una prueba falla.
• Apidog CLI (apidog-cli, binario apidog) ejecuta los escenarios de prueba que diseñas en la aplicación Apidog, obtenidos por ID usando un token de acceso. No exportas nada ni mantienes un archivo JSON a mano; el escenario visual es la prueba, y la CLI lo ejecuta exactamente como lo haría la aplicación.
• Ambos se integran con GitHub Actions, GitLab CI, Jenkins y cualquier cosa con Node.js. Ambos fallan la compilación ante una prueba fallida. JUnit XML es lo que se conecta a los paneles de CI en ambos lados.
• Elige Newman cuando tus pruebas ya existen como colecciones de Postman y quieres un ejecutor gratuito, amigable con el repositorio y sin necesidad de una nueva cuenta.
• Elige Apidog CLI cuando quieras una creación visual, encadenamiento de solicitudes, gestión de entornos y ejecuciones basadas en datos que se mantengan sincronizadas con el mismo escenario que tu equipo depura cada día.

El problema real: pruebas que existen pero nunca se ejecutan

Una prueba que se ejecuta manualmente es una prueba que se echa a perder. Alguien la construyó, pasó una vez, y luego permaneció intacta mientras la API cambiaba por debajo. Más pruebas no solucionan eso. Las pruebas que se ejecutan automáticamente en cada cambio sí lo hacen, porque producen una señal de aprobación o fallo sobre la que su pipeline puede actuar.

Un ejecutor de CLI cierra esa brecha. Para ser útil en CI, debe hacer tres cosas: ejecutarse sin una GUI, salir con un código distinto de cero cuando algo falla para que la compilación se ponga en rojo, y escribir un informe legible por máquina para que los revisores puedan ver qué se rompió. Newman y la CLI de Apidog cumplen con ese estándar de manera limpia. Donde difieren es antes del comando de ejecución, en cómo se escribió la prueba y dónde reside. Si está configurando CI desde cero, los patrones más amplios en cómo automatizar pruebas de API en CI/CD combinan bien con esta comparación. Aquí nos centramos en los dos ejecutores.

Lo que Newman hace bien

Newman se ha ganado su lugar. Es el compañero oficial de código abierto de Postman, y para los equipos cuyas pruebas ya existen como colecciones de Postman, es el camino más directo de “pruebas en mi máquina” a “pruebas en CI”. Vale la pena exponer sus puntos fuertes claramente antes de cualquier comparación.

Es gratuito y de código abierto. Lo instalas desde npm y lo ejecutas dondequiera que se ejecute Node.js, sin una licencia separada para el ejecutor en sí. Tu colección es un archivo JSON portátil que puedes subir a un repositorio, almacenar como un artefacto de compilación o obtener de una URL. Esa portabilidad es real, y significa que Newman se integra en casi cualquier pipeline sin fricción.

Reutiliza lo que ya construiste. Si tu equipo escribe solicitudes, scripts de pre-solicitud y aserciones de prueba en Postman, Newman ejecuta esas mismas colecciones sin cambios. No hay reescritura. Los scripts que escribiste en el editor de Postman se ejecutan de la misma manera en la ejecución sin interfaz gráfica, lo que mantiene la curva de aprendizaje plana para los usuarios de Postman.

npm install -g newman

El binario es newman. Ejecutas una colección exportada apuntando al archivo JSON, normalmente con un archivo de entorno al lado:

newman run api-tests.postman_collection.json -e staging.postman_environment.json

Ese es el ciclo principal. Exporta la colección de Postman, sube el JSON y ejecútalo. Newman lee las solicitudes y aserciones del archivo y las ejecuta en orden. Para la ruta de configuración completa, el propio tutorial de Apidog sobre cómo instalar Newman y ejecutar colecciones de Postman cubre el flujo de exportación y ejecución paso a paso.

Newman también soporta los elementos esenciales de CI que se esperan. Las ejecuciones basadas en datos provienen de un archivo CSV o JSON:

newman run api-tests.postman_collection.json \
  -e staging.postman_environment.json \
  -d users.csv \
  -n 5

Aquí -d proporciona el archivo de datos y -n establece el recuento de iteraciones, de modo que la colección se ejecuta una vez por fila o un número fijo de veces. Estos son los mismos primitivos que cualquier ejecutor serio necesita, y Newman los ha tenido durante años.

Dónde Newman empieza a costarte

Las fortalezas anteriores son honestas, pero también lo son las desventajas, y estas se manifiestan en el mantenimiento diario en lugar de en un solo comando.

El mayor inconveniente es el paso de exportación. Una colección de Postman en CI es una instantánea. Se crea y depura en la aplicación Postman, luego se exporta un archivo JSON para ejecutarlo sin interfaz gráfica. En el momento en que alguien edita una solicitud en la aplicación y olvida reexportar, su colección comprometida se desvía de la fuente de verdad. La ejecución de CI sigue pasando contra una definición antigua mientras la API real ha avanzado. Nada en las herramientas fuerza la sincronización de ambas; depende de quien recuerde exportar.

La escritura de scripts es el otro inconveniente. La lógica de prueba de Postman reside en fragmentos de JavaScript adjuntos a cada solicitud, y esos scripts son donde ocurren el encadenamiento, la extracción de variables y las aserciones. Eso es flexible, pero significa que su suite de pruebas es un montón de pequeños scripts para escribir, depurar y mantener manualmente. A medida que los escenarios crecen, también lo hace la superficie de scripts que usted posee. Esto es parte de un patrón más amplio que los equipos encuentran a medida que las colecciones escalan, lo cual abordamos en restricciones del ejecutor de colecciones de Postman y cómo solucionarlas.

Nada de esto hace de Newman una mala herramienta. Lo convierte en un ejecutor cuya ergonomía está ligada al modelo de creación de Postman: scripts más un paso de exportación. Si ese modelo se adapta a su equipo, Newman está bien. Si el baile de exportación y sincronización es la parte que sigue fallando, ahí es exactamente donde ayuda un ejecutor diferente.

Lo que la CLI de Apidog hace diferente

Apidog toma un camino diferente hacia el mismo pipeline. Se construyen pruebas visualmente en la aplicación Apidog. Se encadenan solicitudes en un escenario de prueba, se añaden aserciones en un editor sin código, se extrae un valor de una respuesta para la siguiente solicitud y se repite todo sobre un archivo de datos. La CLI es el ejecutor sin interfaz gráfica para esos escenarios. No tiene un formato de archivo separado ni nada que exportar. Obtiene el escenario que usted nombra por ID de su proyecto Apidog y lo ejecuta exactamente como lo haría la aplicación.

Eso elimina el problema de la deriva. El escenario en el proyecto es la prueba. No hay una instantánea exportada que pueda desincronizarse, porque la CLI ejecuta el escenario en vivo, no una copia del mismo. Lo creas una vez en un constructor visual que maneja el encadenamiento de solicitudes y las aserciones por ti, y luego el mismo escenario se ejecuta en CI. El ciclo rápido de creación y el ciclo de automatización comparten una única fuente de verdad.

npm install -g apidog-cli

El binario es apidog. Una ejecución típica nombra un escenario por ID, elige un entorno y se autentica con un token de acceso:

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

No escribes esos ID a mano. Abre el escenario de prueba en Apidog, ve a su pestaña CI/CD, genera un token de acceso y Apidog construye el comando completo para ti con el ID del escenario y el ID del entorno ya completados. Lo copias una vez, luego mueves el token a un secreto de CI y lo referencias como $APIDOG_ACCESS_TOKEN. Si no estás seguro de qué flags soporta tu versión instalada, ejecuta apidog run --help y te mostrará las opciones exactas disponibles.

El modelo basado en token y obtención por ID es la diferencia más clara con Newman. Newman lee un archivo de colección desde el disco; la CLI de Apidog accede a un proyecto a través de la red, autenticada, y ejecuta el escenario almacenado allí. Ninguno está mal. Se adaptan a diferentes configuraciones de equipo, y la elección se trata principalmente de si quieres que la prueba exista como un archivo exportado o como un escenario en vivo en un espacio de trabajo compartido.

Comparativa

Dos cosas destacan. Primero, ambos ejecutores cubren los mismos elementos esenciales de CI: selección de entorno, iteración basada en datos, los formatos de informe importantes y una salida distinta de cero en caso de fallo. Los nombres de las banderas son incluso lo suficientemente similares como para que la memoria muscular se transfiera (-e, -d, -n, -r). Segundo, la verdadera división no es la capacidad pura. Es dónde reside la prueba y cómo la escribiste. Newman ejecuta una colección exportada creada con scripts. Apidog ejecuta un escenario visual en vivo por referencia. La versión más profunda de esta comparación, enmarcada en torno a los dos ejecutores del mundo Postman, se encuentra en Postman CLI vs Newman si también quieres ese enfoque.

Reportadores y códigos de salida: las partes que CI realmente lee

Un ejecutor se gana su lugar en un pipeline a través de dos comportamientos: el informe que escribe y el código de salida que devuelve. Si estos son correctos, el resto es cableado.

Newman selecciona los reportadores con el flag -r y una lista separada por comas. JUnit y JSON vienen incluidos; el reportador HTML es el complemento más común:

newman run api-tests.postman_collection.json \
  -e staging.postman_environment.json \
  -r cli,junit \
  --reporter-junit-export ./results/junit.xml

El XML de JUnit es lo que su panel de CI analiza en un árbol de aprobaciones o fallos. La bandera --bail de Newman detiene la ejecución después del primer fallo, lo que acelera la retroalimentación en una prueba de humo. Sin ella, la ejecución se completa y reporta todos los fallos a la vez.

La CLI de Apidog utiliza la misma bandera -r separada por comas y escribe todo bajo un único directorio de salida:

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

Su bandera --on-error define el comportamiento a mitad del escenario: end se detiene en el primer fallo y es el valor predeterminado, continue ejecuta cada paso para que recopiles todos los fallos en un solo informe, e ignore salta un paso que se sabe inestable. De cualquier manera, la ejecución termina con un código distinto de cero si algo falla.

El contrato del código de salida es el mismo en ambos lados, y es la parte fundamental. Cuando una aserción falla, el ejecutor sale con un código distinto de cero. CI lee ese código, marca el paso como fallido, falla el trabajo y bloquea la fusión o el despliegue. No se configura nada extra. La única trampa, idéntica para ambos, es tragarse el código de salida: envolver la ejecución en un pipeline de shell o añadir || true y la salida no-cero se consume, por lo que la puerta deja de funcionar silenciosamente. No haga eso. Para un contexto más amplio sobre los formatos de informe, las pruebas de API basadas en datos con CSV o JSON muestran cómo el informe se relaciona con los datos de iteración.

Newman en GitHub Actions

Dado que la colección es un archivo exportado en el repositorio, el flujo de trabajo es corto. Extrae el código, instala Newman, ejecuta la colección, sube el informe incluso si 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 Newman
        run: npm install -g newman

      - name: Run API tests
        run: |
          newman run ./tests/api-tests.postman_collection.json \
            -e ./tests/staging.postman_environment.json \
            -r cli,junit \
            --reporter-junit-export ./results/junit.xml

      - name: Upload report
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: newman-report
          path: ./results

No se necesita ningún secreto si los archivos de colección y entorno están comprometidos con el repositorio. La línea if: always() mantiene la carga del informe en ejecución incluso cuando las pruebas fallan, que es exactamente cuando quieres leerlo. El costo que estás asumiendo es el paso de exportación que produjo esos archivos JSON en primer lugar, y recordar actualizarlos cuando la API cambia.

CLI de Apidog en GitHub Actions

El flujo de trabajo de Apidog tiene la misma estructura, con un cambio: el token de acceso proviene de los secretos del repositorio, y seleccionas el escenario por ID en lugar de apuntar a un archivo.

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 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

Observe la simetría. El mismo checkout, la misma configuración de Node, la misma forma de instalar y ejecutar, la misma carga siempre. Las únicas diferencias reales son el token configurado como secreto y el escenario seleccionado por ID en lugar de por ruta de archivo. Debido a que el escenario se obtiene en vivo, no hay un archivo JSON que mantener actualizado. Para el mismo patrón en otros sistemas, cómo automatizar pruebas de API en GitHub Actions traslada la estructura a través de GitLab CI y Jenkins.

Cómo elegir

La decisión rara vez se reduce a qué ejecutor es objetivamente mejor. Se reduce a dónde residen tus pruebas y cómo tu equipo quiere mantenerlas.

Elige Newman cuando tus pruebas ya son colecciones de Postman. Si tu suite reside en Postman, tu equipo escribe scripts de prueba en el editor y quieres un ejecutor gratuito y de código abierto que se integre en cualquier pipeline sin una nueva cuenta, Newman es la opción directa. Es la elección natural para los usuarios de Postman que se sienten cómodos exportando una colección y subiendo el JSON, y a quienes no les importa poseer los scripts de prueba manualmente. Puedes leer más sobre las diferencias dentro del ecosistema de Postman en cuál es la diferencia entre Newman y Postman.

Elige la CLI de Apidog cuando la velocidad de creación y una única fuente de verdad importan más que permanecer dentro de Postman. Si prefieres construir un escenario de prueba visualmente, encadenar solicitudes, extraer variables y ejecutar ese mismo escenario en diferentes entornos sin escribir ni reexportar código de prueba, Apidog elimina esa fricción. Diseña, depura, simula y prueba en vivo en un único espacio de trabajo, y la CLI ejecuta el escenario exacto que construiste. Para equipos que vienen de Postman, la migración es algo que Apidog cubre como una alternativa a Postman para pruebas de API, y la importación se realiza con un solo clic.

También hay una respuesta que involucra ambas herramientas. Algunos equipos mantienen un paso de Newman existente ejecutando sus colecciones heredadas mientras trasladan escenarios encadenados nuevos y más complejos a Apidog. Las dos CLI coexisten bien en un mismo pipeline; son pasos separados con códigos de salida separados, y puedes retirar el paso de Newman en tu propio cronograma.

Para configurar tu primer escenario automatizado y ejecutarlo desde la terminal la misma tarde, descarga Apidog, construye un escenario de prueba y copia el comando generado desde su pestaña CI/CD.