Monitoreando y cazando bugs con Newman CLI: Guía práctica

Ya sea que nos desempeñemos en el área de soporte técnico o en aseguramiento de calidad, la creatividad y el ingenio son esenciales para identificar y rastrear problemas, permitiéndonos obtener la mayor cantidad de información posible que sea útil para los desarrolladores u otras áreas interesadas en el correcto funcionamiento de un sistema.

Una alternativa para identificar funcionamientos erráticos en API es utilizando Newman CLI. Newman es un ejecutor de línea de comandos que nos permite ejecutar y probar sin esfuerzo una colección de Postman incluyendo los scripts de validación embebidos que tenga.

A continuación describiré cómo podemos usar esta herramienta desde Windows no solo para automatizar el monitoreo de la disponibilidad de una API, sino también para monitorear su funcionalidad.

Instalando Newman CLI

Lo primero que deberemos realizar es configurar e instalar el entorno para ejecutar Newman CLI:

1. Deberemos instalar Node.js en nuestra máquina, ya que Newman funciona sobre este entorno de ejecución, para ello descargaremos el instalador desde la página oficial.

2. Verificar que tenemos instalado correctamente Node.js ejecutando el siguiente comando en nuestro cmd de Windows.

node --version

3. Procedemos a instalar Newman CLI de manera global ejecutando desde el cmd

npm install -g newman

4. Verificar que tenemos instalado Newman correctamente ejecutando el siguiente comando:

newman --version

Ejecutando Newman

Ahora que ya tenemos instalado Newman CLI, podemos hacer que ejecute una solicitud de API ya sea proporcionándole una URL o un archivo JSON que contenga la información de la colección de Postman que queremos probar.

En este caso ejecutaré Newman CLI usando un archivo JSON, para ello primero debo exportar desde Postman mi colección de prueba y luego ejecutaré el siguiente comando desde el cmd de Windows:

newman run Dog_Pics.postman_collection.json

Para efectos de prueba, mi archivo JSON exportado contiene las instrucciones para llamar a una API pública que responde aleatoriamente con enlaces de fotos de perros 😄. Además, contiene código Javascript integrado que validará la estructura de la respuesta del API y en caso de discrepancias, el script integrado arrojará una excepción.

Entonces, al ejecutar estas instrucciones con Newman CLI, tengo la siguiente respuesta: Un reporte con el resultado de la operación GET de la API (HTTP 200) y la ejecución exitosa de mi script de prueba, el cual evaluó que el cuerpo de la respuesta es el esperado.

Un ejemplo del reporte de falla se vería como en la Imagen 4. Allí podemos observar que se produjo un error HTTP 503 y que el script encontró discrepancias en el cuerpo de la respuesta.

Newman CLI también nos permite guardar los reportes de nuestras ejecuciones. Para ello podemos hacer uso de las utilidades de reportes predeterminadas de Newman o instalar un generador de reportes llamado "htmlextra" para visualizar mejor la información en formato HTML.

Ejecutaremos el siguiente comando para instalar "htmlextra":

npm install -g newman-reporter-htmlextra

Una vez instalado podremos ejecutar nuevamente nuestra prueba indicando la generación del reporte

newman run Dog_Pics.postman_collection.json -r htmlextra

El resultado será la generación de un archivo html que contendra un reporte mejor estructurado que podremos visualizar desde el navegador:

Puliendo la automatización

Hasta allí hemos automatizado a la mitad nuestro monitoreo del API, ahora queda ejecutar periódicamente de forma automática nuestro comando, para ello en Windows hice lo siguiente:

1. Creé un script de Powershell simple denominado "newman-scheduled-task" que básicamente crea las carpetas donde se guardarán los reportes en caso de que no existan y luego ejecuta el comando Newman con todos sus parámetros necesarios y una etiqueta timestamp para generar un nombre único de reporte en cada ejecución.

# Script simple para ejecutar Newman con el Programador de Tareas de Windows
# Genera reportes JUnit y HTML con timestamp

# Cambiar al directorio donde está la colección (ajusta esta ruta según tu configuración)
Set-Location "C:\data\APITests"

# Crear directorios si no existen
New-Item -ItemType Directory -Force -Path "C:\data\APITests\xml" | Out-Null
New-Item -ItemType Directory -Force -Path "C:\data\APITests\html" | Out-Null

# Generar timestamp
$timestamp = Get-Date -Format 'yyyyMMdd-HHmm'

# Ejecutar Comando Newman
newman run Dog_Pics.postman_collection.json -r "junit,htmlextra" --reporter-junit-export "C:\data\APITests\xml\report-$timestamp.xml" --reporter-htmlextra-export "C:\data\APITests\html\report-$timestamp.html"

2. Abrir el Programador de tareas de Windows -> Biblioteca del Programador de tareas -> Crear tarea
3. En la pestaña General , establecemos el nombre del programador y una descripción de la tarea, como por ejemplo el propósito para el que se creó la tarea.

4. Seleccionamos la pestaña "Desencadenadores" y hacemos clic en el botón "Nuevo". Aquí configuraremos las condiciones que activan una tarea.

Por ejemplo, podemos especificar que se ejecute al iniciar sesión o cuando ocurra un evento específico seleccionando el menú desplegable " Iniciar la tarea", en este caso escogemos "Según Programación" porque nos interesa ejecutar la tarea cada cierto tiempo (2 minutos para este ejemplo)

5. Luego seleccionar la siguiente pestaña " Acciones " y haga clic en el botón "Nuevo ".
6. En Explorar, colocamos la ruta del ejecutable PowerShell

C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe

7. En "Agregar argumentos ", colocamos los parámetros y nuestro script PowerShell con su ruta completa

-WindowStyle Hidden -File "C:\data\APITests\newman-scheduled-task.ps1"

8. Finalmente, damos clic en Aceptar para crear la tarea programada.

Una vez que nuestro API se empiece a ejecutar de forma automática, tendremos nuestros resultados listos en los reportes para ser analizados en cualquier momento.

Por ejemplo, mediante línea de comandos, podemos buscar rápidamente en cuáles de estos reportes existió errores en la llamada o validación del API, y así localizar de inmediato el reporte HTML correspondiente para visualizar el detalle completo de manera más clara y detallada.

En este caso el error ocurrió en el archivo de reporte report-20250920-2041.xml por lo tanto veramos la información más detallada en su equivalante HTML.

Conluyendo

Con unas pocas líneas de código y Newman CLI, hemos logrado automatizar la validación del funcionamiento de una API, almacenando simultáneamente los resultados en archivos para su posterior análisis.

Este enfoque representa una alternativa ingeniosa para evaluar la funcionalidad y disponibilidad de APIs, especialmente útil en los siguientes escenarios:

• Cuando no tenemos acceso remoto al servidor en donde se ejecuta la aplicación que consume la API para revisar logs.
• Poca o nula información en logs generados por la aplicación acerca de la interacción contra el API.
• Cuando no es posible ejecutar o instalar herramientas de inspección de red en el servidor que sirve o interactúa con el API.
• Como alternativa adicional para generar métricas y alarmas.
• Monitoreo y pruebas automatizadas de API desde nuestra PC.