# Pruebas de APIs con Postman y Newman

**Categoría:** Testing y QA · **Nivel:** Intermedio · **Lectura:** 11 min
**Publicada:** 2026-07-28 · **Actualizada:** 2026-07-28 · **Autoría:** Underc0de
**Versión HTML (canónica):** https://underc0de.org/guias/testing/pruebas-de-apis-con-postman-y-newman/

## Respuesta rápida

Una **API** no tiene interfaz visual: se prueba enviándole **peticiones HTTP** y comprobando sus **respuestas**. **Postman** es la herramienta para hacerlo cómodo a mano: arma la petición (método, URL, cabeceras, cuerpo), la envía y muestra la respuesta. Pero probar de verdad no es mirar que devuelva `200`: es escribir **aserciones** —comprobaciones automáticas— sobre el código de estado, el cuerpo y el tiempo de respuesta, que se guardan dentro de la **colección**. Con **entornos** y variables, la misma colección corre contra desarrollo, pruebas o producción cambiando un dato. Y **Newman** es el ejecutor de línea de comandos de Postman: corre esa colección en la terminal y, sobre todo, en un **pipeline de integración continua**, de modo que las pruebas de API se ejecuten solas con cada cambio y frenen lo que rompa el contrato.

## Por qué probar una API

Una **API** es la puerta por la que otros programas usan un servicio: la app móvil, la web y los sistemas de terceros hablan con el servidor a través de ella. Si la API falla o cambia sin avisar, todo lo que depende de ella se rompe. Y como no tiene interfaz que una persona mire, sus errores pasan desapercibidos hasta que algo se cae del otro lado.

Probar una API es enviarle peticiones y verificar que responde como debe: el **código de estado** correcto (200 si salió bien, 404 si no existe, 400 si la petición está mal), el **cuerpo** con la estructura y los datos esperados, y en un tiempo razonable. Es de las pruebas que más rinden, porque una API estable sostiene muchas aplicaciones a la vez.

> **Atención**
>
> Hay dos formas complementarias de probar APIs. Esta guía cubre las pruebas **funcionales**: ¿la API hace lo que debe y responde bien? La guía de [contract testing con Pact](../contract-testing-de-apis-con-pact/index.md) cubre otra cosa: ¿el contrato entre dos servicios —lo que uno espera y lo que el otro entrega— se mantiene cuando cualquiera de los dos cambia? Se usan juntas: Postman/Newman verifica el comportamiento, Pact protege la integración.

## Postman a mano

**Postman** arma y envía peticiones sin escribir código. Lo mínimo para una petición:

- **Método:** `GET` para leer, `POST` para crear, `PUT`/`PATCH` para modificar, `DELETE` para borrar.
- **URL:** la dirección del recurso, por ejemplo `https://api.ejemplo.test/pedidos/42`.
- **Cabeceras:** datos de control, como el tipo de contenido o el token de autenticación.
- **Cuerpo:** en un `POST` o `PUT`, los datos que se envían, normalmente en JSON.

Las peticiones se guardan y organizan en una **colección**: un conjunto ordenado de peticiones que representa el flujo de la API (crear un pedido, consultarlo, modificarlo, borrarlo). La colección es la pieza clave, porque es lo que después se automatiza: no se automatiza un clic, se automatiza una colección entera.

## Las aserciones: probar de verdad

El error que separa a quien mira de quien prueba: quedarse con que la API «devolvió 200». Un código 200 solo dice que el servidor respondió algo; no dice que la respuesta sea correcta. Una API puede devolver 200 con el cuerpo vacío, con datos equivocados o con la estructura rota, y todo eso pasaría por bueno.

Probar de verdad es escribir **aserciones** dentro de la colección: comprobaciones automáticas que se ejecutan tras cada petición. Postman las escribe en un pequeño bloque de código junto a la petición:

```javascript
// Aserciones en la pestaña de tests de una petición en Postman.

pm.test("El código de estado es 200", () => {
  pm.response.to.have.status(200);
});

pm.test("La respuesta llega en menos de 500 ms", () => {
  pm.expect(pm.response.responseTime).to.be.below(500);
});

pm.test("El pedido tiene id y estado 'pagado'", () => {
  const cuerpo = pm.response.json();
  pm.expect(cuerpo).to.have.property("id");
  pm.expect(cuerpo.estado).to.eql("pagado");
});
```

Estas aserciones son lo que convierte una colección en una **suite de pruebas**. Cubren lo mismo que cualquier prueba: el resultado esperado (estado y datos) y también aspectos no funcionales (el tiempo de respuesta). Y como viven dentro de la colección, viajan con ella a la terminal y al pipeline.

## Entornos y variables

La misma API vive en varios lugares —tu máquina, un servidor de pruebas, producción— con direcciones y credenciales distintas. Reescribir la colección para cada uno sería un error. Para eso están los **entornos**: conjuntos de variables que la colección usa en vez de valores fijos.

```text
La petición usa una variable:   {{base_url}}/pedidos/42

Entorno "desarrollo":  base_url = http://localhost:3000
Entorno "pruebas":     base_url = https://api-test.ejemplo.test
Entorno "producción":  base_url = https://api.ejemplo.test

Cambiás de entorno y la MISMA colección apunta a otro lado.
```

Las variables también sirven para **encadenar peticiones**: una petición que crea un pedido guarda su identificador en una variable, y la siguiente lo usa para consultarlo. Así la colección representa un flujo real, no peticiones sueltas. Y un aviso importante que aplica también a las APIs propias: los **tokens y credenciales** van en variables de entorno, nunca escritos dentro de la colección que se comparte o se sube al repositorio.

## Newman en la terminal

**Newman** es el ejecutor de línea de comandos de Postman: corre una colección completa —con todas sus aserciones— sin abrir la aplicación. Es lo que permite pasar del clic manual a la ejecución automática.

```bash
# Newman se instala con el gestor de paquetes de Node.js.
npm install -g newman

# Correr una colección exportada desde Postman.
newman run coleccion.json

# Con un entorno concreto y un reporte legible.
newman run coleccion.json -e pruebas.json -r cli,html

# Newman devuelve código de salida distinto de cero si algo falla:
# eso es lo que permite que un pipeline se detenga ante una prueba rota.
```

La colección y el entorno se **exportan desde Postman** como archivos JSON, y esos archivos son los que Newman ejecuta. Ese detalle importa: las pruebas viven en archivos versionables, que se guardan junto al código y evolucionan con él.

## Newman en integración continua

Acá está el valor real. Correr Newman una vez en tu terminal está bien; correrlo **automáticamente con cada cambio** es lo que protege la API. Se agrega al pipeline de integración continua como un paso más:

1. **Las pruebas viven en el repositorio** La colección y el entorno exportados se guardan junto al código.
2. **El pipeline instala Newman y corre la colección** Como un paso del flujo, después de desplegar la API en un entorno de pruebas.
3. **Si una aserción falla, el pipeline se detiene** Newman devuelve error, y el cambio no avanza hasta que se arregle. La API rota no llega a producción.

Cómo se arma ese pipeline paso a paso está en [ejecutar pruebas automáticas con GitHub Actions](../pruebas-automaticas-con-github-actions/index.md), donde correr Newman es uno de los ejemplos. La idea general —escribir la prueba una vez y ejecutarla en todos lados— es la misma que ordena todo el testing automatizado.

## Errores frecuentes

- **Quedarse en «devolvió 200».** El código no garantiza que el cuerpo sea correcto: hay que asertar la estructura y los datos.
- **No escribir aserciones.** Una colección sin comprobaciones no es una prueba, es una demostración.
- **Hardcodear la URL y el token.** Van en variables de entorno, para correr en varios entornos y no filtrar credenciales.
- **Subir credenciales al repositorio.** Los tokens nunca se escriben dentro de la colección compartida.
- **Correr Newman solo a mano.** Su valor está en el pipeline, ejecutándose con cada cambio.
- **No encadenar peticiones.** Una colección de peticiones sueltas no representa el flujo real de la API.
- **Confundir pruebas funcionales con contract testing.** Son complementarias, no lo mismo.

## Preguntas frecuentes

**¿Qué diferencia hay entre Postman y Newman?**
Son dos caras de la misma herramienta. Postman es la aplicación con interfaz gráfica donde armás las peticiones a mano, las organizás en colecciones, escribís las aserciones y explorás la API cómodamente durante el desarrollo. Newman es el ejecutor de línea de comandos que corre esas mismas colecciones sin abrir la aplicación, desde la terminal o, sobre todo, dentro de un pipeline de integración continua. La relación es directa: exportás la colección y el entorno desde Postman como archivos, y Newman los ejecuta. Así, el trabajo manual de diseñar y probar la API en Postman se convierte en pruebas automáticas que corren con cada cambio gracias a Newman, sin tener que reescribir nada.

**¿Por qué no alcanza con que la API devuelva 200?**
Porque el código 200 solo indica que el servidor respondió correctamente a nivel de protocolo, no que la respuesta sea la que corresponde. Una API puede devolver 200 con el cuerpo completamente vacío, con datos equivocados, con campos faltantes o con una estructura distinta de la esperada, y si solo mirás el código de estado, todos esos errores pasarían por buenos. Probar de verdad significa escribir aserciones que comprueben también el contenido: que el cuerpo tenga la estructura correcta, que los campos importantes estén presentes y con el tipo adecuado, que un valor concreto coincida con lo esperado y, si importa, que el tiempo de respuesta esté por debajo de un umbral. El código de estado es la primera comprobación, no la única.

**¿Para qué sirven los entornos en Postman?**
Sirven para que la misma colección de pruebas funcione contra distintos lugares donde vive la API —tu máquina, un servidor de pruebas, producción— sin tener que reescribirla. En lugar de poner la dirección y las credenciales fijas en cada petición, se usan variables, y cada entorno define los valores de esas variables. Cambiando de entorno, la misma colección apunta automáticamente a otro servidor. Los entornos también permiten encadenar peticiones, guardando en una variable un dato que devuelve una petición para que la siguiente lo use, de modo que la colección represente un flujo real. Y son la forma correcta de manejar los tokens y credenciales, que deben ir en variables de entorno y nunca escritos dentro de la colección que se comparte.

**¿Puedo usar Postman y Newman gratis?**
Sí. Postman tiene un plan gratuito suficiente para armar colecciones, escribir aserciones y usar entornos, que es todo lo que hace falta para las pruebas que cubre esta guía. Newman es una herramienta de línea de comandos de código abierto que se instala con el gestor de paquetes de Node.js y se usa sin costo, incluso dentro de pipelines de integración continua. Hay planes de pago de Postman orientados a equipos grandes con necesidades de colaboración, gobernanza y monitoreo, pero para aprender a probar APIs y para automatizar colecciones en un proyecto no son necesarios. La combinación gratuita de Postman para diseñar y Newman para ejecutar cubre por completo el flujo de trabajo de esta guía.

**¿En qué se diferencia esto del contract testing con Pact?**
Resuelven problemas distintos y se complementan. Las pruebas con Postman y Newman son funcionales: comprueban que la API hace lo que debe y responde correctamente, enviándole peticiones y verificando sus respuestas. El contract testing con Pact, en cambio, se ocupa de la integración entre dos servicios: verifica que el contrato entre quien consume la API y quien la provee —lo que uno espera recibir y lo que el otro se compromete a entregar— se mantiene cuando cualquiera de los dos cambia, para que una modificación en un servicio no rompa silenciosamente al otro. Un proyecto serio suele usar ambos: Postman y Newman para el comportamiento funcional, y Pact para proteger las integraciones entre servicios.

**¿Cómo se integran estas pruebas en un pipeline?**
Guardando la colección y el entorno exportados desde Postman dentro del repositorio, junto al código, y agregando un paso al pipeline que instale Newman y ejecute la colección, normalmente después de haber desplegado la API en un entorno de pruebas. La clave está en que Newman devuelve un código de salida distinto de cero cuando alguna aserción falla, y los sistemas de integración continua interpretan ese código como un fallo que detiene el flujo. Así, si un cambio rompe el comportamiento de la API, las pruebas fallan, el pipeline se detiene y el cambio no llega a producción hasta que se corrija. El detalle de cómo construir ese pipeline paso a paso está en la guía de ejecutar pruebas automáticas con GitHub Actions.

## Fuentes

Documentación oficial y material de la comunidad consultados para esta guía. Fecha de consulta: 28 de julio de 2026.

### Aportes de la comunidad Underc0de

1. **Underc0de, foro.** [Sección QA (Quality Assurance)](https://underc0de.org/foro/qa-testing/). Consultas sobre pruebas de APIs y automatización de colecciones.
2. **Underc0de, foro.** [Sección Desarrollo web](https://underc0de.org/foro/desarrollo-web/). Desarrollo y consumo de APIs, el otro lado de lo que se prueba.

### Documentación oficial

1. **Postman.** [Learning Center](https://learning.postman.com/docs/introduction/overview/). La documentación oficial de Postman, con colecciones, entornos y peticiones.
2. **Postman.** [Newman: integración por línea de comandos](https://learning.postman.com/docs/collections/using-newman-cli/command-line-integration-with-newman/). Cómo ejecutar colecciones desde la terminal y en CI.
3. **Postman.** [Writing tests](https://learning.postman.com/docs/tests-and-scripts/write-scripts/test-scripts/). Cómo escribir las aserciones dentro de una colección.
4. **IETF.** [RFC 9110, HTTP Semantics](https://www.rfc-editor.org/rfc/rfc9110). Los métodos y códigos de estado que se comprueban en las pruebas.

## Guías relacionadas

- [Contract Testing con Pact](../contract-testing-de-apis-con-pact/index.md)
- [Pruebas en GitHub Actions](../pruebas-automaticas-con-github-actions/index.md)
- [Testing de software: empezar en QA](../introduccion-al-testing/index.md)
- [Pruebas de rendimiento con k6](../pruebas-de-rendimiento-con-k6-y-grafana/index.md)
- [Índice de Testing y QA](../index.md)