Pruebas funcionales de una API .NET con Newman y GitHub Actions

Introducción

En este artículo automatizo las pruebas funcionales de una API REST en .NET 8 con Newman, el ejecutor de línea de comandos de Postman. Las pruebas corren solas en GitHub Actions en cada cambio y el reporte se publica en la nube con GitHub Pages.

Las pruebas de API verifican que cada endpoint responda lo correcto: el código de estado, los datos, el formato y las reglas de negocio. Postman es la herramienta más conocida para armarlas a mano; Newman permite ejecutar esas mismas colecciones desde la terminal, así que encaja perfecto en un pipeline de CI/CD.

La API y el repositorio público

La aplicación es Banco API, una Minimal API en .NET 8 para manejar cuentas bancarias, con datos en memoria.

Repositorio público del equipo: github.com/viccarretero/banco-api-pruebas. La misma API también se prueba con k6 para medir su rendimiento; eso lo explica mi compañero Gerald Zevallos en su artículo.

Método	Ruta	Qué hace
GET	`/api/cuentas`	Lista las cuentas
GET	`/api/cuentas/{id}`	Obtiene una cuenta (404 si no existe)
POST	`/api/cuentas`	Crea una cuenta
POST	`/api/cuentas/{id}/depositos`	Deposita dinero
POST	`/api/cuentas/{id}/retiros`	Retira dinero (422 si no alcanza el saldo)
DELETE	`/api/cuentas/{id}`	Elimina una cuenta

La colección de Postman

La colección tests/postman/banco-api.postman\_collection.json tiene 12 peticiones que recorren el ciclo de vida completo de una cuenta: se crea, se deposita, se retira, se elimina y se comprueba que ya no existe. Prueba tanto el camino feliz como los errores:

Caso	Resultado esperado
Obtener una cuenta existente	200, datos correctos y esquema JSON válido
Cuenta que no existe	404 con mensaje de error
Crear cuenta	201 y cabecera `Location`
Crear cuenta sin titular	400 (validación)
Depositar un monto negativo	400
Retirar más que el saldo	422 "Saldo insuficiente"
Eliminar y volver a consultar	204 y luego 404

Cada petición tiene sus pruebas en JavaScript. Por ejemplo, al crear una cuenta se valida la respuesta y se guarda el id en una variable para usarlo en las siguientes peticiones:

pm.test('Status 201 Created', () => pm.response.to.have.status(201)); pm.test('Devuelve la cabecera Location', () => pm.response.to.have.header('Location')); const c = pm.response.json(); pm.test('Cuenta creada con los datos enviados', () => { pm.expect(c.titular).to.eql('Maria Quispe'); pm.expect(c.saldo).to.eql(100); }); pm.collectionVariables.set('cuentaId', c.id);

También se valida el esquema JSON de la respuesta, para detectar si alguien cambia el contrato de la API:

pm.test('Cumple el esquema', () => { const esquema = { type: 'object', required: \['id', 'titular', 'saldo'], properties: { id: { type: 'integer' }, titular: { type: 'string' }, saldo: { type: 'number' } } }; pm.response.to.have.jsonSchema(esquema); });

Automatización con GitHub Actions

El workflow .github/workflows/pruebas-api.yml se ejecuta en cada push o pull request a main. El job de Newman levanta la API dentro del runner, espera a que responda y ejecuta la colección:

- name: Iniciar la API run: | dotnet run --project src/BancoApi -c Release --urls http://localhost:5000 > api.log 2>\&1 \& for i in $(seq 1 60); do if curl -sf http://localhost:5000/health > /dev/null; then echo "API lista"; exit 0; fi sleep 2 done cat api.log; exit 1 - name: Instalar Newman run: npm install -g newman newman-reporter-htmlextra - name: Ejecutar la colección de Postman run: | mkdir -p site/newman newman run tests/postman/banco-api.postman\_collection.json \\ -e tests/postman/local.postman\_environment.json \\ --reporters cli,htmlextra,junit \\ --reporter-htmlextra-export site/newman/index.html

Si alguna prueba falla, Newman termina con error y el pipeline se pone en rojo, así nadie publica una API rota sin darse cuenta. Al final, un último job publica el reporte HTML en GitHub Pages.

Resultados y publicación en la nube

Reporte publicado: viccarretero.github.io/banco-api-pruebas/newman

En la primera ejecución:

Métrica	Valor
Peticiones	12
Validaciones (assertions)	24
Pruebas fallidas	0
Tiempo promedio de respuesta	8 ms
Duración total de la colección	317 ms

El reporte de htmlextra muestra cada petición con su respuesta, sus pruebas en verde o rojo y los tiempos, así que cualquier persona del equipo puede revisar el resultado sin instalar nada.

Conclusiones

Newman convierte una colección de Postman en una suite de pruebas automática: las mismas peticiones que usamos para explorar la API se vuelven un control de calidad que corre en cada cambio. Las pruebas funcionales confirman que la API hace lo correcto; para saber si aguanta muchos usuarios a la vez hace falta una prueba de carga, que es justo lo que cubre k6 en el artículo de Gerald.

Enlaces