Pruebas de API con Postman

Teoría

Qué prueba Postman (y qué no)

Postman es un cliente HTTP: arma una petición real, la envía por la red, y solo puede ver dos cosas, lo que salió (verbo, URL, headers, body) y lo que volvió (status, headers, body). No lee tu código fuente ni sabe en qué framework o lenguaje está escrito tu backend: prueba el contrato HTTP desde afuera, exactamente como lo haría tu front en Angular o cualquier otro cliente real.

Esto es lo que se llama una prueba de caja negra: verifica que la caja responda como se espera, sin abrirla para revisar por dentro. Ya conoces el otro extremo: las pruebas con JUnit prueban un método Java (la unidad es el método) y se escriben en Java.

Consejo

Por eso la misma Collection de Postman sigue sirviendo si mañana reescribes tu backend en otro lenguaje: mientras el contrato HTTP (las URLs, los verbos, el formato de las respuestas) no cambie, las pruebas siguen pasando.

Qué más puede hacer Postman

En este curso vas a usar Collections, Environments y Tests, pero Postman ofrece bastante más. Vale la pena que sepas que existe, para cuando lo necesites en un proyecto real:

• Pre-request scripts: código que corre justo antes de enviar la petición, por ejemplo para calcular una fecha o armar un token.
• Collection Runner: corre todas las peticiones de una Collection en secuencia, incluso repitiendo el ciclo con un archivo de datos (CSV o JSON).
• Newman: el mismo Collection Runner, pero desde la terminal en vez de la aplicación de Postman. Sirve para automatizar la ejecución de las pruebas, por ejemplo como parte de un pipeline de Integración Continua. Ya lo instalaste en el taller de ambiente de desarrollo.
• Mock Servers: simulan las respuestas de una API que todavía no existe, para que el front pueda avanzar en paralelo.
• Monitors: ejecutan una Collection automáticamente según un horario, para detectar si un servicio se cae.
• Documentación y Workspaces: generan documentación navegable de tu API a partir de la Collection, y permiten compartirla con tu equipo.

Principios para diseñar una prueba de API

Antes de escribir un pm.test(), dos preguntas:

1. ¿Qué datos necesita la prueba? Si vas a consultar un artista por su id, ese artista tiene que existir de antemano: o ya está en tus datos de prueba, o lo creas tú mismo con un POST justo antes (lo vas a ver en “Tests encadenados”, más abajo).
2. ¿Qué vas a verificar, y en qué escenarios? Ya usaste esta idea con JUnit: un escenario positivo verifica el caso feliz (el código de estado esperado, la forma del body); un escenario negativo verifica qué pasa cuando algo sale mal o se sale de lo común (un id que no existe, una lista vacía, un dato duplicado). La estrategia mínima para cada endpoint es al menos un escenario positivo y uno negativo.

Consejo

Es la misma estrategia de “Escenarios positivos y negativos” que ya viste en las pruebas de lógica de negocio, aplicada del otro lado del HTTP.

Qué es un test en Postman

Después de recibir una respuesta HTTP, Postman ejecuta JavaScript para verificar formalmente lo esperado. Sin tests hay que revisar visualmente status, body y headers; con tests la verificación es repetible y automática en toda la Collection.

1. Enviar la petición HTTP.
2. Recibir status, headers, body y tiempo de respuesta.
3. Ejecutar el JavaScript de la pestaña de tests.
4. Mostrar PASS o FAIL para cada pm.test() en Test Results.

Anatomía de pm.test() y pm.expect()

pm.test("El artista tiene id y nombre", function () {
  const artista = pm.response.json();
  pm.expect(artista).to.have.property("id");
  pm.expect(artista).to.have.property("nombre");
});

• pm es el objeto global para respuesta, entorno y tests.
• pm.test(nombre, función) define el caso visible en Test Results.
• el nombre expresa qué se verifica.
• la función contiene una o más aserciones.
• pm.expect(valor real) inicia una aserción Chai y la cadena posterior expresa el valor esperado.

Aserciones esenciales

pm.expect(pm.response.code).to.equal(200);
pm.expect(body).to.be.an("array");
pm.expect(body.length).to.be.above(0);
pm.expect(artista).to.have.property("albumes");
pm.expect(artista.nombre).to.be.a("string");
pm.expect(artista.albumes).to.be.empty;
pm.expect(pm.response.responseTime).to.be.below(500);
pm.expect(pm.response.headers.get("Content-Type"))
  .to.include("application/json");

Patrones por operación

Cada patrón siguiente aplica el principio de escenarios positivos y negativos a un verbo HTTP distinto.

GET de una colección

Verifica 200, que el body sea un arreglo no vacío, que cada artista tenga id y nombre, que albumes exista como arreglo para confirmar ArtistaDetailDTO, y que Content-Type incluya application/json.

GET por identificador

Verifica que el body sea un objeto y no un arreglo, que el id coincida con la URL, que nombre sea un string no vacío, activo sea boolean y albumes sea un arreglo. En cada álbum se esperan propiedades como artista y titulo.

POST exitoso

Verifica 201 Created, header Location, identificador numérico positivo asignado por el servidor, nombre igual al enviado y albumes vacío.

const nuevo = pm.response.json();

pm.test("Status code es 201 Created", () =>
  pm.expect(pm.response.code).to.equal(201));
pm.test("Header Location está presente", () =>
  pm.expect(pm.response.headers.get("Location"))
    .to.include("/artistas/"));
pm.test("id fue asignado", () =>
  pm.expect(nuevo.id).to.be.above(0));

PUT, DELETE y errores

• PUT verifica 200, que el identificador no cambie, que el género se actualice y que los álbumes se conserven.
• DELETE acepta en el recurso original 200 con el DTO eliminado; 204 No Content es una alternativa válida sin body.
• un duplicado verifica 409 Conflict y un body con error, message no vacío y status: 409.
• un identificador inexistente verifica 404, body de error sin propiedad nombre y un mensaje que incluya el identificador buscado.

Laboratorio de respuestas

Cambia la respuesta simulada, ejecuta los tests y observa por qué pasan o fallan.

Status HTTPDetailDTOPOST

Código de estado

Respuesta simulada

200 OK404 Not Found500 Error

Status recibido: 200 · 38 ms

Tests que se ejecutarán

pm.expect(pm.response.code).to.equal(200);

▶ Ejecutar tests

Test Results

Selecciona una respuesta y ejecuta.

Tests encadenados

// POST: guardar el id generado
pm.environment.set("artistaId", nuevo.id);

// GET: usarlo en /artistas/{{artistaId}}
pm.expect(pm.response.json().id)
  .to.equal(Number(pm.environment.get("artistaId")));

// DELETE: limpiar la variable
pm.environment.unset("artistaId");

El encadenamiento crea un recurso, consulta el mismo identificador y finalmente lo elimina. Las variables de entorno evitan copiar manualmente el valor entre requests.

Precaución

Los tests no reemplazan la inspección del diseño de la API: expresan formalmente el contrato esperado para cada escenario.

Autoevaluación

1. ¿Cuándo ejecuta Postman los tests de una petición?

Antes de enviar HTTPDespués de recibir la respuestaSolo al exportar la Collection

2. ¿Qué define pm.test()?

Una variable de entornoUn endpointUn caso de prueba con nombre y callback

3. ¿Qué status se espera al crear correctamente un artista?

201200404

4. ¿Cómo se comprueba que el body es un arreglo?

pm.response.code.equal('array')pm.expect(body).to.be.an('array')pm.environment.set('array')

5. ¿Qué permite encadenar POST, GET y DELETE?

Repetir siempre el id 1Modificar el hostGuardar el id en una variable de entorno

6. ¿Qué debe verificar un GET inexistente?

201 y Location404 y un body de error200 y un artista

7. ¿Por qué Postman puede probar un backend sin importar en qué lenguaje esté escrito?

Porque traduce el código del backend automáticamentePorque prueba el contrato HTTP desde afuera, sin leer el código fuentePorque todos los backends exponen JavaScript internamente

8. ¿Para qué sirve Newman?

Para diseñar la interfaz de PostmanPara correr una Collection desde la terminal y automatizar su ejecuciónPara reemplazar los Environments

9. ¿Cuál es la estrategia mínima de pruebas para un endpoint?

Solo probar el caso felizAl menos un escenario positivo y uno negativoProbar todos los códigos de estado HTTP que existen

Comprobar