Tutorial de Postman: Guía Completa de Testing de APIs para Principiantes

TL;DR

• Postman es la herramienta de testing de APIs más popular con 30M+ desarrolladores
• Organiza requests en Colecciones con carpetas para endpoints relacionados
• Usa Entornos para cambiar entre dev/staging/production sin modificar requests
• Escribe tests en JavaScript usando pm.test() — se ejecutan después de cada request
• Newman CLI ejecuta colecciones en pipelines CI/CD

Ideal para: QA engineers aprendiendo testing de APIs, desarrolladores testeando sus APIs Omite si: Prefieres herramientas code-only (REST Assured, requests) o necesitas scripting complejo Tiempo de lectura: 12 minutos

Estás testeando una API manualmente. Copias el token del response de login, lo pegas en el siguiente request, cambias la URL para staging, repites para production. Esto cansa rápido.

Postman resuelve esto. Las colecciones organizan tus requests. Los entornos almacenan variables. Los scripts de prueba validan responses automáticamente. Newman ejecuta todo en CI/CD.

Primeros Pasos

Instalación

Descarga desde postman.com/downloads. Disponible para Windows, macOS, Linux y como app web.

Tu Primer Request

1. Click en New → HTTP Request
2. Ingresa URL: https://jsonplaceholder.typicode.com/posts/1
3. Click en Send
4. Ve el response con status, tiempo y body

{
  "userId": 1,
  "id": 1,
  "title": "sunt aut facere repellat provident occaecati excepturi optio reprehenderit",
  "body": "quia et suscipit..."
}

Métodos HTTP

Colecciones: Organizando Requests

Las colecciones agrupan requests relacionados. Piensa en ellas como carpetas para tus tests de API.

Creando una Colección

1. Click en Collections en sidebar
2. Click en + para crear nueva colección
3. Nómbrala “User API Tests”
4. Click derecho → Add Request

Estructura de Colección

User API Tests/
├── Authentication/
│   ├── Login
│   ├── Refresh Token
│   └── Logout
├── Users/
│   ├── Get All Users
│   ├── Get User by ID
│   ├── Create User
│   ├── Update User
│   └── Delete User
└── Posts/
    ├── Get User Posts
    └── Create Post

Entornos: Gestionando Variables

Los entornos almacenan variables que cambian entre contextos (dev, staging, production).

Creando Entorno

1. Click en Environments en sidebar
2. Click en + para crear nuevo
3. Nómbralo “Development”
4. Agrega variables:

Usando Variables

Referencia variables con dobles llaves:

GET {{base_url}}/users
Authorization: Bearer {{access_token}}

Ámbitos de Variables

Estableciendo Variables en Scripts

// Pre-request Script (se ejecuta antes del request)
pm.environment.set("timestamp", Date.now());
pm.environment.set("random_email", `user_${Date.now()}@test.com`);

// Tests tab (se ejecuta después del response)
const response = pm.response.json();
pm.environment.set("user_id", response.id);
pm.collectionVariables.set("last_created_user", response.id);

Escribiendo Tests

Los tests se ejecutan después de cada request. Usa JavaScript con la API pm de Postman.

Assertions Básicos

// Status code
pm.test("Status code is 200", function() {
    pm.response.to.have.status(200);
});

// Tiempo de response
pm.test("Response time is less than 500ms", function() {
    pm.expect(pm.response.responseTime).to.be.below(500);
});

// JSON body
pm.test("Response has correct user ID", function() {
    const response = pm.response.json();
    pm.expect(response.id).to.eql(1);
    pm.expect(response.name).to.be.a('string');
});

// Headers
pm.test("Content-Type is JSON", function() {
    pm.response.to.have.header("Content-Type", "application/json; charset=utf-8");
});

Patrones Comunes de Tests

// Verificar longitud de array
pm.test("Returns 10 users", function() {
    const users = pm.response.json();
    pm.expect(users).to.be.an('array');
    pm.expect(users.length).to.eql(10);
});

// Verificar estructura de objeto
pm.test("User has required fields", function() {
    const user = pm.response.json();
    pm.expect(user).to.have.property('id');
    pm.expect(user).to.have.property('email');
    pm.expect(user).to.have.property('name');
});

// Verificar propiedades anidadas
pm.test("Address has city", function() {
    const user = pm.response.json();
    pm.expect(user.address.city).to.be.a('string');
});

// Validación de response de error
pm.test("Error response has message", function() {
    if (pm.response.code === 400) {
        const error = pm.response.json();
        pm.expect(error).to.have.property('message');
    }
});

Validación de JSON Schema

const schema = {
    "type": "object",
    "required": ["id", "email", "name"],
    "properties": {
        "id": { "type": "integer" },
        "email": { "type": "string", "format": "email" },
        "name": { "type": "string", "minLength": 1 }
    }
};

pm.test("Response matches schema", function() {
    pm.response.to.have.jsonSchema(schema);
});

Autenticación

Bearer Token

Authorization: Bearer {{access_token}}

O en pestaña Authorization:

1. Selecciona Bearer Token
2. Ingresa {{access_token}}

Refresh Automático de Token

// En pestaña Tests del request Login
pm.test("Login successful", function() {
    pm.response.to.have.status(200);

    const response = pm.response.json();
    pm.environment.set("access_token", response.access_token);
    pm.environment.set("refresh_token", response.refresh_token);

    // Establecer tiempo de expiración
    const expiresIn = response.expires_in * 1000;
    pm.environment.set("token_expiry", Date.now() + expiresIn);
});

Testing Data-Driven

Ejecuta el mismo request con diferentes datos usando archivos CSV o JSON.

Archivo CSV (users.csv)

email,name,age
john@test.com,John Doe,30
jane@test.com,Jane Smith,25
bob@test.com,Bob Wilson,35

Usando Datos en Request

// Body del request
{
    "email": "{{email}}",
    "name": "{{name}}",
    "age": {{age}}
}

Ejecutando con Datos

1. Click en Run en la colección
2. Selecciona Data → Elige archivo CSV
3. Establece iteraciones
4. Click en Run

Newman: CLI Runner

Newman ejecuta colecciones Postman desde línea de comandos — esencial para CI/CD.

Instalación

npm install -g newman

Uso Básico

# Ejecutar colección
newman run collection.json

# Con entorno
newman run collection.json -e environment.json

# Con iteraciones
newman run collection.json -n 5

# Con archivo de datos
newman run collection.json -d users.csv

Integración CI/CD

# .github/workflows/api-tests.yml
name: API Tests

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install Newman
        run: npm install -g newman newman-reporter-htmlextra

      - name: Run API Tests
        run: |
          newman run postman/collection.json \
            -e postman/staging.json \
            -r cli,htmlextra \
            --reporter-htmlextra-export reports/api-report.html

      - name: Upload Report
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: api-test-report
          path: reports/

Desarrollo Asistido por IA en Postman

Las herramientas de IA pueden acelerar tu workflow en Postman.

Lo que la IA hace bien:

• Generar scripts de prueba desde documentación de API
• Crear JSON schemas desde ejemplos de responses
• Escribir scripts de transformación de datos
• Explicar errores de API
• Convertir comandos cURL a requests Postman

Lo que aún necesita humanos:

• Diseñar estrategia y cobertura de tests
• Decidir qué edge cases testear
• Entender validación de lógica de negocio
• Depurar fallos intermitentes

Prompt útil:

Tengo este response de API:
{
  "user": {
    "id": 123,
    "email": "test@example.com",
    "profile": {
      "name": "John",
      "age": 30
    }
  },
  "token": "eyJ..."
}

Escribe tests de Postman que:
1. Validen status 200
2. Verifiquen que user tiene id, email y profile
3. Verifiquen que profile tiene name y age
4. Guarden token en variable de entorno
5. Validen tiempo de response menor a 500ms

FAQ

¿Es Postman gratis para testing de APIs?

Sí. El plan gratuito de Postman incluye requests ilimitados, colecciones, entornos y scripts de prueba. Puedes ejecutar colecciones manualmente y usar Newman para CI/CD. Los planes pagos agregan workspaces de equipo, monitoreo, mock servers y funciones avanzadas.

¿Cómo escribo tests en Postman?

Usa la pestaña Tests en cualquier request. Escribe JavaScript usando la API pm de Postman:

pm.test("Status is 200", function() {
    pm.response.to.have.status(200);
});

pm.test("Has user ID", function() {
    const data = pm.response.json();
    pm.expect(data.id).to.exist;
});

Los tests se ejecutan automáticamente después de cada request y muestran pass/fail en resultados.

¿Qué es Newman en Postman?

Newman es el runner de colecciones por línea de comandos de Postman. Instala con npm install -g newman, luego ejecuta newman run collection.json. Esencial para integración CI/CD — funciona en entornos headless, genera reportes y retorna exit codes para status del pipeline.

¿Puede Postman testear APIs GraphQL?

Sí. Postman tiene soporte dedicado para GraphQL:

• Editor de queries con syntax highlighting
• Introspección de schema para autocomplete
• Soporte de variables para queries dinámicos
• Mismas capacidades de scripting que REST

Selecciona GraphQL como tipo de body y escribe tu query.

Cuándo Elegir Postman

Elige Postman cuando:

• El equipo necesita herramienta visual de testing de APIs
• Quieres creación rápida de tests sin codificar
• Necesitas compartir colecciones y colaborar
• Construyes documentación de API junto con tests
• Prefieres GUI sobre herramientas code-only

Considera alternativas cuando:

• Necesitas lógica de test programática compleja (REST Assured)
• Quieres tests en el mismo repo que el código (pytest + requests)
• El equipo prefiere TypeScript (Playwright API testing)
• Necesitas testing de performance (k6, JMeter)

Recursos Oficiales

• Postman Learning Center
• Postman API Documentation
• Newman Documentation

Ver También

• API Testing Mastery - Guía completa de estrategias de testing de APIs
• Postman Automation Guide - Automatización avanzada con Newman y CI/CD
• REST Assured Tutorial - Testing de APIs code-first con Java
• Postman Alternatives - Bruno, Insomnia y otras opciones