¿Por qué es necesario incluir API testing en el pipeline? El desarrollo software se trata de un proceso iterativo, más aún cuando se realiza en un enfoque "agile" en el que se entrega valor de manera incremental.

Cuando se desarrolla de esta manera, los cambios en los sistemas backend o el desarrollo de nuevas funcionalidades tardan en implementarse un cierto tiempo y los consumidores necesitan engancharse a esa funcionalidad lo antes posible para mostrar resultados.

Es en este punto donde las APIs ofrecen su mayor ventaja: exponer esa funcionalidad a los consumidores antes de que los servicios backend estén finalizados.

Con este enfoque se aumenta la agilidad del equipo permitiendo el desarrollo paralelo entre los desarrolladores de movilidad, frontend, terceros e incluso la generación de los tests de integración a la vez que el desarrollo en backend.

La automatización de pruebas con pipelines de integración continua ayudan a esa entrega de funcionalidad de una manera controlada, ofreciendo:

En un post anterior ya se habló en detalle sobre los beneficios del uso de pipelines de Jenkins en proyectos y las APIs como otro eslabón en la cadena del desarrollo y cómo deben incluirse dentro de estos flujos.

A nivel de herramientas de integración continua para APIs, generalmente se dividen en dos categorías:

Este post se centra en la segunda de las categorías, en concreto en herramientas que nos permitan tener un método automatizado para conseguir los siguientes objetivos:

  1. Garantizar que el software entregado cumple con la definición del contrato de la API y no rompe lo que actualmente está siendo consumido mediante los tests de contratos con Postman y Newman.
  2. Tener el control de los cambios que verdaderamente se están subiendo en la nueva versión mediante una librería de comparación de definición de APIs: swagger-diff.
  3. La definición de reglas de calidad del contrato y su cumplimiento mediante Speccy.

¿Qué necesitamos en nuestro pipeline?

Tests de contratos

Los test de contratos o de interfaz nos permiten verificar los esquemas de solicitud y de respuesta de una API y su comportamiento, es decir, qué información retorna un endpoint con diferentes solicitudes. Esta funcionalidad es especialmente útil en dos situaciones:

Con estos test, una vez las APIs pasen del mock a engancharse al servicio backend real, se puede probar de una manera automatizada la integración y detectar posibles desalineamientos que se hayan producido durante el desarrollo.

A su vez, también pueden servirnos en el momento en que se quiera incorporar nuevas funcionalidades en una aplicación a modo de test de regresión para comprobar que todo sigue funcionando como hasta ahora.

Para generar estos tests se puede hacer uso de Postman y Newman siguiendo los siguientes pasos:

Definición del test de validación mediante JSON Schema

Para realizar los tests de contrato el primer paso es generar un JSON Schema con los cuerpos de petición y respuestas de las APIs.

Algunas herramientas como el gateway de AWS generan esos JSON Schema directamente desde el fichero de definición de contrato, Open API Specification (OAS, también conocido como Swagger).

También se pueden utilizar herramientas como jsonschema.net, que nos ayudan con esta tarea y evitar realizarlo a mano.

Postman es una de las aplicaciones más utilizadas para probar APIs. La mayoría de los desarrolladores escriben una prueba simple y verifican el resultado de la API.

Eso está bien para pruebas rápidas y con pocos casos de uso, pero cuando se requiere comprobar un flujo o se tiene un número elevado de casos de uso, es necesario automatizar todo ese proceso, además de gestionar diferentes entornos en cuyo caso la mejor opción es hacer uso del *sandbox *que vienen dentro de la herramienta junto con las variables de entorno.

Postman proporciona funcionalidades de testing mediante scripts basados en Node.js. Estos scripts nos permiten escribir un conjunto de pruebas para generar solicitudes con parámetros dinámicos, pasar datos entre solicitudes, validar esquemas, datos y un montón de verificaciones más. Estos scripts se dividen en dos categorías:

Esta funcionalidad es útil para generar información necesaria de manera previa a la solicitud del endpoint. El caso más habitual es la generación de un token de acceso a la API. La obtención de dicho token es una funcionalidad perfecta para incluir dentro de los test previos al envío de la solicitud.

La consola de test de Postman tiene el siguiente aspecto:

Tanto los tests de pre-solicitud como los tests posteriores se realizan de forma jerárquica en función del nivel en el que se hayan definido dentro de Postman: a nivel de colección, de carpeta o de solicitud siguiendo la siguiente secuencia:

En nuestro caso, para la validación del esquema de la respuesta de la API, se hace uso de los test a nivel de solicitud mediante la librería tv4, incluida en Postman.

Una posible propuesta para realizar una validación de un contrato a través de tv4, sería mediante las siguientes comprobaciones en cada petición:

En caso de recibir una respuesta correcta al ejecutar la petición tendríamos lo siguiente:

Un ejemplo de test que devuelve un error de validación es el siguiente:

Un error de validación de JSON Schema puede deberse a diferentes causas:

La documentación oficial con scripts de ejemplos para testear puede verse en detalle en la página oficial de Postman.

Variables de entorno

El siguiente paso, tras la implementación de los tests, es definir las variables de entorno para los mismos. En Postman, un entorno se trata de un conjunto de variables de tipo clave-valor.

Dichos entornos permiten definir valores asociados a esas variables y que esos cambios se reflejen en las solicitudes de las APIs. En un entorno se pueden definir múltiples variables y se pueden utilizar múltiples entornos, pero en cada ejecución de tests sólo se hace uso de uno de dichos entornos y, por tanto, solo del conjunto de pares valor incluidos en él.

Para generar un entorno desde Postman se crea desde su consola y se añaden las variables con sus correspondientes valores de la siguiente forma:

Las valores asociados a las variables definidas dentro de un entorno pueden utilizarse tanto en las peticiones como en los scripts de los tests.

De esta forma se pueden definir tests válidos entre entornos, incluyendo en las variables aquella información que cambie entre ellos, por ejemplo el endpoint, la api-key o incluso en caso de que se tengan versiones de API desplegadas distintas en cada entorno, el JSON Schema correspondiente a cada versión.

Una vez se tienen definidos los tests y las variables de entorno asociados a los mismos se pueden ejecutar los tests a nivel de colección o carpeta dentro de la consola del producto con el "Runner" de la siguiente forma:

Obteniendo el siguiente resultado:

Exportación de los tests y variables de entorno

Si queremos lanzar las pruebas anteriores de una manera automatizada desde nuestro pipeline necesitamos exportar los archivos configurados en Postman.

Por un lado, las colecciones de tests y, por otro, las variables de entorno asociadas de las siguiente manera:

En este punto, una vez se hayan generado los tests y se hayan exportado, se tienen los siguientes ficheros:

Con este conjunto de ficheros que gestionamos dentro de un repositorio de código como Git, nos ayuda a tener un control total de los cambios y un histórico de los mismos.

Cuando se quiera añadir una funcionalidad nueva y se actualicen estos ficheros se abre una Pull Requests, que será el disparador de nuestro pipeline de integración continua en el que como primer paso se ejecutarán los tests incluidos en el repositorio, pero para realizar esa ejecución desde línea de comandos necesitamos Newman.

Ejecución de los tests con Newman vía línea de comandos

Newman se trata de una herramienta que permite ejecutar los tests definidos en Postman por línea de comandos, al igual que se haría mediante la propia aplicación como vimos antes.

Newman es fácilmente integrable en Jenkins, ya que está construido en Node.js, por lo que para su instalación es muy sencilla mediante *npm *siguiendo los pasos descritos aquí.

Para ejecutar los tests definidos en el archivo exportado desde Postman simplemente es necesario ejecutar el siguiente comando:

Siguiendo el ejemplo anterior tendríamos lo siguiente:

Conclusiones

Los tests de contratos constituyen la primera fase de nuestro flujo de validación de APIs dentro de nuestro pipeline de integración continua y su inclusión supone las siguientes ventajas:

Cuéntanos qué te parece.

Enviar.

Los comentarios serán moderados. Serán visibles si aportan un argumento constructivo. Si no estás de acuerdo con algún punto, por favor, muestra tus opiniones de manera educada.