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.
Ver índice de contenidos
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.
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 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:
GETpara leer,POSTpara crear,PUT/PATCHpara modificar,DELETEpara 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
POSToPUT, 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:
// 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.
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.
# 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:
- Las pruebas viven en el repositorioLa colección y el entorno exportados se guardan junto al código.
- El pipeline instala Newman y corre la colecciónComo un paso del flujo, después de desplegar la API en un entorno de pruebas.
- Si una aserción falla, el pipeline se detieneNewman 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, 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
- Underc0de, foro. Sección QA (Quality Assurance). Consultas sobre pruebas de APIs y automatización de colecciones.
- Underc0de, foro. Sección Desarrollo web. Desarrollo y consumo de APIs, el otro lado de lo que se prueba.
Documentación oficial
- Postman. Learning Center. La documentación oficial de Postman, con colecciones, entornos y peticiones.
- Postman. Newman: integración por línea de comandos. Cómo ejecutar colecciones desde la terminal y en CI.
- Postman. Writing tests. Cómo escribir las aserciones dentro de una colección.
- IETF. RFC 9110, HTTP Semantics. Los métodos y códigos de estado que se comprueban en las pruebas.