Newman CLI: Running Postman Collections in CI/CD Pipelines

In this tutorial, you will learn about Newman CLI: Running Postman Collections in CI/CD Pipelines. We cover key concepts, practical examples, and best practices to help you master this topic.

Newman is a command-line collection runner for Postman that executes collections in CI/CD environments, supporting data-driven iterations, custom reporters, environment files, and integration with all major CI platforms.

What You'll Learn

How to install and use Newman, run collections with environment files, use data-driven iterations with CSV/JSON, configure reporters (CLI, HTML, JSON), set exit codes for CI, integrate with GitHub Actions and Jenkins, and handle secrets.

Why It Matters

Newman brings Postman tests into CI/CD, enabling automated API Regression Testing on every commit. DodaTech runs Newman in GitHub Actions on every PR, executing 100+ API tests in under 30 seconds.

Real-World Use

A developer pushes a branch changing the user API. GitHub Actions triggers, checks out code, installs Newman, runs the user API collection with staging environment variables, generates a JUnit XML report, and fails the build if any test fails.

flowchart LR
    A["Git Push\nto PR"] --> B["GitHub Actions\nTrigger"]
    B --> C["Install\nNewman"]
    C --> D["Load Environment\nVariables"]
    D --> E["Run Collection\nwith Data File"]
    E --> F{"Test\nResults"}
    F -->|All Pass| G["Build\nPasses"]
    F -->|Any Fail| H["Build\nFails"]
    G --> I["Merge\nPR"]
    H --> J["Fix Tests\nor Code"]
    style A fill:#dbeafe,stroke:#2563eb
    style E fill:#ef7d31,color:#fff
    style G fill:#bbf7d0,stroke:#16a34a
    style H fill:#fecaca,stroke:#dc2626

Installing Newman

# Install Newman globally
npm install -g newman

# Verify installation
newman --version
# Expected output:
# 6.2.0

# Install HTML reporter
npm install -g newman-reporter-htmlextra

Basic Newman Usage

# Run a collection with environment file
newman run DodaTech-API-Tests.postman_collection.json \
  -e DodaTech-Staging.postman_environment.json

# Expected output:
# DodaTech API Tests
# → Users
#   ✓ GET /users [200 OK, 450ms, 1.2KB]
#   ✓ POST /users [201 Created, 320ms, 0.8KB]
#   ✓ GET /users/:id [200 OK, 280ms, 0.6KB]
#   ✓ PUT /users/:id [200 OK, 310ms, 0.5KB]
#   ✓ DELETE /users/:id [204 No Content, 290ms, 0.3KB]
#
# ┌─────────────────────────┬──────────┬──────────┐
# │                         │ executed │  failed  │
# ├─────────────────────────┼──────────┼──────────┤
# │              iterations │        1 │        0 │
# │                requests │        5 │        0 │
# │            test-scripts │        5 │        0 │
# │      prerequest-scripts │        5 │        0 │
# │              assertions │       25 │        0 │
# │ total run duration: 2.3s │         │          │
# └─────────────────────────┴──────────┴──────────┘

Data-Driven Iterations

# Run with CSV data file (each row = one iteration)
newman run User-Tests.postman_collection.json \
  -e Staging.postman_environment.json \
  -d test-data/users.csv

# Run with JSON data file
newman run User-Tests.postman_collection.json \
  -e Staging.postman_environment.json \
  -d test-data/users.json

# Limit iterations
newman run User-Tests.postman_collection.json \
  -e Staging.postman_environment.json \
  -d test-data/users.json \
  --iteration-count 3

# Expected output (with data file of 5 rows):
# ┌─────────────────────────┬──────────┬──────────┐
# │              iterations │        5 │        0 │
# │                requests │       25 │        0 │
# │              assertions │      125 │        0 │
# └─────────────────────────┴──────────┴──────────┘

CI/CD Integration Examples

# GitHub Actions workflow
name: API Tests
on: [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 collections/DodaTech-API.postman_collection.json \
            -e environments/Staging.postman_environment.json \
            --reporters cli,junit,htmlextra \
            --reporter-junit-export results/junit-report.xml \
            --reporter-htmlextra-export results/html-report.html \
            --suppress-exit-code 1

      - name: Upload Test Results
        uses: actions/upload-artifact@v4
        with:
          name: test-reports
          path: results/

// Jenkins pipeline stage
stage('API Tests') {
    agent { docker { image 'node:20' } }
    steps {
        sh '''
            npm install -g newman newman-reporter-junit
            newman run collections/DodaTech-API.postman_collection.json \
                -e environments/Staging.postman_environment.json \
                --reporters cli,junit \
                --reporter-junit-export results/api-tests.xml
        '''
    }
    post {
        always {
            junit 'results/api-tests.xml'
        }
    }
}

Newman Options Reference

# Key Newman options

# Basic options
newman run collection.json \
  -e environment.json \              # Environment file
  -d data-file.json \                # Data file for iterations
  -n 5 \                             # Number of iterations
  --delay-request 1000 \             # Delay (ms) between requests
  --timeout-request 10000 \          # Request timeout (ms)
  --timeout-script 5000 \            # Script timeout (ms)

# Reporter options
  --reporters cli,json,junit,htmlextra \
  --reporter-json-export results.json \
  --reporter-junit-export junit.xml \
  --reporter-htmlextra-export report.html \

# Working directory options
  --working-dir ./tests \            # Base directory for files
  --folder "Users" \                 # Run specific folder only
  --env-var "base_url=https://api.dodatech.com"  # Override env vars

# Exit code options
  --suppress-exit-code 1             # Always exit 0 (for non-blocking)

Common Mistakes

1. Not Using Environment Files

Hardcoded URLs and tokens in collections break across environments. Always use separate environment JSON files for dev, staging, and production with appropriate values.

2. Ignoring Exit Codes

Newman exits with code 1 if any test fails. This causes CI to fail. If tests are non-blocking, use --suppress-exit-code 1. Otherwise, let CI handle the failure automatically.

3. Missing Data File Path Resolution

Newman resolves data file paths relative to the working directory, not the collection location. Use --working-dir or absolute paths to avoid file-not-found errors.

4. Not Installing Reporters

Reporters like htmlextra and junit are separate npm packages. Install them with npm install -g newman-reporter-htmlextra before running. Missing reporters fail silently.

5. Running Without Folder Filtering

Running a 500-request collection for every change is slow. Use --folder "Users" to run only the relevant folder. Run the full suite nightly or before release.

Practice Questions

1. How do you pass environment variables to Newman?
2. How do you run only a specific folder from a collection?
3. How does data-driven testing work with Newman?
4. How do you make Newman tests non-blocking in CI?

Answers:

1. Use -e environment.json for file-based variables, or --env-var "KEY=VALUE" for inline overrides. Never hardcode sensitive values in command line arguments.
2. Use --folder "FolderName". You can specify multiple folders with --folder "Users" --folder "Products". Only requests in those folders execute.
3. Provide a JSON or CSV data file with -d data.json. Each row becomes a separate iteration. Access fields in scripts via pm.iterationData.get("field").
4. Use --suppress-exit-code 1 to always exit 0 regardless of test results. Then Process the test report (JSON/JUnit) separately to determine pass/fail.

Challenge: Set up Newman in a CI pipeline: create a GitHub Actions workflow that runs a Postman collection on push, use environment-specific variable files, add data-driven iteration with a 3-row data file, configure HTML and JUnit reporters, upload test artifacts, and fail the build only if critical tests fail.

FAQ

{{< faq "Can Newman read environment variables from CI secrets?" "Yes, pass secrets as --env-var "API_KEY=${{ secrets.API_KEY }}" in CI. Newman reads them at runtime without exposing them in logs." >}}

Mini Project

Set up a complete Newman CI pipeline: export a Postman collection with 10 endpoints and environment file, write a GitHub Actions workflow, add data-driven iteration with 5 test cases, configure HTML and JUnit reporters, upload reports as artifacts, and add Slack notification on test failure.

What's Next

Supertest — write API tests using Supertest and Mocha.