Postman CLI en CI/CD: automatiza y escala tus pruebas

Artículo de Daniel Balletbó; Isabel Arnaiz

Tras haber abordado lo básico de la herramienta en Postman: una guía rápida para principiantes, profundizado en variables, entornos y colaboración en Postman: Guía avanzada con entornos, tests y mock servers, y visto cómo integrar las colecciones en entornos de CI/CD gracias a Newman: la CLI de Postman, en este artículo exploraremos un paso más en la optimización de tus flujos de trabajo con Postman.

Encontrarás ejemplos prácticos, configuraciones avanzadas y consejos para sacar el máximo provecho a la suite de herramientas, de modo que tu equipo pueda automatizar pruebas de API, así como colaborar y monitorizarlas de forma eficiente.

Postman CLI

Postman CLI es un acompañante de línea de comandos seguro para Postman. Está asegurado y respaldado por Postman, permitiendo lo siguiente:

Ejecutar una colección con su ID o ruta
Enviar resultados de ejecución a Postman de forma predeterminada
Permite iniciar y cerrar sesión
Verifica las definiciones de API con las reglas de seguridad de API

Instalar postman CLI

Postman CLI soporta los mismos requisitos de sistema operativo que la aplicación normal de escritorio de Postman.

La instalación a través de línea de comandos varía según el sistema operativo que se esté usando, a continuación los comandos necesarios para la instalación en windows y en linux:

Windows:

powershell.exe -NoProfile -InputFormat None -ExecutionPolicy AllSigned -Command "[System.Net.ServicePointManager]::SecurityProtocol = 3072; iex ((New-Object System.Net.WebClient).DownloadString('https://dl-cli.pstmn.io/install/win64.ps1'))"

Linux:

curl -o- "https://dl-cli.pstmn.io/install/linux64.sh" | sh

Comandos básicos de Postman CLI

A continuación tres de los comandos básicos de postman. En ellos encontrarás ítems como la APIKEY o la collection key. Para obtener ambas sigue los pasos especificados en este apartado de nuestro artículo anterior: Automatiza tus pruebas con Newman: la CLI de Postman ignorando lo que refiere a Newman.

Login / logOut

postman login --with-api-key ABCD-1234-1234-1234-1234-1234

postman logout

Run collections

postman collection run 12345678-12345ab-1234-1ab2-1ab2-ab1234112a12

Ejecutar Postman collection en gitlab CI pipeline

Postman CLI puede usarse para ejecutar colecciones tanto manual como de forma automatizada. En este caso veremos cómo ejecutarlas automáticamente a través de gitlabCI.

PASOS A SEGUIR:

Asegurarnos de tener una Api Key creada para este caso. ( Lo explicamos aquí: Crear una Postman API key
Obtener la collection_uid de la colección que queremos ejecutar. (Lo explicamos aquí: Obtener el collection_uid, obviar lo referente a newman).
Obtener el environment_uid del environment que tenemos enlazado a la colección. (Lo explicamos aquí: Obtener el environment_uid).
Entrar en postman y seleccionar la colección que queremos correr, una vez seleccionada clicar en la opción run.
Dentro aparecerán las opciones para poder especificar lo que se necesita dentro del archivo .gitlab-ci.yml.
- Seleccionar bien la colección y el environment que queremos usar.
- Seleccionar la configuración de CI que queremos, en este caso será gitlab y se usará un linux.
Una vez completados los pasos anteriores, nos aparecerá la estructura con los detalles de lo que necesitamos añadir al archivo gitlab-ci.yml.

Notas:

Ese documento variará según las necesidades que haya.
Por defecto postman usa una imagen la cual incluye varias opciones que facilitan las interacciones continuas, pero es una imagen muy pesada y que quizás trae cosas que realmente no necesitamos. Siempre es buena idea buscar algo que se ajuste mejor a las necesidades y asegurarse de que postman cli ofrece el soporte para dicha imagen. (por ejemplo, alpine no es compatible).
Según la imagen que se use los comandos cambiarán.la configuración del proyecto de gitlab para la api key.
Habrá que crear una variable de entorno dentro de la configuración del proyecto de gitlab para la api keyodo expuesto es el de usar la api con los uids correspondientes el otro es usar los archivos json generados por postman.
Hay cambios en cuanto a la manera de leer las peticiones dependiendo de que método se está usando. El método expuesto es el de usar la api con los uids correspondientes el otro es usar los archivos json generados por postman.
- ¿Cual es la diferencia?
- Cuando se está pasando un parámetro :algo por url

Monitoring

Postman ofrece una opción de monitoreo de nuestra colección:

Jenkins

Programar las ejecuciones desde Jenkins es el último paso para una automatización efectiva. Debemos instalar Newman en el mismo Jenkins o en el esclavo que ejecutará los test. Además, necesitaremos el plugin de email extension y el Log Parser. Este último plugin, desde la configuración de Jenkins ha de aparecer del siguiente modo:

En la descripción indicamos qué va a parsear, por ejemplo “Error parsing” y en el campo Parsing Rules File indicamos el nombre de un archivo que ha de estar en la raíz de Jenkins con las reglas. Este archivo tiene el siguiente contenido:

error /AssertionError/

Con esta configuración, creamos un nuevo job con la siguiente información:

Nombre del proyecto: SWPostman (por ejemplo)
Dónde se ejecutara: testing (por ejemplo)
Souce code: Git, añadiendo la ruta del repositorio donde tengamos el código
Build → Add build step → Execute Shell y escribimos la misma series de comandos que escribíamos para ejecutar Newman en local: newman run -e swenvironment.json swcollection.json
Post-build Actions → Add post-build action → Console Output (build log) parsing
- Seleccionando Use global rule, en Select Parsing Rules seleccionamos “Error Parsing”, que es la descripción que hemos puesto a la parsing rule.
Post-build Actions → Add post-build action → Editable Email Notification, y rellenamos la siguiente información:
- Project Recipient List: Direcciones de correo que deben recibir el email.
- Advanced Settings → Add Trigger → Script – After Build
  - Trigger Script → Groovy Script:
    //solo mandará un email si encuentra AssertionError en los logs build.logFile.text.readLines().any { it =~ /.*AssertionError.*/ }

Guardamos y ejecutamos con “Build now”.

La salida por consola mostrará prácticamente lo mismo que veíamos desde local mas otras líneas que indican parte del proceso del job.

Al ejecutar un job que tiene un fallo a propósito, se recibe también un email con un pequeño resumen de la ejecución y un link para acceder a esa ejecución en Jenkins.

Desde el resumen de la ejecución podemos hacer clic en el link “Parsed Console Output” y hacer clic en el error generado. Esto nos permite acceder al punto del log en el que aparece el propio error:

JenkinsFile

pipeline{
     agent {
            label 'testing'
     }
     stages {
             stage('Test') {
               steps {
                 checkout scm    
                     echo "Executing tests..."
                     sh "newman run -e swenvironment.json swcollection.json -r htmlextra"
                     echo "Test execution completed."
                   }
             }
     }
}

Newman Reports

Newman nos permite generar un informe en formato html con un desglose de las consultas y sus resultados:

Para poder generar este fichero, primero tenemos que instalar htmlextra:

npm install -g newman-reporter-htmlextra

Una vez instalado, para generar el fichero html con los resultados, ejecutamos:

newman run -e swenvironment.json swcollection.json -r htmlextra

Este comando nos creará una carpeta llamada newman, donde se almacenarán los ficheros resultantes:

Instalar Plugin para añadir formato HTML en Jenkins

Además de hacerlo de forma local, también podemos hacer que Jenkins nos genere un documento HTML con la información de las consultas y sus resultados. Para ello debemos, primero de todo, instalar el plugin HTML Publisher.

Primero de todo, en Jenkins, accedemos a Administrar Jenkins > Administrar Plugins y buscamos en el buscador el plugin en cuestión para instalarlo.

En Job de Jenkins:

En JenkinsFile:

post{
always {
                    publishHTML (target: [
                              allowMissing: false,
                              alwaysLinkToLastBuild: false,
                              keepAll: true,
                              reportDir: 'newman/',
                              reportFiles: 'SW2*.html',
                              reportName: "NewmanReport"
                    ])
 }
}

Vista del fichero desde Jenkins:

Si miramos el fichero .html generado desde el propio Jenkins, veremos que este aparece sin .css. Para arreglarlo, tenemos que hacer lo siguiente:

Panel de control -> Administrar Jenkins -> Administrar Nodos -> Botón del engranaje sobre el nodo (a la derecha) -> Consola interactiva
Una vez en la consola, introduciremos el siguiente comando: $System.setProperty("hudson.model.DirectoryBrowserSupport.CSP", "")
Y le daremos a ejecutar.

Una vez hecho esto, todas las ejecuciones futuras se mostrarán con el .css correctamente.

Variables de entorno:

En el caso que quisiéramos ejecutar Newman accediendo a la colección a través de la API de postman, tendremos que proporcionarle una API KEY (explicado aquí). Si esto lo tenemos en Jenkins hardcodeado, supone un riesgo de seguridad, ya que cualquiera que tenga acceso a Jenkins va a poder ver nuestra API KEY. Para solucionarlo, vamos a guardar el valor de la KEY como una variable de entorno.

Para hacerlo, iremos a:

Panel de control -> Administrar Jenkins -> Manage Credentials -> En la Store, elegiremos Jenkins (dependiendo del scope que queramos) -> Global credentials (unrestricted) -> adding some credentials.

Una vez ahí, veremos que se nos da bastantes opciones en Kind. Si lo que queremos es, en este caso, guardar un valor de KEY, vamos a seleccionar “Secret text”

En “secret” introduciremos el valor de la API KEY, mientras que en “ID” indicaremos el nombre que le queramos dar a la variable para después acceder a ella. Opcionalmente podemos indicar una descripción de esa variable.

Una vez creada, vamos al Job donde queramos usarla. Ahí, en Entorno de ejecución, elegiremos la opción “Use secret text(s) or file(s)”. Indicaremos el nombre que queremos que tenga la variable en ese job, y el mapeo a qué variable global queremos usar. En este caso, el nombre que tendrá nuestra variable en este job será APIKEY así que en el comando de ejecución accederemos a su valor usando ${APIKEY}.

Lo interesante, es que el valor de la APIKEY no se muestra en ningún momento. De hecho, si lo ejecutamos y vamos a ver el output de la consola, veremos que en vez de ver el valor de la APIKEY, nos aparecerá ****:

Ahora que ya conoces todo esto, podrás ir más allá de la simple ejecución de pruebas, integrándolas perfectamente en tu ciclo de desarrollo y asegurándote de que tanto tu equipo como tus APIs alcancen su máximo potencial. La combinación de las guías anteriores con las técnicas descritas en este artículo te permitirá consolidar tu estrategia de calidad y cobertura de pruebas.

Si has leído la guía al completo, gracias por llegar hasta aquí, si aún quieres más, puedes seguir leyendo nuestro ebook gratuito con muchos más consejos sobre QA y automatización de pruebas.