Newman CLI for Postman — Complete Guide

In this tutorial, you will learn about Newman CLI for Postman. We cover key concepts, practical examples, and best practices to help you master this topic.

Newman is Postman's command-line tool for running collections. It enables automated API testing in CI/CD pipelines, supports multiple reporters (CLI, JSON, HTML, JUnit), and accepts environment and data files for parameterization.

What You'll Learn

• Newman installation and basic usage
• Running collections with environment files
• CLI reporters and custom reporters
• Data-driven testing with CSV/JSON files
• CI/CD integration

Why It Matters

Newman brings Postman collections into automated pipelines. Teams run the same collections locally, in CI, and in monitoring. Newman provides consistent results across environments.

Real-World Use

Many organizations run Newman in GitHub Actions, Jenkins, and GitLab CI. Postman's own monitoring uses Newman under the hood. Teams use Newman for nightly Regression Testing.

flowchart LR
    Collection[Postman Collection JSON] --> Newman[Newman CLI]
    Environment[Environment JSON] --> Newman
    Data[Data File CSV/JSON] --> Newman
    Newman --> CLI[CLI Reporter]
    Newman --> HTML[HTML Reporter]
    Newman --> JUnit[JUnit Reporter]
    Newman --> JSON[JSON Reporter]

Teacher Mindset

Newman runs the same collections you build in Postman. Export collections and environments as JSON. Use data files for test parameterization. Add Newman to your CI pipeline for automated regression.

Code Examples

# Example 1: Basic Newman commands
# Install Newman
npm install -g newman

# Run a collection with environment
newman run collection.json \
  --environment staging.json \
  --reporters cli,json

# Run with HTML reporter
newman run collection.json \
  -e staging.json \
  -r htmlextra \
  --reporter-htmlextra-export ./reports/report.html

# Run with data file
newman run collection.json \
  -e staging.json \
  -d test-data.csv

# Example 2: Newman with options
newman run api-tests.json \
  --folder "Users" \
  --env-var "base_url=https://api.example.com" \
  --delay-request 100 \
  --timeout-request 5000 \
  --bail \
  --verbose

# Global variables
newman run collection.json \
  --global-var "api_key=$API_KEY" \
  --global-var "environment=ci"

# Example 3: GitHub Actions workflow
name: API Tests
on: [push]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
      - run: npm install -g newman
      - run: |
          newman run collections/api-tests.json \
            --environment envs/ci.json \
            --reporters cli,junit \
            --reporter-junit-export results.xml
      - uses: dorny/test-reporter@v1
        if: success() || failure()
        with:
          name: API Tests
          path: results.xml
          reporter: java-junit

Common Mistakes

• Running collections without the correct environment file
• Not using data files for parameterized testing
• Ignoring Newman exit codes in CI pipelines
• Forgetting to install Newman globally or in CI
• Using absolute paths in environment variables

Practice

1. Export a Postman collection and environment as JSON files.
2. Run the collection with Newman using the CLI reporter.
3. Generate an HTML report with htmlextra reporter.
4. Run the collection with a CSV data file for parameterization.
5. Challenge: Add Newman to a GitHub Actions workflow with JUnit reporting.

FAQ

Mini Project

Set up a Newman CI pipeline. Export a Postman collection with 5 API tests. Create a GitHub Actions workflow that runs the collection with Newman, generates JUnit results, and publishes a test report.

What's Next

Next, you will learn about Supertest for testing Node.js APIs.