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 Postman is the world’s most widely used API platform, trusted by over 30 million developers and QA engineers across organizations of every size. According to the SmartBear State of Testing 2025 report, API testing adoption has grown to 72% of software teams — making API test skills among the most in-demand in the industry. Postman simplifies this by combining request building, environment management, test scripting, and CI/CD automation in a single GUI application. You organize related requests into Collections, store environment-specific variables so the same request works against dev, staging, and production without editing URLs by hand, and write JavaScript assertions that validate status codes, response bodies, and headers automatically after each call. When you need headless execution in a pipeline, Newman — Postman’s CLI companion — runs any exported collection directly from the terminal. The official Postman learning center at learning.postman.com/docs covers the full API in depth. This tutorial walks you through every layer, from your first GET request to data-driven testing and CI/CD integration with Newman reporters.

Getting Started

Installation

Download from postman.com/downloads. Available for Windows, macOS, Linux, and as a web app. See the official Postman docs for system requirements and proxy configuration.

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

MethodUse CaseExample
GETRetrieve dataGet user profile
POSTCreate resourceCreate new user
PUTReplace resourceUpdate entire user
PATCHPartial updateUpdate user email only
DELETERemove resourceDelete user

“The biggest mistake I see teams make with Postman is treating it as a one-off manual testing tool. Once you commit to structuring your Collections properly and wiring them into Newman for CI/CD, your API test suite becomes a first-class citizen in the pipeline — catching regressions before they ever reach staging.” — Yuri Kan, Senior QA Lead

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:
VariableInitial ValueCurrent Value
base_urlhttps://api.dev.example.comhttps://api.dev.example.com
api_keydev_key_123dev_key_123

Using Variables

Reference variables with double curly braces:

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

Variable Scopes

ScopeVisibilityUse Case
GlobalAll collectionsShared across everything
EnvironmentActive environmentURL, credentials per env
CollectionSingle collectionCollection-specific data
LocalSingle requestTemporary values

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. The complete pm object reference is documented in the official Postman scripting docs.

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. The full Newman CLI documentation is available on npmjs.com/package/newman and covers all reporter options.

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 Testing

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.

How do I run Postman tests in CI/CD?

Use Newman, Postman’s CLI runner. Install with npm install -g newman, then run newman run collection.json -e environment.json. Add Newman as a step in GitHub Actions, Jenkins, or any CI tool. Newman returns non-zero exit codes on test failures, so your pipeline automatically fails when API tests break.

What is the difference between Postman and Newman?

Postman is the desktop GUI application for designing requests, writing tests, and exploring APIs interactively. Newman is the command-line companion that runs those same collections without a GUI. You design tests in Postman, export the collection as JSON, and run it with Newman in CI/CD pipelines, Docker containers, or scheduled jobs.

See Also