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:
- Comprueba que
/api/healthresponda HTTP 200 y declare el servicio correcto. - Crea un item y verifica el HTTP 201, la presencia de un identificador y el nombre enviado.
- Consulta la lista y confirma que contiene el item recién creado.
- Envía un nombre inválido y espera HTTP 422 con el código
invalid_name. - 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
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
- Postman. Install and run Newman.
- Postman. GitHub Actions integration.
- Cloudflare. Workers deploy command.
Top comments (0)