Newman: cómo ejecutar colecciones Postman desde línea de comandos.

¿Eres QA? ¿Eres desarrollador? Seguramente has trabajado o trabajas con Apis, ya que son cada vez más comunes debido al aumento de proyectos con infraestructuras basadas en microservicios.

Si es tu caso, Postman puede ser clave en tu día a día. Es una herramienta que nos ofrece una gran variedad de funcionalidades, tanto para ayudarnos a desarrollar nuestras APIs como para testearlas (lo cual forma parte también de su desarrollo).

Hoy no vamos a hablar mucho más de Postman (nuestro compañero Félix Redondo ya escribió sobre ello en el blog). En este post vamos a centrarnos en Newman y cómo puede ayudarnos a ejecutar colecciones de Postman desde línea de comandos.

Colecciones de Postman

Antes de empezar a trabajar con Newman debemos tener claro qué son las colecciones de Postman y por qué debemos usarlas.

Las colecciones nos permiten agrupar requests individuales. Estas, a su vez, pueden contener carpetas que agrupen aún más dichas requests. Hasta aquí suena muy bonito, pero ¿qué nos aportan realmente?

Organización

Las colecciones y sus subcarpetas nos ayudan a tener juntas las request relacionadas. Esto nos facilita muchísimo la organización de las mismas, haciéndolas muchos más localizables y reconocibles.

Documentación

Podemos agregar nombres y descripciones a las request, carpetas y colecciones, lo cual sirve de documentación. Esta información está accesible desde el navegador de colecciones. Si cuentas con Postman Pro, también podrás crear y publicar páginas de documentación de las API a través de las colecciones.

Suites de pruebas

Nos permiten crear suites de pruebas que agrupen tests para diferentes request asociadas, lo que nos facilita la creación de pruebas de integración.

Flujos de trabajo condicionales

Se pueden usar scripts para pasar datos entre diferentes request de la API. Con ello, podemos crear flujos que reflejan casos de usos reales.

Antes de trabajar con Newman, necesitamos disponer de las colecciones que queremos ejecutar. Para ello, debemos acceder a Postman y exportarlas en un fichero “.json” cada una.

1. Accedemos a las opciones de la colección pulsando “...”.
2. Hacemos clic en “export”.
3. Seleccionamos la versión de la exportación.
4. Hacemos clic nuevamente en “Export”.
5. Seleccionar la ruta donde queremos almacenar el fichero.

Newman

Newman nos permite ejecutar y probar sin esfuerzo colecciones de Postman directamente desde la línea de comandos. Esto nos abre un gran abanico de posibilidades, que pueden ser explotadas por cada usuario según las necesidades de su proyecto y su ingenio.

Desde mi punto de vista, lo ideal es usarlo dentro de nuestro flujo de integración continua. Podríamos tener una fase que se encargue lanzar una serie de colecciones, que nos ayuden a asegurar que nuestras APIs funciona correctamente.

Primeros pasos con Newman

Newman es un paquete de Node.js y, por lo tanto, lo podemos localizar en su gestor de paquetes npm (Node Package Manager).

Para poder disfrutar de él debemos instalarlo como cualquier otro paquete de node.

npm install -g newman

Ahora sí. Tenemos Newman y nuestras colecciones disponibles en nuestra máquina. Llega el momento de ejecutarlas utilizando un comando similar al del ejemplo que se muestra a continuación. En él, se indica la llamada a la herramienta, el parámetro “run” y la ruta de la colección.

newman run “ruta/nombre_coleccion.json”

No siempre tenemos tenemos almacenadas las colecciones en local. A veces, estas están almacenadas en un servidor y accesibles desde URL. En estos casos, también podemos ejecutarlas sin tener que descargarlas.

newman run “htp://URL_Coleccion_Postman”

Es muy común tener una API desplegada en varios entornos. Si es nuestro caso, podemos generar environments de Postman. En ellos, definiremos las urls y parámetros específicos de cada entorno.

Después de definirlos en la herramienta y exportarlos, podemos hacer referencia en la ejecución, para que nuestras requests apunten al entorno correspondiente en cada momento.

newman run “ruta/nombre_coleccion.json” -e “ruta/nombre_environment.json”

Muchas veces, necesitamos tener un informe que muestre de forma específica y clara tanto la ejecución de los tests, como los resultados de los mismos.

Con la opción “-r” o “--reporters” indicamos que tipo de reporte queremos: cli, json, junit, progress o emojitrain.

Cli es la opción por defecto y, a su vez, consta de una gran variedad de opciones que podemos ir seleccionando según nuestras necesidades.

• --reporter-cli-silent: el reporte es deshabilitado internamente y no se muestra salida en el terminal.
• --reporter-cli-no-summary: la tabla de resumen estadístico no se muestra.
• --reporter-cli-no-failures: evita que los fallos de ejecución se impriman por separado.
• --reporter-cli-no-assertions: desactiva la salida de las aserciones a medida que ocurren.
• --reporter-cli-no-success-assertions: desactiva la salida para aserciones exitosas a medida que ocurren.
• --reporter-cli-no-console: desactiva la salida de console.log (y otras llamadas a la consola) de los scripts de la colección.
• --reporter-cli-no-banner: desactiva el banner de Newman que se muestra al comienzo de cada ejecución de la colección.

Si queremos profundizar más en esta herramienta, podemos acceder a la documentación oficial o directamente a su ayuda desde la consola, escribiendo: newman run --help.

Postman + Newman + Jenkins

Como comentaba al inicio del post, el poder ejecutar colecciones desde línea de comandos, nos abre un abanico de posibilidades. Personalmente destaco el poder ejecutarlos desde Jenkins.

Seguramente hay muchas casuísticas posibles, pero voy a mostrar las dos más básicas y comunes que se me ocurren.

En la primera, tendremos un stage específico dentro del flujo de integración continua; mientras que en la segunda, veremos un interesante ejemplo ejecutándose como job independiente fuera del flujo.

Ejecutando colecciones como Stage

La gran mayoría de proyectos ya trabaja con Pipelines de Jenkins. Estos suelen tener varios stages para ejecución de diferentes tipos de pruebas. ¿Por qué no ejecutamos estas colecciones como un stage más? Con él ganaríamos un plus de calidad dentro de nuestro flujo.

Esto es muy sencillo, simplemente tendremos que definir un nuevo stage en nuestro JenkinsFile. En él indicaremos la/s llamadas a Newman necesarias para nuestro caso.

Un sencillo ejemplo podría ser:

stage("Postman API Tests") {
          sh “ newman run 'test/nombre_coleccion' -e ruta_entorno;”
        }

Ejecutando colecciones como job Independiente

Independientemente de tenerlo en el flujo de integración continua o no, puede ser que queramos definir un job de Jenkins para ejecutarlo cuando creamos correspondiente.

En este caso, hemos creado un job de tipo pipeline para ser ejecutado en cualquier momento y comprobar que los servicios responden correctamente.

El ejemplo que mostraré a continuación forma parte de un JenkinsFile. Este genera un stage de forma automática para cada colección encontrada en una carpeta, la cual se indica como variable.

  // Ruta environment
  def Environment="environments/Prepro.postman_environment.json"

  //Ruta colecciones Postman
  def rutaColecciones = "**/postman/regressionTests/test/*.json"

//findFiles genera un array con todos los ficheros encontrados en la ruta indicada
def files = findFiles(glob: "${rutaColecciones}")

//Recorremos el array y generamos un stage para cada colección
for (i=0; i<files.length; i++) {

  file = files[i].name
  fileName = files[i].name.replace(".json","")

  stage("$fileName") {
       sh “ newman run 'test/$file' -e $Environment; “ 
  }  

En la imagen podemos ver la vista de este pipeline. En ella comprobamos que, al ejecutarse, ha generado un stage por cada colección, asignándole como nombre el nombre del fichero.

Como QA, me gusta todo lo que ayude a mejorar la calidad de los proyectos en los que colaboro. Por ello, al conocer Newman pensé en cómo usarlo y qué podía aportar en mi día día y acabé añadiendo los dos ejemplos que he mostrado.

Desde entonces, estos forman parte del flujo de integración continua de mi proyecto y también pueden ser ejecutados en cualquier momento para comprobar el estado de la plataforma en distintos entornos.

Una vez terminado este repaso a Newman, sus características y algunas de las opciones que nos ofrece, espero que pueda seros de gran utilidad y que sigáis indagando sobre él y sus múltiples usos.