Tutorial: Automatizar las pruebas de Postman con Newman

1. Objetivos de aprendizaje

Al terminar este tutorial vas a ser capaz de:

• Explicar qué es Newman y por qué un pipeline de CI lo necesita en vez de Postman.
• Correr una Collection exportada con Newman desde la terminal, usando el Environment exportado para resolver sus variables.
• Combinar varias Collections en una sola con postman-combine-collections, y correrlas todas con un solo comando de Newman.
• Leer el reporte de Newman y su código de salida para saber si la corrida pasó o falló.

Prerrequisitos: tener Newman y postman-combine-collections instalados (ya deberían estarlo, quedaron instalados en el taller de ambiente de desarrollo), y al menos una Collection y su Environment exportados en collections/, como quedó en el tutorial de Postman.

---

2. Por qué Newman

Hasta ahora corriste tus pruebas de Postman haciendo clic en Send dentro de la aplicación. Eso funciona en tu máquina, pero un pipeline de CI (Jenkins, GitHub Actions) no tiene interfaz gráfica ni a nadie haciendo clic: necesita un comando de terminal que corra la Collection completa y termine en éxito o en error.

Newman es el CLI oficial de Postman: corre una Collection exportada (el mismo .json que ya tienes en collections/) sin abrir la aplicación, imprime un reporte en la terminal y, lo más importante para CI, termina con código de salida 0 si todos los tests pasaron, y distinto de 0 si alguno falló. Ese código de salida es lo que un pipeline usa para decidir si el build pasa o no.

Consejo

Es la misma razón por la que usas mvn test o ng test en vez de correr las pruebas a mano desde el IDE: un pipeline necesita un comando, no una persona haciendo clic.

---

3. Verificar que ya tienes Newman instalado

Newman y postman-combine-collections son paquetes de npm que ya instalaste en el taller de ambiente de desarrollo, al principio del curso. Confirma que siguen instalados:

newman --version
postman-combine-collections --version

Precaución

Si alguno de los dos comandos no existe, vuelve al taller de ambiente de desarrollo e instálalo antes de seguir: npm install -g newman o npm install -g postman-combine-collections.

---

4. Correr una Collection con su Environment

Desde la raíz de tu repositorio (donde está la carpeta collections/), pásale a Newman tanto la Collection como el Environment que exportaste en el tutorial de Postman, con la opción -e:

newman run collections/Artista.postman_collection.json -e collections/environment.postman_environment.json

Newman resuelve {{baseUrl}} con el valor que quedó guardado en ese archivo de Environment: el mismo que ya usabas dentro de la aplicación de Postman.

Precaución

Si ves un error de conexión, o una URL literal como {{baseUrl}}/artistas en el reporte en vez de una URL resuelta, revisa que la ruta después de -e sea correcta y que ese archivo sea el Environment (no la Collection).

Consejo

Exportar el Environment en vez de escribir la variable a mano en cada comando evita un error fácil de cometer y difícil de notar: si en algún comando escribieras --env-var baseURL=... (con mayúscula) en vez de baseUrl, Postman trata los nombres de variable como distintos y {{baseUrl}} en la Collection simplemente no se resolvería, sin ningún aviso claro del porqué. Con el archivo exportado, el nombre de la variable queda fijo una sola vez.

---

5. Correr todas las Collections de una vez

Hoy tienes una sola Collection, pero cuando integres con tu equipo (Release 5) la carpeta collections/ va a tener una Collection por cada módulo, y un solo Environment compartido. Newman corre un solo archivo de Collection a la vez, así que antes de correrlas necesitas combinarlas en una: para eso instalaste postman-combine-collections desde el taller de ambiente de desarrollo.

Combina todas las Collections de collections/ en un solo archivo:

postman-combine-collections -f 'collections/*.postman_collection.json' -o collections/combined.postman_collection.json -n "Musical"

Precaución

Las comillas simples alrededor de 'collections/*.postman_collection.json' son necesarias: sin ellas, la terminal expande el * antes de que postman-combine-collections lo vea, y en algunos sistemas eso hace que solo se combine el primer archivo que encuentre en vez de todos.

Y corre el archivo combinado con Newman, igual que corrías una sola Collection:

newman run collections/combined.postman_collection.json -e collections/environment.postman_environment.json

Este par de comandos es para que tú corras todo de una vez en tu máquina. El Jenkinsfile del repo del grupo hace algo distinto: recorre cada archivo *.postman_collection.json de backend/collections/ y corre Newman sobre cada uno por separado, pasándole la URL del back con --env-var baseUrl=... en vez de leer tu Environment. Por eso la variable de tus Collections tiene que llamarse exactamente baseUrl (con la U mayúscula): si una Collection usa {{baseurl}} o {{BASE_URL}}, en Postman puede funcionar con tu Environment, pero en el pipeline la variable queda sin valor y los requests fallan. Cuando cualquier request de cualquier Collection falla, newman run termina con código de salida distinto de 0 y el pipeline lo detecta.

Consejo

combined.postman_collection.json es un archivo generado, no algo que edites ni versiones a mano: bórralo o agrégalo a tu .gitignore si quieres, se vuelve a generar cada vez que corres el primer comando.

---

6. Leer el reporte

Newman imprime, por cada request, sus asserts (los pm.test que ya escribiste) con ✓ o ✗, y al final una tabla resumen con el total de requests, asserts y fallas. El código de salida del proceso es 0 solo si absolutamente todo pasó. Puedes verlo justo después de correrlo con:

echo $?

---

¿Dónde quedaste?

Al final de este tutorial puedes combinar todas tus Collections de collections/ en una sola con postman-combine-collections, y correrla con Newman usando el Environment ya exportado para resolver {{baseUrl}}, sin depender de la interfaz gráfica de Postman. Esto es lo que necesitas para el Paso 1 de Release 5 antes de abrir tu PR de integración. El stage de Newman del Jenkinsfile del repo del grupo corre cada Collection por separado y pasa baseUrl por línea de comandos, así que lo que de verdad tiene que cumplir tu repo es que cada Collection use {{baseUrl}}.