Colecciones de Postman como base de suites de pruebas

Por qué una colección es la unidad base de una suite de pruebas

En Postman, una colección puede ser mucho más que una lista de requests: es el contenedor que permite agrupar, documentar, parametrizar y automatizar pruebas de forma consistente. Cuando una colección está bien diseñada, se convierte en una suite de pruebas porque: (1) refleja módulos funcionales reales de la API, (2) define un orden lógico de ejecución, (3) centraliza precondiciones y postcondiciones, y (4) facilita el mantenimiento y la colaboración entre QA, Dev y Automation.

La idea clave es que la estructura de la colección debe representar cómo se usa la API (por recursos/funcionalidades) y no cómo “se fue creando” (por urgencias o por quién la tocó).

Diseño mantenible: jerarquía recomendada

Niveles: colección → carpetas → requests

• Colección: representa un dominio o módulo grande (por ejemplo, “Billing API”, “Identity API” o “Backoffice”).
• Carpetas: agrupan por recurso (Customers, Orders) o por feature (Checkout, Refunds). Evita mezclar ambos criterios dentro de la misma colección; elige uno y sé consistente.
• Requests: representan una operación concreta (Create, GetById, Search, Update, Delete) o una acción de negocio (Approve, Cancel, Assign).

Dos patrones de organización (elige uno)

Ejemplo de estructura (por recurso)

Colección: Commerce API - QA Suite  Colección variables: baseUrl, apiVersion, tenantId  Carpeta: Customers    GET - List customers    POST - Create customer    GET - Get customer by id    PATCH - Update customer    DELETE - Delete customer  Carpeta: Orders    POST - Create order    GET - Get order by id    POST - Cancel order

Convenciones para equipos de QA: nombres, tags y descripciones

Convenciones de nombres (consistencia > creatividad)

Una convención simple reduce fricción al buscar, revisar y automatizar. Recomendación:

• Requests: METHOD - Acción (detalle) o METHOD - Recurso - Operación.
• Carpetas: nombre del recurso/feature en plural, sin prefijos innecesarios.
• Evita: “test1”, “nuevo”, “final”, “copia”, “prueba ok”, “endpoint Juan”.

Ejemplos:

• POST - Orders - Create
• GET - Orders - Get by id
• POST - Orders - Cancel (valid state)

Tags sin plugins: cómo simularlos

Postman no ofrece tags nativos universales para filtrar como en un test runner tradicional, pero puedes estandarizar “tags” en el nombre o en la descripción:

Continúa en nuestra aplicación.

• Escuche el audio con la pantalla apagada.
• Obtenga un certificado al finalizar.
• ¡Más de 5000 cursos para que explores!

O continúa leyendo más abajo...

Descargar la aplicación

• En el nombre: [smoke], [regression], [negative], [contract], [perf-lite].
• En la descripción: una línea “Tags:” para lectura humana y para parseo si exportas JSON.

Ejemplo de nombre:

GET - Orders - Get by id [smoke][contract]

Descripciones útiles (plantilla)

Usa descripciones cortas pero accionables. Plantilla recomendada para requests:

• Objetivo: qué valida este request.
• Precondiciones: qué debe existir antes (datos, estado).
• Postcondiciones: qué deja creado/modificado.
• Variables: qué variables usa/produce (por ejemplo, orderId).
• Casos cubiertos: happy path / negativos relevantes.

Ejemplo:

Objetivo: crear una orden válida y capturar orderId. Precondiciones: customerId existente. Postcondiciones: orden creada en estado NEW. Variables: set orderId en collection variables. Casos: 201 OK (happy), 400 por items vacíos (negative).

Examples (Ejemplos) como documentación viva: variaciones y casos negativos

Qué problema resuelven los Examples

Los Examples permiten guardar variantes de una misma request (inputs) y sus respuestas esperadas/observadas (outputs). Esto es especialmente útil para QA porque convierte una request en un “contenedor de casos” sin duplicar endpoints.

Cómo modelar variaciones con Examples

• Happy path: payload válido, respuesta 200/201, asserts principales.
• Variación de negocio: mismo endpoint, diferente combinación de campos (por ejemplo, cupón aplicado, envío express).
• Negativos: payload inválido, faltan campos, formato incorrecto, estado no permitido.

Recomendación práctica: crea al menos estos Examples por operación crítica:

• OK - minimal
• OK - full
• KO - missing required field
• KO - invalid format

Ejemplo: request con múltiples Examples

Supón un endpoint POST /orders. En la misma request, crea Examples:

• Example: OK - minimal (body mínimo válido)
• Example: OK - with discount (incluye cupón)
• Example: KO - empty items (items vacío, esperas 400)

En cada Example, guarda el body y, si aplica, la respuesta. Esto ayuda a que cualquier QA entienda rápidamente qué combinaciones se prueban.

Asserts específicos por Example (patrón recomendado)

Para no duplicar lógica, coloca asserts comunes en el script del request y usa una variable para diferenciar el caso. Por ejemplo, define una variable caseName en el pre-script del request o en la propia request (según tu estándar) y ramifica:

// Tests (a nivel de request) const caseName = pm.variables.get('caseName'); if (caseName === 'OK_MINIMAL') {   pm.test('Status 201', () => pm.response.to.have.status(201));   pm.test('Tiene id', () => pm.expect(pm.response.json()).to.have.property('id')); } if (caseName === 'KO_EMPTY_ITEMS') {   pm.test('Status 400', () => pm.response.to.have.status(400));   pm.test('Error code esperado', () => {     const body = pm.response.json();     pm.expect(body).to.have.property('code');     pm.expect(body.code).to.eql('VALIDATION_ERROR');   }); }

Así, el mismo request soporta múltiples escenarios sin crear “copias” del endpoint.

Precondiciones y postcondiciones con scripts: colección, carpeta y request

Principio: lo común arriba, lo específico abajo

Para mantener una suite limpia:

• Scripts a nivel de colección: inicialización global (por ejemplo, timestamps, correlación, helpers, defaults).
• Scripts a nivel de carpeta: precondiciones del módulo (por ejemplo, preparar datos base para Orders).
• Scripts a nivel de request: validaciones y capturas específicas (por ejemplo, guardar orderId tras crear).

Precondiciones típicas (qué automatizar)

• Generación de datos dinámicos: emails únicos, referencias, fechas.
• Selección de fixtures: elegir un customerId “estable” o crear uno si no existe.
• Encadenamiento: si un request depende de otro, captura IDs y pásalos por variables.

Postcondiciones típicas (qué limpiar o registrar)

• Guardar IDs creados para requests posteriores.
• Registrar trazas mínimas para debugging (por ejemplo, requestId/correlationId).
• Limpieza (cuando aplique): borrar entidades creadas o marcar para teardown.

Ejemplo: script a nivel de carpeta (Orders)

Objetivo: asegurar que existe un customerId para las pruebas de Orders. Si tu suite ya tiene un flujo de creación, puedes centralizar aquí la selección del ID.

// Pre-request Script (carpeta Orders) if (!pm.collectionVariables.get('customerId')) {   // En un enfoque simple, fallar explícitamente para forzar orden de ejecución   throw new Error('Falta customerId. Ejecuta primero Customers/POST - Create customer'); } // Generar un idempotency key por request (si tu API lo usa) pm.variables.set('idempotencyKey', 'idem-' + Date.now());

Ejemplo: script a nivel de request (Create order)

// Tests (request POST - Orders - Create) pm.test('Status 201', () => pm.response.to.have.status(201)); const json = pm.response.json(); pm.test('Respuesta contiene id', () => pm.expect(json).to.have.property('id')); pm.collectionVariables.set('orderId', json.id);

Checklist de mantenimiento para scripts

• No uses variables “mágicas”: documenta en la descripción qué variables se leen/escriben.
• Evita lógica compleja repetida: si se repite en 3+ requests, súbela a carpeta o colección.
• Si una precondición es obligatoria, falla temprano con un mensaje claro.

Guía práctica: refactorizar una colección desordenada en una suite coherente

Objetivo del refactor

Transformar una colección con requests duplicadas, nombres inconsistentes y scripts dispersos en una suite con estructura modular, convenciones claras, Examples útiles y scripts en el nivel correcto.

Paso 1: inventario y clasificación rápida

• Exporta o revisa la colección y lista requests por endpoint (METHOD + path).
• Marca duplicados (mismo endpoint con pequeñas variaciones).
• Identifica “flujos” (por ejemplo: crear → consultar → actualizar → cancelar).

Paso 2: define el criterio de carpetas (recurso o feature)

• Si 70%+ es CRUD por entidad, elige por recurso.
• Si predominan journeys (checkout, onboarding), elige por feature.
• Escribe una regla en la descripción de la colección: “Esta colección se organiza por X”.

Paso 3: crea la nueva jerarquía sin tocar aún los requests

• Crea carpetas destino (Customers, Orders, etc.).
• Dentro de cada carpeta, crea subcarpetas opcionales si el módulo es grande: CRUD, Validations, Flows.
• Define variables de colección necesarias para el módulo (por ejemplo, baseUrl, customerId, orderId), y documenta su propósito en la descripción de la colección.

Paso 4: normaliza nombres con una convención única

• Renombra requests al formato elegido (METHOD - Recurso - Operación).
• Agrega tags en el nombre si tu equipo los usa: [smoke], [negative].
• Elimina sufijos como “(copy)”, “(new)”, “final2”. Si necesitas conservar historial, usa control de versiones fuera de la colección, no en el nombre.

Paso 5: elimina duplicados convirtiéndolos en Examples

• Para cada grupo duplicado del mismo endpoint, conserva una request “canónica”.
• Convierte las variaciones en Examples (OK/KO).
• En la descripción del request, lista los Examples disponibles y qué cubren.

Paso 6: reubica scripts al nivel correcto

• Busca scripts repetidos (mismas validaciones o mismas capturas de variables).
• Mueve inicializaciones comunes a colección.
• Mueve precondiciones del módulo a carpeta.
• Deja en request solo lo específico: asserts del endpoint y captura de IDs propios.

Paso 7: estandariza pre/postcondiciones con un “contrato interno” de variables

Define un mini-contrato de variables para que los flujos sean predecibles. Ejemplo:

• customerId: se setea en Customers/Create y se consume en Orders/*
• orderId: se setea en Orders/Create y se consume en Orders/Get/Cancel
• caseName: se setea por Example para ramificar asserts

Documenta este contrato en la descripción de la colección y, si aplica, en cada carpeta.

Paso 8: crea una carpeta “Smoke” como entrada rápida (sin duplicar lógica)

Para facilitar ejecuciones rápidas, crea una carpeta Smoke que referencie el camino mínimo de requests (crear → consultar). Si tu equipo evita duplicar requests, una alternativa es usar tags en el nombre y filtrar al ejecutar; si no, mantén la carpeta Smoke pequeña y sincronizada.

Paso 9: valida coherencia con una revisión de checklist

• ¿Cada carpeta representa un recurso/feature claro?
• ¿Los nombres siguen la convención?
• ¿Los duplicados se convirtieron en Examples?
• ¿Las variables producidas/consumidas están documentadas?
• ¿Los scripts están en el nivel correcto (colección/carpeta/request)?

Paso 10: congela el estándar (para que no vuelva el caos)

Agrega en la descripción de la colección una sección “Reglas del equipo” con 5–8 bullets: convención de nombres, criterio de carpetas, política de Examples, y dónde va cada tipo de script. Esto reduce la entropía cuando el equipo crece o rota.