DEV Community

Pruebas de API reproducibles con Newman y GitHub Actions

Autora: Gabriela Estefania Cohaila Alvarado (2022075746)

Repositorio público: https://github.com/GabrielaCohailaAlvaradoE/api-pulse-newman-testing

API pública: https://api-pulse-newman.everlasting-octopus.workers.dev/api/health

Panel desplegado: https://gabrielacohailaalvaradoe.github.io/api-pulse-newman-testing/

Video: agregar el enlace público de YouTube al finalizar la publicación.

Introducción

Probar una interfaz no es suficiente para afirmar que una aplicación funciona correctamente. Una API puede devolver un estado HTTP erróneo, cambiar la estructura de un JSON, aceptar una entrada inválida o eliminar información inesperadamente. Por eso, en este proyecto construimos API Pulse, una API REST pequeña y una colección de pruebas ejecutable con Newman, el runner de línea de comandos para colecciones Postman.

La meta fue crear un proceso repetible: iniciar la API, ejecutar el mismo conjunto de solicitudes, validar códigos de respuesta y contratos, y conservar el resultado en integración continua.

La API evaluada

API Pulse se implementó como un Cloudflare Worker y expone recursos de ejemplo:

Método Ruta Resultado esperado
GET /api/health Estado ok y nombre del servicio
GET /api/items Lista y contador de recursos
POST /api/items Recurso creado con HTTP 201
GET /api/items/:id Recurso individual o HTTP 404
DELETE /api/items/:id Eliminación con HTTP 204

El endpoint de creación valida que name tenga entre 3 y 80 caracteres y que status sea open o done. Cuando la regla no se cumple, la API responde con HTTP 422 y un objeto de error estructurado. Esta validación es especialmente útil para demostrar que una prueba de API no se limita a verificar respuestas exitosas.

La colección Postman y Newman

La colección se almacena versionada en tests/api-pulse.postman_collection.json. Esto hace que el equipo pueda revisar cambios a las pruebas en el mismo pull request que modifica la API.

Newman ejecuta cinco solicitudes y nueve aserciones:

  1. Comprueba que /api/health responda HTTP 200 y declare el servicio correcto.
  2. Crea un item y verifica el HTTP 201, la presencia de un identificador y el nombre enviado.
  3. Consulta la lista y confirma que contiene el item recién creado.
  4. Envía un nombre inválido y espera HTTP 422 con el código invalid_name.
  5. Elimina el item de prueba y espera HTTP 204.

La ejecución es sencilla:

npm ci
npm run dev
npx newman run tests/api-pulse.postman_collection.json \
  --env-var baseUrl=http://127.0.0.1:8787
Enter fullscreen mode Exit fullscreen mode

El uso de una variable baseUrl permite apuntar exactamente la misma colección al Worker local o al servicio público. Durante la validación remota, las nueve aserciones pasaron contra la URL de Cloudflare Workers.

Automatización en GitHub Actions

El workflow de CI inicia un Worker local, espera el health check y ejecuta Newman en cada push, pull request o ejecución manual. El reporte JUnit se guarda como artefacto de GitHub Actions. Si una aserción falla, el job se marca como fallido antes de aprobar el cambio.

Esto transforma la colección en un control preventivo, no en una lista de pasos manuales. También fija las acciones de GitHub a hashes de commit inmutables para reducir el riesgo de depender de etiquetas móviles.

Conclusión

Newman nos permitió convertir una colección Postman en una prueba automatizada, visible y repetible. El proyecto demuestra que una API debe probar tanto casos correctos como errores de validación y efectos de escritura. Integrar estas pruebas en CI ayuda a detectar regresiones cuando todavía son pequeñas y fáciles de corregir.

Referencias

  1. Postman. Install and run Newman.
  2. Postman. GitHub Actions integration.
  3. Cloudflare. Workers deploy command.

Top comments (0)