Postman Tutorial: API Testing Complete Guide for Beginners

TL;DR

• Postman is the most popular API testing tool with 30M+ developers
• Organize requests in Collections with folders for related endpoints
• Use Environments to switch between dev/staging/production without changing requests
• Write tests in JavaScript using pm.test() — runs after every request
• Newman CLI runs collections in CI/CD pipelines

Best for: QA engineers learning API testing, developers testing their APIs Skip if: You prefer code-only tools (REST Assured, requests) or need complex scripting Read time: 12 minutes

You’re testing an API manually. Copy the token from login response, paste into the next request, change the URL for staging, repeat for production. This gets old fast.

Postman solves this. Collections organize your requests. Environments store variables. Test scripts validate responses automatically. Newman runs everything in CI/CD.

Getting Started

Installation

Download from postman.com/downloads. Available for Windows, macOS, Linux, and as a web app.

Your First Request

1. Click New → HTTP Request
2. Enter URL: https://jsonplaceholder.typicode.com/posts/1
3. Click Send
4. See response with status, time, and body

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

HTTP Methods

Collections: Organizing Requests

Collections group related requests. Think of them as folders for your API tests.

Creating a Collection

1. Click Collections in sidebar
2. Click + to create new collection
3. Name it “User API Tests”
4. Right-click → Add Request

Collection Structure

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

Sharing Collections

• Export: Right-click collection → Export → Save as JSON
• Import: File → Import → Select JSON file
• Team workspace: Share with team (requires Postman account)

Environments: Managing Variables

Environments store variables that change between contexts (dev, staging, production).

Creating Environment

1. Click Environments in sidebar
2. Click + to create new
3. Name it “Development”
4. Add variables:

Using Variables

Reference variables with double curly braces:

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

Variable Scopes

Setting Variables in Scripts

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

// Tests tab (runs after response)
const response = pm.response.json();
pm.environment.set("user_id", response.id);
pm.collectionVariables.set("last_created_user", response.id);

Writing Tests

Tests run after each request. Use JavaScript with Postman’s pm API.

Basic Assertions

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

// Response time
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");
});

Common Test Patterns

// Check array length
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);
});

// Check object structure
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');
});

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

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

JSON Schema Validation

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);
});

Authentication

Bearer Token

Authorization: Bearer {{access_token}}

Or in Authorization tab:

1. Select Bearer Token
2. Enter {{access_token}}

Automatic Token Refresh

// In Login request Tests tab
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);

    // Set expiry time
    const expiresIn = response.expires_in * 1000;
    pm.environment.set("token_expiry", Date.now() + expiresIn);
});

// In Pre-request Script of authenticated requests
const tokenExpiry = pm.environment.get("token_expiry");

if (Date.now() > tokenExpiry - 60000) { // Refresh 1 min before expiry
    // Token needs refresh - will be handled by collection runner
    console.log("Token expired, refresh needed");
}

API Key Authentication

// Query parameter
GET {{base_url}}/data?api_key={{api_key}}

// Header
X-API-Key: {{api_key}}

Data-Driven Testing

Run same request with different data using CSV or JSON files.

CSV File (users.csv)

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

Using Data in Request

// Request body
{
    "email": "{{email}}",
    "name": "{{name}}",
    "age": {{age}}
}

Running with Data

1. Click Run on collection
2. Select Data → Choose CSV file
3. Set iterations (or leave blank for all rows)
4. Click Run

Tests with Data Variables

pm.test("User created with correct email", function() {
    const response = pm.response.json();
    pm.expect(response.email).to.eql(pm.iterationData.get("email"));
});

Collection Runner

Run multiple requests sequentially with test validation.

Basic Run

1. Click Run on collection
2. Select requests to include
3. Set iterations
4. Choose environment
5. Click Run

Workflow Control

// Skip to specific request
postman.setNextRequest("Create User");

// Stop execution
postman.setNextRequest(null);

// Conditional flow
if (pm.response.code === 401) {
    postman.setNextRequest("Refresh Token");
} else {
    postman.setNextRequest("Get User Details");
}

Newman: CLI Runner

Newman runs Postman collections from command line — essential for CI/CD.

Installation

npm install -g newman

Basic Usage

# Run collection
newman run collection.json

# With environment
newman run collection.json -e environment.json

# With iterations
newman run collection.json -n 5

# With data file
newman run collection.json -d users.csv

CI/CD Integration

# .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/

Newman Reporters

# Install reporters
npm install -g newman-reporter-htmlextra newman-reporter-junitfull

# HTML report
newman run collection.json -r htmlextra --reporter-htmlextra-export report.html

# JUnit for CI systems
newman run collection.json -r junitfull --reporter-junitfull-export results.xml

# Multiple reporters
newman run collection.json -r cli,htmlextra,junitfull

Mock Servers

Create mock APIs when backend isn’t ready.

Creating Mock

1. Right-click collection → Mock Collection
2. Name your mock
3. Postman generates mock URL

Adding Examples

For each request, add examples that define mock responses:

1. Send request
2. Click Save Response → Save as example
3. Edit example name (e.g., “Success”, “Not Found”)
4. Mock returns example based on request match

Dynamic Mocks

// Example response with dynamic data
{
    "id": "{{$randomUUID}}",
    "email": "{{$randomEmail}}",
    "created_at": "{{$isoTimestamp}}"
}

Pre-request Scripts

Scripts that run before the request.

Common Use Cases

// Generate timestamp
pm.environment.set("timestamp", new Date().toISOString());

// Generate random data
pm.environment.set("random_id", Math.floor(Math.random() * 1000));

// Calculate signature
const crypto = require('crypto-js');
const signature = crypto.HmacSHA256(pm.request.body.raw, pm.environment.get("secret_key"));
pm.environment.set("signature", signature.toString());

// Set dynamic headers
pm.request.headers.add({
    key: "X-Request-ID",
    value: pm.variables.replaceIn("{{$guid}}")
});

AI-Assisted Postman Development

AI tools can accelerate your Postman workflow.

What AI does well:

• Generating test scripts from API documentation
• Creating JSON schemas from response examples
• Writing data transformation scripts
• Explaining API error responses
• Converting cURL commands to Postman requests

What still needs humans:

• Designing test strategy and coverage
• Deciding which edge cases to test
• Understanding business logic validation
• Debugging intermittent failures

Useful prompt:

I have this API response:
{
  "user": {
    "id": 123,
    "email": "test@example.com",
    "profile": {
      "name": "John",
      "age": 30
    }
  },
  "token": "eyJ..."
}

Write Postman tests that:
1. Validate status 200
2. Check user has id, email, and profile
3. Verify profile has name and age
4. Save token to environment variable
5. Validate response time under 500ms

FAQ

Is Postman free for API testing?

Yes. Postman’s free tier includes unlimited requests, collections, environments, and test scripts. You can run collections manually and use Newman for CI/CD. Paid plans add team workspaces, monitoring, mock server calls beyond limits, and advanced features like API versioning.

How do I write tests in Postman?

Use the Tests tab in any request. Write JavaScript using Postman’s pm API:

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;
});

Tests run automatically after each request and show pass/fail in results.

What is Newman in Postman?

Newman is Postman’s command-line collection runner. Install with npm install -g newman, then run newman run collection.json. Essential for CI/CD integration — runs in headless environments, generates reports, and returns exit codes for pipeline status.

Can Postman test GraphQL APIs?

Yes. Postman has dedicated GraphQL support:

• Query editor with syntax highlighting
• Schema introspection for autocomplete
• Variable support for dynamic queries
• Same test scripting as REST

Select GraphQL as body type and write your query.

When to Choose Postman

Choose Postman when:

• Team needs visual API testing tool
• Want quick test creation without coding
• Need collection sharing and collaboration
• Building API documentation alongside tests
• Prefer GUI over code-only tools

Consider alternatives when:

• Need complex programmatic test logic (REST Assured)
• Want tests in same repo as code (pytest + requests)
• Team prefers TypeScript (Playwright API testing)
• Need performance testing (k6, JMeter)

Official Resources

• Postman Learning Center
• Postman API Documentation
• Newman Documentation

See Also

• API Testing Mastery - Complete guide to API testing strategies
• Postman Automation Guide - Advanced automation with Newman and CI/CD
• REST Assured Tutorial - Code-first API testing with Java
• Postman Alternatives - Bruno, Insomnia, and other options