Si alguna vez has tenido que testear el comportamiento de una API ya implementada te habrás tenido que sentar un buen rato a pensar qué tienes que probar y cómo hacerlo. También habrás pensado en cómo verificar que el comportamiento es el adecuado para cada caso de uso. Vaya… también te has tenido que plantear los casos de uso.
Aún no has verificado nada y ya tienes un montón de trabajo. Y todavía hay más: cuando termines de definir la Test Suite (que es lo que has estado haciendo hasta ahora) tienes que probar la API y verificar cada caso de uso. ¿Cómo verificas y registras los resultados? ¿Mirando caso por caso? ¿Escribes los resultados en una hoja Excel o en un documento de texto?
Seguro que todo lo anterior te ha hecho plantearte si las APIs que tu organización o tú mismo has desarrollado están correctamente probadas. Es un trabajo difícil que requiere atención y mimo. Pues para satisfacción tuya, nuestra y de todo aquel al que le preocupe cómo probar sus APIs, en CloudAPPi hemos desarrollado una herramienta que te permite hacer todo este trabajo con menos esfuerzo. Eso siempre y cuando hayas definido tu API utilizando el estándar OpenAPI en su versión 2.0, también conocida como swagger.
No hay recetas mágicas, siempre tienes que hacer un trabajo previo. El trabajo de definir lo mejor posible una API es la base de todo proyecto que implique su utilización. Si tienes esa definición hay multitud de herramientas para hacer lo que necesites, y swaggerToPostman (OpenAPI2postman) es una de ellas.
¿Qué debería saber antes de seguir leyendo?
Lo ideal es que estés familiarizado con Postman, que es quizá la herramienta más conocida para realizar llamadas a una API, especialmente cuando se trata de una API REST. Postman organiza las llamadas en colecciones, que son agrupaciones de llamadas a una o más APIs.
Otro concepto a tener en cuenta son los entornos Postman. Un entorno Postman permite almacenar variables con valores específicos del entorno contra el que se quieran realizar las llamadas de una colección. Dichas variables se utilizan desde las llamadas almacenadas en las colecciones, de forma que es posible mantener una colección intacta y probarla contra distintos entornos con solo clonar uno de ellos y cambiar los valores de las variables que contiene.
Además de Postman sería ideal que conocieras OpenAPI, o al menos que hayas visto alguna vez un documento de definición de API elaborado siguiendo la especificación de OpenApi. Quizá no lo conozcas y la definición de la API te llegue ya hecha. Pues es el momento de que entiendas cómo se realiza dicha definición, porque de ella dependerá el resultado que obtengas de swaggerToPostman (OpenAPI2postman).
OpenAPI2Postman
OpenAPI2Postman es una aplicación desarrollada en node.js que permite generar colecciones y entornos Postman a partir de un archivo de definición swagger escrito en formato yaml. Como mínimo se generará una colección y un entorno, pero es posible configurar las colecciones y entornos a generar, sus nombres, el tipo de llamadas que contendrán las colecciones y algunos de los valores de las variables de entorno. En concreto puedes configurar lo siguiente:
Nombre de la colección generada
Nombre del entorno generado
Máquina y puerto del servidor al que se llamará
Basepath o contexto de la API a invocar
Inclusión de llamadas que escriben datos (POST, PUT, PATCH y DELETE)
Carpeta de destino de los archivos generados
Carpeta de origen de las llamadas necesarias para obtener tokens de autorización si son necesarios.
La configuración se especifica por medio de un archivo JSON en el cual se especifican dichos parámetros por cada colección y entorno a generar.
También se debe especificar el origen del archivo de definición. Por lo tanto los dos únicos parámetros que necesitas para ejecutar la herramienta son:
Archivo de definición swagger (recuerda, en yaml)
Archivo de configuración (json)
Si tienes ambas cosas ya puedes generar tus suites de pruebas, aunque para ello será necesario que la máquina en la que vas a ejecutarla tenga instalado node.js y su gestor de paquetes, npm. (La instalación de estas herramientas no es objeto de este post)
Si ya tienes node y npm instalados sólo tienes que abrir un terminal, situarte en la carpeta raíz donde hayas descargado el proyecto swaggerToPostman y ejecutar:
npm install
node index.js –file {ruta al archivo de definición swagger} –configuration {ruta al archivo json de configuración}
¿Qué debería ocurrir?
Si todo ha ido bien deberías haber obtenido tantas colecciones y entornos como hayas configurado en el archivo json, situados en las carpetas que hayas especificado y con los nombres que hayas elegido. Si no has especificado carpetas de destino entonces deberían estar en la carpeta raíz del proyecto.
Esto es lo más interesante de todo. Si usamos esta herramienta es para no tener que diseñar e implementar la test suite de la API. Pues eso es precisamente lo que contiene la colección. En concreto se probarán los siguientes aspectos:
Respuestas correctas:
200: Se recibe una respuesta con status 200 cuando todo ha transcurrido con normalidad en peticiones GET, PATCH, PUT y DELETE. En este caso se comprueba el status y se valida que el esquema de la respuesta se corresponde con el especificado en el documento de definición. En realidad se valida el esquema en todas las peticiones, por lo que omitiremos este resultado en las sucesivas descripciones
201: Se recibe este status cuando se envía una petición POST y todo transcurre con normalidad. Se comprobará el status.
206: Se recibe este status cuando se envía una petición GET y se recibe un listado paginado. Se comprobará el status.
Errores de cliente:
400: Obtenemos una respuesta con status http 400 cuando cometemos un error al hacer la petición. Por ejemplo no enviar un parámetro obligatorio, dejar el cuerpo de una petición POST vacío o no enviarlo. Para estos casos se comprueba:
Que se recibe un status 400 cuando no enviamos un parámetro obligatorio
Que se recibe un status 400 cuando el valor de un parámetro, obligatorio o no, es erróneo (no es del mismo tipo, es un valor excluido del rango aceptado, etc). Los valores erróneos no se generan, sino que se generan variables de entorno que se deben cumplimentar antes de ejecutar la test suite.
401: Obtenemos este status cuando no tenemos el token, APIkey o mecanismo de autorización necesario para acceder a la API. Estas peticiones se generarán cuando se incluya una colección auxiliar con las peticiones necesarias para obtener la autorización. En concreto se probará que se recibe un 401 cuando no se aporta la autorización.
404: Este status se devuelve cuando se consulta un recurso y no es posible encontrarlo. Para estos casos se comprobará que se recibe este status cuando se aporta un identificador de recurso no existente, el cual se especificará en una variable de entorno. Al igual que con los valores erróneos para los parámetros se debe cumplimentar esta variable antes de la ejecución de la test suite.
¿Y con esto es suficiente?
Pues depende. Es probable que no se generen todas las peticiones que te gustaría. Ten en cuenta que sólo con la definición de la API no podemos conocer el negocio de la misma, no sabemos cómo está implementada.
También es posible que te preguntes por qué no se comprueban errores de servidor. Pues por el mismo motivo que antes: para provocar un error de servidor lo primero que es necesario es que la implementación de la API produzca errores incontrolados o no se encuentre disponible. Es fácil deducir que sin conocer la implementación no podemos provocar un error no controlado. Tampoco podemos conocer cuándo el backend de la API no va a estar disponible, ni cuándo se va a producir un timeout, etc. Si quieres probar esas respuestas tendrás que forzar las condiciones en las que se producen, pero en la mayoría de los casos ni siquiera será el propio backend el que te responda. Queda a tu elección.
¿Cómo ejecutar la test suite?
Los archivos generados son archivos en formato JSON siguiendo una definición propia de Postman. Por lo tanto la herramienta a utilizar es….Postman.
Abre Postman y pulsa el botón importar. Selecciona los archivos que acabas de generar. La colección aparecerá a la izquierda, en la pestaña colecciones
Los entornos se ubican en la parte derecha de la interfaz de usuario. Para dar valores a las variables pulsa el icono de la rueda dentada, selecciona el entorno que quieres editar y asigna los valores oportunos. Quizá tengas que examinar atentamente la colección antes de hacerlo para saber a qué llamada corresponde cada una de ellas
Una vez tengas configurado el entorno usa la herramienta runner de Postman para ejecutar la test suite completa. La herramienta te dará el resultado de cada prueba una por una.
OpenAPI2Postman es una herramienta que te facilita el proceso de testing de APIs. Los archivos generados, una vez completos pueden servirte para automatizar las pruebas mediante integración continua ayudándote de Newman, la implementación para línea de comandos del runner de Postman. Si hasta ahora no has tenido la ocasión de hacer un proceso de testing de APIs con unas garantías mínimas OpenAPI2Postman te va a ayudar a desarrollarlo. Sólo debes tener en cuenta que OpenAPI2Postman es un recién nacido, y los bebés requieren paciencia y cariño.
Esperamos que te sea de utilidad.
