Data-Driven Runs & Newman

The Collection Runner#

The Collection Runner executes every request in a collection (or folder) in order, runs all the scripts and shows a pass/fail summary. Open it from the collection's Run button, choose an environment, set the number of iterations and a delay between requests, and start.

A collection designed for the runner should:

• Run top to bottom without manual steps (log in first, chain the rest).
• Create its own data and not depend on leftovers from earlier runs.
• Have meaningful test names — they become your report.

Data-driven runs with a CSV file#

Run the same requests once per row of a data file. Column names become variables available as {{column}} and through pm.iterationData.

# login-cases.csv
username,password,expectedStatus
emilys,emilyspass,200
emilys,wrong-password,400
unknown-user,emilyspass,400

Request body for POST {{baseUrl}}/auth/login (with baseUrl = https://dummyjson.com):

{
  "username": "{{username}}",
  "password": "{{password}}"
}

Post-response script:

const expected = Number(pm.iterationData.get('expectedStatus'));

pm.test(`${pm.iterationData.get('username')} → ${expected}`, () => {
  pm.response.to.have.status(expected);
});

if (expected === 200) {
  pm.test('Returns a token', () => {
    pm.expect(pm.response.json().accessToken).to.be.a('string');
  });
}

In the Collection Runner, select the CSV under Data; Postman sets iterations to the number of rows. Each row is a separate test result. JSON data files work the same way (an array of objects).

Newman: Postman on the command line#

Newman runs Postman collections from the terminal — which means it runs in CI.

npm install -g newman

Export the collection (… → Export → Collection v2.1) and environment (Environments → … → Export), then:

newman run jsonplaceholder.postman_collection.json \
  -e staging.postman_environment.json

Useful options:

newman run collection.json \
  -e staging.postman_environment.json \
  -d login-cases.csv \
  -n 3 \
  --env-var "password=$TEST_PASSWORD" \
  --folder "Posts" \
  --delay-request 100 \
  --bail

Newman exits with code 1 if any test fails, so CI marks the build red automatically.

HTML reports#

npm install -g newman-reporter-htmlextra
newman run collection.json -e staging.postman_environment.json \
  -r cli,htmlextra --reporter-htmlextra-export reports/api-report.html

The htmlextra report shows every request, response and assertion — great for sharing with developers.

Running Newman in GitHub Actions#

Commit the exported collection and a non-secret environment to the repo (e.g. postman/), and pass secrets from repository secrets:

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

on:
  pull_request:
  push:
    branches: [main]
  schedule:
    - cron: '0 3 * * *'          # also run nightly at 03:00 UTC

jobs:
  newman:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - 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/api.postman_collection.json \
            -e postman/staging.postman_environment.json \
            --env-var "password=${{ secrets.API_TEST_PASSWORD }}" \
            -r cli,htmlextra --reporter-htmlextra-export reports/api-report.html
      - uses: actions/upload-artifact@v4
        if: always()
        with:
          name: api-report
          path: reports/

Keeping collections in sync#

Exported JSON files can drift from the copy in Postman. Options:

• Treat the repo as the source of truth: edit in Postman, export, commit — with a review like any code change.
• Run collections straight from the Postman API with an API key: newman run "https://api.getpostman.com/collections/<id>?apikey=$POSTMAN_API_KEY".
• Use Postman's Git integration on paid plans.

Postman CLI#

Postman also ships the Postman CLI (postman collection run <collection-id>), which runs collections stored in your Postman workspace and reports results back to Postman. Newman remains the most common choice for running exported collections in open-source CI pipelines.

Next, review the Postman & API testing interview questions.