Pruebas de API: Postman/Newman

1) Por qué Postman/Newman

• regresiones repetibles y smokes rápidos;
• parametrización de entornos/secretos;
• métricas de calidad e informes legibles por máquina.

2) Modelo básico

Colección: árbol de consultas y carpetas con scripts compartidos.
Entorno: el conjunto '{{vars}}' para dev/stage/prod (URL, claves).
Pre-request script - preparación: firmas, tokens, corelación de datos.
Pruebas - Aprobación y conservación de variables/artefactos.
Datos-archivos - CSV/JSON para la ejecución de datos-controlados.
Mock/Monitor - bandadas y revisiones periódicas.

<API v1>
├─ _bootstrap (auth, health, seeds)
├─ Public
├─ Authenticated
│  ├─ Accounts
│  ├─ Payments
│  └─ Reports
└─ _teardown (cleanup)

3) Variables y secretos

Nombre las variables como prefijo explícito: 'baseUrl',' tenant ',' clientId '.
Los secretos (contraseñas, client_secret, claves HMAC) se mantienen en las variables del entorno CI, no combine en el repositorio.
Use scop: local → collection → environment → globals (lo mínimo posible).

json
{
"name": "stage-eu",
"values": [
{"key":"baseUrl","value":"https://api. stage. example. com","type":"text","enabled":true},
{"key":"tenant","value":"eu-1","type":"text","enabled":true}
]
}

4) Autenticación: plantillas

4. 1 OAuth2/OIDC (Client Credentials)

js if (!pm.environment. get("access_token")          Date. now() > pm. environment. get("token_exp")) {
pm. sendRequest({
url: pm. environment. get("authUrl"),
method: 'POST',
header: {'Content-Type':'application/x-www-form-urlencoded'},
body: { mode:'urlencoded', urlencoded:[
{key:'grant_type',value:'client_credentials'},
{key:'client_id',value:pm. environment. get('clientId')},
{key:'client_secret',value:pm. environment. get('clientSecret')},
{key:'scope',value:'payments:read payments:write'}
]}
}, (err, res) => {
pm. environment. set("access_token", res. json(). access_token);
pm. environment. set("token_exp", Date. now()+ (res. json(). expires_in-30)1000);
});
}

En la consulta: 'Authorization: Bearer {{access _ token}}'.

4. 2 HMAC (webhooks/socios)

js const body = pm. request. body? pm. request. body. raw          '': '';
const ts = Math. floor(Date. now()/1000);
const msg = `${ts}.${body}`;
const sig = CryptoJS. HmacSHA256(msg, pm. environment. get('hmacSecret')). toString();
pm. variables. set('ts', ts);
pm. variables. set('sig', sig);

Encabezados: 'X-Timestamp: {{ts}}', 'X-Signature: {sig}'.

5) Pruebas: aprobación y corulación

Use 'pm. expect(...)` и `pm. test("...", fn)`.
Guarde los identificadores para los pasos siguientes a través de 'pm. collectionVariables. set`.

js pm. test("HTTP 200", () => pm. response. to. have. status(200));
pm. test ("Scheme is valid," () => {
const schema = pm. collectionVariables. get("schema_wallet");
pm. expect(tv4. validate(pm. response. json(), JSON. parse(schema))). to. be. true;
});
pm. test ("Contains id," () => {
const id = pm. response. json(). id;
pm. expect(id). to. be. a('string');
pm. collectionVariables. set("wallet_id", id);
});

6) Validación del esquema (OpenAPI/JSON Schema)

Almacene JSON Schema en variables de colección o en un archivo individual.
Para OpenAPI: utilice los liebs terminados en pre-request/test (ajv, tv4) - a través de 'pm. natRequest 'en un archivo raw o JSON en línea.

js pm. collectionVariables. set("schema_wallet", JSON. stringify({
"type":"object",
"required":["id","currency","balance"],
"properties":{
"id":{"type":"string"},
"currency":{"type":"string","pattern":"^[A-Z]{3}$"},
"balance":{"type":"number","minimum":0}
}
}));

7) scripts Data-driven

email, password, currency u1@example. com, P@ss1, EUR u2@example. com, P@ss2, USD

La consulta utiliza '{{email}}', '{currency}}'.

newman run collection. json -e stage-eu. json -d users. csv

JSON (array de objetos): conveniente para casos/estructuras complejas.

8) Casos negativos y sostenibilidad

• 401/403 (sin ficha/scope/rol incorrecto).
• 400/422 (validación del esquema, campos obligatorios, límites).
• 404 (BOLA/recurso ajeno).
• 409 (conflictos, llaves idempotentes).
• 429 (límites): compruebe 'Retry-After'.
• 5xx - Degradación correcta y retracción del cliente.

js pm. test ("There is Retry-After at 429," () => {
if (pm. response. code === 429) pm. expect(pm. response. headers. has('Retry-After')). to. be. true;
});

9) Idempotencia, retraídas, paginación

Pasa 'Idempotency-Key' y asegúrate de que la repetición dé el mismo 'id/status'.
Prueba la paginación: 'limit/offset '/' cursor', el detalle de duplicados y pases.
Simulación de retraídas en script de prueba: llamadas consecutivas con la misma clave.

js pm. test ("Idempotent repetition," () => {
pm. sendRequest(pm. request, (err, res2) => {
pm. expect(res2. code). to. eql(pm. response. code);
pm. expect(res2. json(). id). to. eql(pm. response. json(). id);
});
});

10) Newman в CI/CD

10. 1 Inicio

newman run collection. json \
-e stage-eu. json \
-d data. csv \
--timeout-request 30000 \
--reporters cli,htmlextra,junit \
--reporter-htmlextra-export./reports/report. html \
--reporter-junit-export./reports/junit. xml

10. 2 Acciones de GitHub (fragmento)

yaml
- uses: actions/setup-node@v4 with: { node-version: '20' }
- run: npm i -g newman newman-reporter-htmlextra
- run: newman run collection. json -e stage-eu. json --reporters cli,junit --reporter-junit-export reports/junit. xml
- uses: actions/upload-artifact@v4 with: { name: newman-reports, path: reports }

10. 3 Jenkins/GitLab CI

Para la visualización autóctona, exporte AMBnit ('--reporter-junit-nat').
En la paipline, separe los frijoles: smoke (rápido), regression (completo), security (negativo/bordes).

10. 4 Docker

docker run --rm -v $PWD:/etc/newman postman/newman \
run collection. json -e stage-eu. json

11) Moki y monitoreo

Mock servers Postman - bandadas rápidas para el frente y los contratos.
Los monitores son una corrida periódica de higos de la nube (latency, 5xx, SSL).
En el repositorio, mantenga los archivos de respuesta de ejemplo para mokas deterministas.

12) Datos de prueba y limpieza

Crear/eliminar entidades (_bootstrap/_teardown).
Marque los objetos de prueba con el prefijo 'e2e _' y TTL.

js pm. collectionVariables. set("uniq", Date. now()+"_"+Math. floor(Math. random()1e6));

13) Rendimiento «de rodilla»

• mida 'pm. response. responseTime`;
• correr 5-10 iteraciones y fijar p95/umbrales;
• Las correas de performance pesadas están en JMeter/k6/Gatling (más allá de este artículo).

14) Localización y multiarrendamiento

Las variables 'tenant', 'region', 'lang'; cambie en los alrededores.
Las pruebas deben verificar que los datos no «fluyen» entre los tenantes (BOLA-read, prohibiciones cruzadas).
Colecciones/carpetas individuales en las características regionales (límites, monedas).

15) Informes y artefactos

Almacena artefactos de CI: reportes HTML, 'junit. xml ', registros de respuestas fallidas (response bodies).
Conecte Slack/Teams notificaciones de caídas de higos.

16) Calidad y cobertura

• CRUD per-recurso (200/201/204 + negativos).
• Autorización: roles/scoups/multi-tenant.
• Paginación/filtros/clasificación.
• Idempotencia y retraídas.
• Límites: 413/414/431/429.
• Formatos y esquemas (JSON Schema/OpenAPI).
• Integraciones (webhooks con HMAC/mTLS) - anti-replay.

17) Antipatternas

Un «camino feliz» sin pruebas negativas.
Tokens de larga vida en la colección/repositorio.
Mezcla de datos de prueba con datos prod.
Una dependencia oculta del orden de las pruebas sin corelación explícita.
Gigantescos archivos de datos sin samplear.
La falta de informes AMBnit/HTML → la falta de visibilidad en el CI.

18) Lista de comprobación prod

• Las colecciones están divididas por dominios, hay '_ bootstrap/_ teardown'.
• Entorno para dev/stage/prod; secretos de la bóveda de CI.
• Pre-request для auth (OAuth2/HMAC); los tokens se almacenan en caché y se rotan.
• Pruebas: positivo + negativo, circuitos (JSON Schema), paginación, 429/Retry-After.
• Idempotencia: prueba 'Idempotency-Key', doble desafío equivalente.
• Datos-driven CSV/JSON, sufijos aleatorios para la singularidad.
• Newman en el CI: Informes AMBnit/HTML, artefactos como build outputs.
• Moki/monitores para rutas clave; SLA por higuera.
• Documentación sobre variables, etiquetas y orden de inicio.

19) TL; DR

Almacena la lógica de las pruebas en las colecciones Postman, los parámetros están en el entorno, y haz una ejecución en CI a través de Newman con los informes AMBnit/HTML. Cubrir negativos, esquemas, idempotencia, paginación y límites. Correlacione los pasos con variables, use entradas de datos y mokes/monitores. Los secretos son sólo de CI, los informes son artefactos de Bild.