Postman

Postman is an API platform that starts as a friendly GUI for sending requests and grows into full automated testing. You organize requests into Collections, parameterize them with Environments, add JavaScript test scripts, chain requests, and finally run the whole Collection in CI with the Newman CLI.

• Collections: grouped, saved, versionable requests (your test suite).
• Environments: named variable sets (local/staging/prod) referenced as {{baseUrl}}.
• Scripts: pre-request and test scripts in JavaScript using the pm.* API.
• Newman: run collections headless in CI and produce reports.

1. Install the Postman desktop app (or use the web version).
2. Create a Collection named "TestForge API".
3. Create an Environment named "Local" with a variable baseUrl = http://localhost:3000/api.
4. Add a request GET {{baseUrl}}/catalog/products?limit=5 and hit Send.

The Tests tab runs after the response arrives. Use pm.test() with pm.expect() (Chai assertions). Each pm.test becomes a pass/fail line in the results.

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

pm.test('returns an array of products', function () {
  const body = pm.response.json();
  pm.expect(body.data).to.be.an('array');
  pm.expect(body.data.length).to.be.at.most(5);
});

pm.test('responds quickly', function () {
  pm.expect(pm.response.responseTime).to.be.below(800);
});

A classic flow: log in, save the token to an environment variable in the login request’s Tests tab, then reference it on later requests. This chains requests without copy-pasting tokens.

// Request body (raw JSON):
// { "email": "customer@testforge.dev", "password": "Password123!" }

pm.test('login succeeds', function () {
  pm.response.to.have.status(200);
});

const body = pm.response.json();
pm.environment.set('accessToken', body.accessToken);
pm.environment.set('refreshToken', body.refreshToken);

On the protected request (e.g. POST {{baseUrl}}/cart/items), set the Authorization header to Bearer {{accessToken}} — or configure it once at the Collection level under the Authorization tab so every request inherits it.

Authorization: Bearer {{accessToken}}
Content-Type: application/json

Body (raw JSON):
{ "productId": "{{productId}}", "quantity": 1 }

Pre-request scripts run before the request is sent — useful for computing timestamps, generating data, or grabbing an id from a previous call. You can even send an HTTP call with pm.sendRequest to fetch a fresh token first.

// Fetch a product id to use in this request
pm.sendRequest(pm.environment.get('baseUrl') + '/catalog/products?limit=1', function (err, res) {
  if (!err) {
    const id = res.json().data[0].id;
    pm.environment.set('productId', id);
  }
});

The Collection Runner executes every request in order and can iterate over a CSV/JSON data file, substituting {{variables}} per row — great for testing many inputs.

[
  { "email": "customer@testforge.dev", "password": "Password123!", "expected": 200 },
  { "email": "customer@testforge.dev", "password": "wrong", "expected": 401 }
]

pm.test('status matches expected for this row', function () {
  pm.response.to.have.status(Number(pm.iterationData.get('expected')));
});

Export the Collection and Environment to JSON, commit them, and run headless with Newman. This turns your Postman suite into a CI gate.

npm install -g newman
newman run TestForge_API.postman_collection.json \
  -e Local.postman_environment.json \
  --reporters cli,junit \
  --reporter-junit-export results.xml

name: newman
on: [push, pull_request]
jobs:
  api:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 20 }
      - run: npm install -g newman
      - run: newman run TestForge_API.postman_collection.json -e Local.postman_environment.json

• Parameterize everything with environment/collection variables — no hard-coded URLs or tokens.
• Set auth once at the collection level so requests inherit it.
• Keep secrets in environment variables marked as "secret", and do not commit real credentials.
• Write at least one assertion per request (status + one body check).
• Version the exported collection/environment JSON in git so changes are reviewable.
• Run via Newman in CI — the GUI is for authoring, Newman is for gating.

Postman resolves {{variables}} against several scopes, each with a different lifetime. Understanding the order matters because a name defined in more than one scope resolves to the narrowest one that is set.

• Global: available across every collection and environment; the widest, longest-lived scope — use sparingly.
• Collection: shared by all requests in one collection (pm.collectionVariables), good for a baseUrl that belongs to one API.
• Environment: a named, switchable set (Local / Staging / Prod) via pm.environment — the workhorse scope.
• Local: created inside a script for the current request/run only; never persisted.
• Data: columns from the CSV/JSON file the Collection Runner iterates over (pm.iterationData) — read-only, one row at a time.

Pre-request scripts run before the request is sent (set up data, compute a signature, refresh a token). Test scripts run after the response arrives and hold your assertions with pm.test() + pm.expect(). Persisting a value with pm.environment.set() in a test script is exactly how you hand a login token to later requests.

// Request body (raw JSON):
// { "email": "customer@testforge.dev", "password": "Password123!" }

pm.test('login returns 200', function () {
  pm.response.to.have.status(200);
});

pm.test('response carries an access token', function () {
  const body = pm.response.json();
  pm.expect(body).to.have.property('accessToken');
  // Persist for later requests in this environment
  pm.environment.set('accessToken', body.accessToken);
  pm.environment.set('refreshToken', body.refreshToken);
});

// Local variable: exists only for this request execution
const nonce = 'req-' + Date.now();
pm.variables.set('nonce', nonce);

// Read the token saved by the login request
const token = pm.environment.get('accessToken');
if (!token) {
  console.warn('No accessToken set — run POST /auth/login first');
}

Real API tests are workflows, not single calls. Postman chains requests two ways: capture a value in one request and reference it in the next (via a shared variable), or fetch something inline with pm.sendRequest before the current request even fires.

// Grab a real product id so the cart request has something to add
pm.sendRequest(
  {
    url: pm.environment.get('baseUrl') + '/catalog/products?limit=1',
    method: 'GET',
  },
  function (err, res) {
    if (err) { return; }
    const id = res.json().data[0].id;
    pm.environment.set('productId', id);
  }
);

To control ordering inside a Collection Runner run, use postman.setNextRequest() to jump to a named request (or stop the run). By default the runner walks requests top to bottom; setNextRequest lets you loop, skip, or branch — for example, add to cart, then jump straight to checkout.

pm.test('item added to cart', function () {
  pm.response.to.have.status(201);
});

if (pm.response.code === 201) {
  postman.setNextRequest('Checkout order');
} else {
  // Stop the run so we don't attempt checkout on an empty cart
  postman.setNextRequest(null);
}

Data-driven testing runs the whole collection once per row of a data file. Attach a CSV or JSON file in the Collection Runner; each row exposes its columns as pm.iterationData, and any {{column}} in a URL, header, or body is substituted per iteration.

[
  { "email": "customer@testforge.dev", "password": "Password123!", "expected": 200 },
  { "email": "customer@testforge.dev", "password": "wrong", "expected": 401 },
  { "email": "nobody@testforge.dev", "password": "Password123!", "expected": 401 }
]

pm.test('status matches the expected code for this row', function () {
  const expected = Number(pm.iterationData.get('expected'));
  pm.response.to.have.status(expected);
});

Newman is the command-line runner for Postman collections. Export the collection and environment to JSON, commit them, and Newman runs the exact same requests and test scripts headless — so your Postman suite becomes a CI gate that fails the build on a broken API.

npm install -g newman

# Run a collection against the Local environment
newman run TestForge_API.postman_collection.json \
  -e Local.postman_environment.json

# Data-driven run: one iteration per row of the CSV/JSON file
newman run TestForge_API.postman_collection.json \
  -e Local.postman_environment.json \
  -d login-cases.json

Reporters control the output. The cli reporter prints to the terminal; junit produces XML that CI can parse into test results; the htmlextra reporter (installed separately) gives a rich shareable report. You can emit several at once.

# CLI output plus a JUnit XML file for CI to ingest
newman run TestForge_API.postman_collection.json \
  -e Local.postman_environment.json \
  --reporters cli,junit \
  --reporter-junit-export results.xml

# Rich HTML report (npm install -g newman-reporter-htmlextra first)
newman run TestForge_API.postman_collection.json \
  -e Local.postman_environment.json \
  --reporters cli,htmlextra \
  --reporter-htmlextra-export report.html

# In a GitHub Actions job, after starting the API:
npm install -g newman
newman run TestForge_API.postman_collection.json \
  -e CI.postman_environment.json \
  --reporters cli,junit \
  --reporter-junit-export results.xml
# A non-zero exit code (any failed assertion) fails the CI job.

• Docs: learning.postman.com
• Explore the pm.* API (pm.response, pm.expect, pm.collectionVariables, pm.sendRequest).
• Practice: build a TestForge collection covering login → browse → add to cart → checkout, chaining ids and tokens between requests, then run it with Newman.