Postman

Postman is an API platform for building and using APIs, providing automated collection testing, mock servers, environment management, and Newman CLI integration for CI/CD.

When to Use

REST, GraphQL, & gRPC API Testing: Designing requests, inspecting headers, and verifying streaming payloads.
Automated CI/CD API Regression Suites: Running Postman Collections in automated pipelines using the Newman CLI.
Dynamic Authentication Handling: Scripting OAuth 2.0 token refreshes, HMAC signatures, and AWS SigV4 in Pre-request scripts.
Mock Servers & API Documentation: Creating instant mock endpoints and publishing interactive team API documentation.

Quick Start

1. Test Script in Postman

// Tests tab in Postman Request
pm.test("Status code is 200 OK", function () {
  pm.response.to.have.status(200);
});

pm.test("Response time is under 400ms", function () {
  pm.expect(pm.response.responseTime).to.be.below(400);
});

pm.test("Token returned and set in environment", function () {
  const jsonData = pm.response.json();
  pm.expect(jsonData.access_token).to.be.a("string");
  pm.environment.set("AUTH_TOKEN", jsonData.access_token);
});

2. Run via Newman CLI

npm install -g newman
newman run collection.json -e environment.json --reporters cli,junit

Core Concepts

Pre-Request Script: Automated JWT / HMAC Signature

Generating dynamic cryptographic signatures and injecting timestamps before request execution:

// Pre-request Script (PM API)
const timestamp = Math.floor(Date.now() / 1000).toString();
const apiKey = pm.environment.get("API_KEY");
const apiSecret = pm.environment.get("API_SECRET");
const requestBody = pm.request.body.raw || "";

// Generate SHA256 HMAC
const message = `${pm.request.method}\n${pm.request.url.getPath()}\n${timestamp}\n${requestBody}`;
const signature = CryptoJS.HmacSHA256(message, apiSecret).toString(
  CryptoJS.enc.Hex,
);

pm.request.headers.add({ key: "X-Auth-Key", value: apiKey });
pm.request.headers.add({ key: "X-Auth-Timestamp", value: timestamp });
pm.request.headers.add({ key: "X-Auth-Signature", value: signature });

Automated Response Assertions & Variable Extraction

Validating HTTP response code, schema, and saving output for downstream requests:

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

pm.test("Response contains valid user session", function () {
  const json = pm.response.json();
  pm.expect(json).to.have.property("access_token");
  pm.expect(json.expires_in).to.be.above(0);

  // Propagate access token to active environment
  pm.environment.set("AUTH_TOKEN", json.access_token);
});

pm.test("Response time is under 300ms", function () {
  pm.expect(pm.response.responseTime).to.be.below(300);
});

Newman CLI Execution in CI/CD Pipeline

Executing collection tests headlessly and generating JUnit reports:

# Run Postman collection with environment and HTML/JUnit reports
npx newman run ./collections/auth-api-tests.json \
  -e ./environments/staging.postman_environment.json \
  --reporters cli,junit \
  --reporter-junit-export ./reports/newman-results.xml \
  --bail \
  --env-var "BASE_URL=https://staging-api.example.com"

Common Patterns

Pre-Request HMAC Signature Generation

Problem: API requests require timestamp and SHA-256 HMAC signature headers calculated per request.
Solution: Generate headers dynamically in the Pre-request Script tab.

const secret = pm.environment.get("API_SECRET");
const timestamp = Math.floor(Date.now() / 1000).toString();
const payload = pm.request.body.raw || "";

const message = `${timestamp}.${pm.request.method}.${payload}`;
const signature = CryptoJS.HmacSHA256(message, secret).toString();

pm.request.headers.add({ key: "X-Timestamp", value: timestamp });
pm.request.headers.add({ key: "X-Signature", value: signature });

Chained API Testing (Login -> Create -> Delete)

Problem: Execute multi-step end-to-end user workflows using dynamically extracted identifiers.
Solution: Set variables in pm.collectionVariables and trigger conditional next requests via postman.setNextRequest().

// Step 1: Capture created resource ID
const res = pm.response.json();
pm.collectionVariables.set("ITEM_ID", res.id);

// Conditionally skip to cleanup on error
if (pm.response.code !== 201) {
  postman.setNextRequest("Cleanup Endpoint");
}

Best Practices

Do:

Parameterize environment URLs, tenant IDs, and credentials using {{base_url}} variables.
Store sensitive credentials in Environment variables with type Secret to mask values from UI and exports.
Run collections via Newman in CI/CD workflows to prevent regressions before deployment.
Organize collections by domain resource with clear folder-level authorization inheritance.

Don't:

Hardcode raw JWT tokens or passwords directly in request headers or body payloads.
Commit environment files containing active production API keys to public repositories.
Duplicate authentication headers manually; configure Auth at the Collection level.

Troubleshooting

| Error | Cause | Solution | | --------------------------------------------------------- | ------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------- | | SSL Error: Self-signed certificate in certificate chain | Target endpoint uses local dev or untrusted SSL certificate | Turn off SSL certificate verification in Postman Settings > General, or pass --insecure to Newman. | | Variable not substituting ({{API_URL}} remains literal) | Active environment not selected in dropdown or variable misspelled | Ensure environment dropdown in top-right is selected and scope matches (environment vs collectionVariables). | | Newman exit code failure in CI pipeline | Assertion failed in collection run | Check test summary output; run Newman with --bail to stop on first failure or inspect JUnit XML report. |

References

Postman Documentation