DEV Community

Victor Cesar Carretero Hualpa
Victor Cesar Carretero Hualpa

Posted on Edited on

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

#testing #api #postman #githubactions

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);
Enter fullscreen mode Exit fullscreen mode

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);
});
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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

Victor Carretero — Calidad y Pruebas de Software, Universidad Privada de Tacna.

Top comments (0)