Hola, comunidad!

 

Después de crear la app IrisApiTester, me di cuenta que podría tener mas potencial, y que con algunos ajustes, podría convertirse en una poderosa herramienta colaborativa.

Me pregunté a mi mismo:

• ¿Podría compartir la colección con un equipo de desarrolladores?
• ¿Podría usarlo para realizar test unitarios?
• ¿Y test de integración?
• ¿Y si le añadiésemos una capa de CI/CD?

 

Después de pensar esto, me decidí a intentarlo. Y descubría que todas las respuestas fueron afirmativas (con algunos matices xD). Finalmente, me he decidí a escribir este artículo y compartir mi experiencia con vosotros. Espero que nos sirva para intercambiar conocimientos y porque no mejorar la aplicación juntos.

 

Para no hacer el artículo muy extenso, lo he dividido en varias partes. De este modo tendréis la opción de ir directamente al apartado que os interese en lugar de leer el artículo completo.

Para seguir los pasos asumo que ya dispones de una instancia de la imagen del Docker de IrisApiTester funcionando. Si no es así puedes consultar como seguir los pasos en esta guía que redacté:

https://es.community.intersystems.com/post/iris-api-tester-español

 

Punto 1 - Compartiendo la colección Postman entre el equipo:

 

La primera cosa que me pregunté a mi mismo fue ¿Como puedo compartir mi colección de Postman entre todos mis compañeros?, y la solución fue mucho mas simple de lo que esperaba.

Descubrí que se podía conectar Postman con un repositorio que contuviese una o varias colecciones de API's y que Postman incluye un cliente Git para descargar las colecciones del repositorio y hacer commits desde el propio Postman sin tener que cambiar al terminal ni nada adicional. Posiblemente esto sea algo que muchos ya sabíais pero de lo que yo nunca me había percatado.

Manos a la obra!, os voy a explicar como conectar Postman con un repositorio que contenga la colección de un API.

 

Para el ejemplo, he creado un repositorio en GitHub. Lo he probado con Bitbucket y también funciona si preferís Bitbucket a GitHub.

Este es el link a mi repo:

https://github.com/daniel-aguilar-garcia/postman-collection-test

 

La colección contiene unos simples test que apuntan a la instancia IrisApiTester que tengo en local en un Docker.

 

Lo primero que haremos será conectar con el repositorio.

 

Abrimos Postman, hacemos click en Apis y en crear Api:

 

Después elegimos el nombre de la colección y hacemos click en el icono de GitHub (O de Bitbucket)

 

Si os pregunta por autorización simplemente dadle permisos haciendo login con vuestro usuario:

 

Una vez la petición sea aceptada, selecciona tu usuario de GitHub, el repositorio donde tienes almacenadas las API's, y la rama del repositorio:

 

Una vez conectados (a no ser que sea un nuevo repositorio vacío), la colección API que habéis seleccionado debería aparecer en el menú:

 

Todas las colecciones del API aparecerán en el menú:

 

Si hacemos algún cambio en la colección, aparecerá reflejado en la sección de Git inmediatamente. Desde esta podremos realizar operaciones de commit, full y push.

 

 

Si tenéis una licencia de pago de Postman, lo único que debéis de hacer en los ordenadores del resto del equipo será conectaros al mismo Workspace y listo, si usáis una cuenta gratuita, deberéis repetir estos pasos en todos los ordenadores de los desarrolladores del equipo.

Una vez completados los pasos anteriores ya podréis mantener actualizada la colección de test entre todos los desarrolladores. Si usáis una cuenta gratuita la "única" pega es que tiene un límite de 3 APIs, así que si este es vuestro caso, os recomiendo que pongáis todas la colecciones en el mismo repositorio para evitar problemas.

 

Punto 2 - Test unitarios:

 

El siguiente punto era como usar la aplicación para test unitarios además de tests para Apis. En este punto me pregunté como podría generar de una manera rápida los endpoints para mis test sin tener que crear entradas en el fichero de rutas para exponer cada uno de ellos. I esto es lo que se me ocurrió:

Creé una aplicación en el raíz llamada /run

 

También creé una clase para el API. En ella creé la siguiente ruta (En el repositorio está en el fichero TestRoutes.cls)

 

Con esta ruta, seremos capaces de "auto publicar" cualquier método de cualquier clase simplemente pasando el nombre de la clase y del método que queremos ejecutar en la ruta. Ejemplo:

localhost:52773/run/IrisNewman.Example.TestMethods/TestOK

 

En este caso, se indica lo siguiente:

/run -> ruta WebApp

/IrisNewman.Example.TestMethods -> la clase que contiene el meted que queremos ejecutar

/TestOK -> el metodo a ejecutar

 

En el metodo TestOK, realizo una simple operación para comprobar el test unitario:

ClassMethod TestOK() As %Status
{
    Set testNumber = 1
    Set a = 1
    Set b = 2
    Set res = ..SumNumbers(a,b)

    Do ..assert(res,3,$G(%methodname),testNumber)

    Quit $$$OK
}

 

Una peculiaridad de esta clase, es que he definido mi propio método assert. El método evalúa que el primer parámetro y el segundo sean iguales. El tercer parámetro es el nombre del método que se está ejecutando y el cuarto parámetro es el nº de prueba. Estos 2 últimos parámetros solo los uso para devolver una respuesta mas detallada en caso de que falle la aserción. Si los valores comparados no coinciden, el método lanza una excepción enviando el código de respuesta 500 a la cabecera de la petición. Esto hace que aparezcan como fallido y con el detalle en el reporte de Newman.

 

Con este enfoche, lo único que quedaría por hacer sería:

• Incluir una llamada al metodo en nuestra colección de Postman.
• Hacer commit de los cambios

 

De este modo, cualquier que tenga la colección y haga Pull tendrá la colección de los test actualizada.

 

 

Punto 3 - Test de Integración:

 

Del mismo modo, que en el paso anterior, podemos usar la WebApp para realizar test de integración. Un ejemplo podría ser añadir información de una persona a nuestra base de datos:

localhost:52773/run/IrisNewman.Example.TestMethods/InsertPerson

 

En este caso, indica lo siguiente:

/run -> ruta WebApp

/IrisNewman.Example.TestMethods -> la clase donde está el meted a ejecutar

/InsertPerson -> el método a ejecutar

 

En el metodo InserPerson, realizo todas las operaciones dentro de una transacción y compruebo con el método assert que los valores que se almacenan son correctos. Finalmente realizo un Rollback para deshacer todos los cambios:

ClassMethod InsertPerson()
{

    Set testNumber = 1
    Set method=$G(%methodname)

    TSTART
    Set person=##class(IrisNewman.Example.Entity.Person).%New()
    Set person.IDCard="11111111H"
    Set person.Name="Incognito Guy"
    Set person.Address="False Street, 123"
    Set person.City="Springfield"
    Set res = person.%Save()

    Do ..assert(res,1)

    Set personReaded = ##class(IrisNewman.Example.Entity.Person).%OpenId(person.IDCard)

    Do ..assert(personReaded.Name,"Incognito Guy",method,testNumber)

    TROLLBACK
    Quit $$$OK
}

 

Del mismo modo, podemos lanzar pruebas de actualización, borrado, etc... es decir realizar cualquier test de integración que necesitemos.

 

Punto 4 - Añadir CI/CD:

 

Llegados a este punto posiblemente estés pensando: "Ok, esto está bien, pero yo quiero algo mas automatizado. ¿Como puedo lanzar el test de mis colecciones de pruebas automáticamente?

Para ello, he creado un nuevo endpoint en la App (Debe ejecutarse desde un navegador, no desde Postman):

http://localhost:52773/pull_and_run_tests

 

Este endpoint descarga la última versión de la colección desde el repositorio de GitHub o Bitbucket. Ejecuta los test y muestra el Report de Newman con los resultado por pantalla:

 

Para que funcione el endpoint pull_and_run_test, debemos configurar previamente los datos con la información de acceso a nuestro repositorio informándolo en el fichero repository.cfg:

 

Cuando llegué a esta parte, tenía una idea dando le vueltas a mi cabeza, estaría genial poder añadir esto a un Workflow en el repositorio que pudiese lanzar las pruebas automáticamente cada vez que hago un commit...

 

Y creé este otro nuevo endpoint:

http://localhost:52773/pull_run_and_send_google

 

Hace lo siguiente: descarga una imagen de IrisApiTesting, descarga la colección de Postman del repositorio, después ejecuta los test y finalmente envía un mensaje con la URL del informe Newman en HTML a un Canal de Google Chat.

 

Para que funcione, en el fichero repository.cfg debemos configurar la URL de el webhook de nuestro canal de Google Chat donde queremos recibir el mensaje:

 

En la siguiente pantalla, podéis ver un ejemplo de la ejecución del workflow después de cada commit en el repositorio:

 

Este es un ejemplo del código que he usado en mi Workflow de GitHub:

name: Launch Tests
on:
  push:
    branches:
      - main
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
    - name: Checkout source code
      uses: actions/checkout@v2
    - name: Clone the irisapitester repository
      run: git clone https://github.com/daniel-aguilar-garcia/irisapitester.git
    - name: Raise Docker Compose
      run: docker-compose up -d
      working-directory: ./irisapitester
    - name: Wait for Docker
      run: sleep 30
    - name: Send report to Google Chat
      id: send_report_google
      run: |

        $(curl -s http://localhost:52773/pull_run_and_send_google)

 

Y esta es una captura del mensaje que llega al canal de Google Chat:

(En mi ejemplo, simplemente he enviado la URL, pero podríamos programar que se enviase el mensaje solo si fallan los test o que llegue acompañado de un mensaje indicando que el test ha ido OK o KO, etc...)

 

Nota: Si estáis pensando enviar mensajes, configurad la ruta de destino donde se guardan los reports en HTML de Newman en una unidad de red donde tenga acceso el Docker a fin de que podáis acceder al fichero posteriormente ya que si ponéis una ruta local del Docker el fichero se será inaccesible cuando se destruya el Docker al finalizar el Workflow. Para modificar la ruta donde almacenar el HTML modificad el parámetro executionsTestPath a la ruta deseada en la clase IrisNewman/Api.cls

 

 

 

Espero que hayáis encontrado interesante el artículo y os pueda ser de ayuda en vuestro día a día o que al menos os haya dado alguna idea de como aplicar algo de lo visto en el artículo para algún desarrollo vuestro.

Vuestros comentarios son bienvenidos. Os animo a preguntar cualquier cosa que no haya quedado clara en los comentarios.

 

Gracias por dedicar vuestro tiempo a leer el artículo!