Skip to main content
API Testing with Postman·Lesson 5 of 5

Newman & CI/CD Integration

Postman's GUI is great for writing and debugging tests, but for automated testing in CI/CD pipelines, you need Newman — Postman's command-line companion.

What Is Newman?

Newman is an open-source CLI tool that runs Postman collections. It takes the same collection JSON file you export from Postman and executes every request and test in sequence.

Installing Newman

Newman requires Node.js. Install it globally:

npm install -g newman

Verify the installation:

newman --version

Exporting from Postman

Before running with Newman, export your collection and environment:

  1. Collection: Right-click → Export → Save as collection.json
  2. Environment: Click the environment → Export → Save as env.json

Running a Collection

Basic execution:

newman run collection.json

With an environment:

newman run collection.json -e env.json

Newman Output

Newman prints a detailed report:

┌─────────────────────────┬──────────┬──────────┐
│                         │ executed │   failed │
├─────────────────────────┼──────────┼──────────┤
│        iterations       │     1    │     0    │
├─────────────────────────┼──────────┼──────────┤
│         requests        │    12    │     0    │
├─────────────────────────┼──────────┼──────────┤
│      test-scripts       │    12    │     0    │
├─────────────────────────┼──────────┼──────────┤
│      assertions         │    28    │     2    │
├─────────────────────────┼──────────┼──────────┤
│ total run duration      │   4.2s   │          │
└─────────────────────────┴──────────┴──────────┘

Useful Newman Options

# Run multiple iterations (load testing)
newman run collection.json -n 10

# Add a delay between requests (ms)
newman run collection.json --delay-request 500

# Set a timeout for requests (ms)
newman run collection.json --timeout-request 5000

# Override environment variables
newman run collection.json --env-var "base_url=https://staging.api.com"

# Generate HTML report
newman run collection.json -r htmlextra

# Generate JUnit XML report (for CI)
newman run collection.json -r junit --reporter-junit-export results.xml

HTML Reports

Install the HTML reporter:

npm install -g newman-reporter-htmlextra

Generate a report:

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

This creates a beautiful HTML report with:

  • Pass/fail summary
  • Request/response details
  • Test assertion results
  • Response time charts

CI/CD Integration

GitHub Actions

name: API Tests
on: [push, pull_request]

jobs:
  api-tests:
    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 tests/collection.json \
            -e tests/env.json \
            -r cli,htmlextra,junit \
            --reporter-htmlextra-export reports/api-report.html \
            --reporter-junit-export reports/api-results.xml

      - name: Upload Test Report
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: api-test-report
          path: reports/

GitLab CI

api-tests:
  image: node:20
  stage: test
  script:
    - npm install -g newman newman-reporter-htmlextra
    - newman run tests/collection.json
        -e tests/env.json
        -r cli,htmlextra,junit
        --reporter-htmlextra-export report.html
        --reporter-junit-export results.xml
  artifacts:
    when: always
    paths:
      - report.html
    reports:
      junit: results.xml

Data-Driven Testing

Run the same requests with different data using a CSV or JSON file:

test-data.csv:

email,password,expected_status
valid@test.com,ValidPass123,200
invalid@test.com,wrong,401
,ValidPass123,400
valid@test.com,,400

In Postman, reference columns with {{email}}, {{password}}, {{expected_status}}.

Test script:

pm.test("Status matches expected", function () {
    const expected = parseInt(pm.iterationData.get("expected_status"));
    pm.response.to.have.status(expected);
});

Run with data file:

newman run collection.json -d test-data.csv

Newman runs the collection once per row in the CSV, substituting the variables each time.

Best Practices

  • Version control your collections: Export and commit collection.json alongside your code.
  • Use environment files per stage: dev.json, staging.json, production.json.
  • Don't hardcode secrets: Pass sensitive values via --env-var in CI, not in exported files.
  • Fail the pipeline on test failure: Newman exits with code 1 when tests fail — CI/CD tools pick this up automatically.
  • Run on every PR: Catch API regressions before they're merged.