Keyboard Shortcuts N Next post
P Previous post
S Save / unsave
R Read aloud
T Toggle theme
/ Focus search
Esc Close panels
🔥
Ready to read...
APIs APIs From Zero to Real-World API Testing & Automation CI/CD Module 7 — Postman Newman Postman

Newman — Running Postman Collections from the Command Line

Reviewed & accurate
AI Summary

What You'll Learn

  • What Newman is and why it exists
  • How to run a Postman collection from the command line
  • How to generate HTML/JSON reports
  • How to integrate Newman into CI/CD pipelines

Why This Matters

Postman's GUI is great for development. But CI/CD pipelines do not have a GUI — they run on servers, triggered by git pushes. Newman is the command-line version of Postman's Collection Runner. It runs the same collections, executes the same scripts, and produces reports you can archive or send to Slack. Without Newman, your Postman tests cannot run in CI.

What Is Newman?

Newman is the CLI companion to Postman. It is a Node.js tool that runs Postman collections from the terminal. Same collection file, same scripts, same assertions — just no GUI.

Installing Newman

npm install -g newman

Verify the install:

newman --version

Exporting a Collection for Newman

Newman needs the collection as a JSON file. Export it from Postman:

  1. In Postman, right-click your collection.
  2. Click Export.
  3. Choose Collection v2.1 (the latest format).
  4. Save as my-collection.json.

Also export your environment:

  1. Click the environment dropdown.
  2. Click the gear icon next to your environment.
  3. Click Export.
  4. Save as my-environment.json.

Running a Collection

newman run my-collection.json

Newman runs every request in the collection, executes pre-request and test scripts, and prints a summary:

→ User Creation
  POST https://jsonplaceholder.typicode.com/users [201 Created, 312B, 187ms]
  ✓ Status is 201
  ✓ Response has ID
  ✓ Name matches

→ User Fetch
  GET https://jsonplaceholder.typicode.com/users/11 [200 OK, 234B, 145ms]
  ✓ Status is 200
  ✓ ID matches

┌─────────────────────────┬──────────┬──────────┐
│                         │ executed │   failed │
├─────────────────────────┼──────────┼──────────┤
│              iterations │        1 │        0 │
│                requests │        2 │        0 │
│            test-scripts │        2 │        0 │
│      prerequest-scripts │        0 │        0 │
│              assertions │        5 │        0 │
└─────────────────────────┴──────────┴──────────┘

Running with an Environment

newman run my-collection.json \
  -e my-environment.json

The -e flag supplies the environment file. Variables in the collection resolve from it.

Useful Newman Flags

FlagWhat it does
-e file.jsonEnvironment file
-d data.csvData file for data-driven testing
-n 5Run the collection 5 times
--folder "Posts"Run only a specific folder
-r cli,htmlReporters to use (cli = terminal output, html = HTML report)
--reporter-html-export report.htmlSave HTML report to a file
--reporter-json-export report.jsonSave JSON report to a file
--timeout-request 30000Request timeout in ms
--bailStop on first failure
--insecureSkip SSL verification (testing only)

Generating Reports

newman run my-collection.json \
  -e my-environment.json \
  -r cli,html,json \
  --reporter-html-export reports/api-tests.html \
  --reporter-json-export reports/api-tests.json

This produces:

  • Terminal output (cli reporter)
  • An HTML report at reports/api-tests.html — open in a browser
  • A JSON report at reports/api-tests.json — parse for custom dashboards

Running Data-Driven Tests

newman run my-collection.json \
  -e my-environment.json \
  -d test-data.csv

Newman runs the collection once per row in the CSV, just like the Postman Collection Runner.

Integrating with CI/CD — GitHub Actions Example

Create .github/workflows/api-tests.yml in your repo:

name: API Tests

on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]

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/my-collection.json \
            -e environments/staging.json \
            -r cli,htmlextra \
            --reporter-htmlextra-export reports/api-tests.html

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

Every push or PR triggers the tests. If any assertion fails, the build fails. The HTML report is uploaded as an artifact you can download.

Common Mistakes

  1. Forgetting to export the environment. Newman has no access to your Postman workspace. You must export both the collection and the environment.
  2. Hard-coding secrets in the environment file. Use CI secrets instead. In GitHub Actions: env: TOKEN: ${{ secrets.API_TOKEN }}, then reference $TOKEN in a script that injects it into the environment file.
  3. Not failing the build on test failure. Newman exits with non-zero status on failure. Most CI tools treat this as a failed build automatically.
  4. Skipping the report. Without a report, you cannot debug failures. Always generate HTML and JSON reports.
  5. Running every test on every push. For large collections, this is slow. Use --folder to run only critical tests on PRs, full suite on merges to main.

Practical Exercise (20 minutes)

  1. Install Newman: npm install -g newman
  2. Export a Postman collection and environment as JSON files.
  3. Run the collection with Newman: newman run collection.json -e env.json
  4. Add the HTML reporter: -r cli,html --reporter-html-export report.html
  5. Open report.html in a browser.
  6. Bonus: run the same collection with a CSV data file.

Mini Challenge

Set up a GitHub Actions workflow (or any CI you use) that runs your Postman collection on every push to main. Make sure: (1) Newman is installed, (2) the collection and environment are in the repo, (3) secrets are used for tokens, (4) the HTML report is uploaded as an artifact, (5) the build fails if any test fails.

Key Takeaways

  • Newman is the CLI version of Postman's Collection Runner. Same collections, no GUI.
  • Export collections and environments as JSON files. Newman reads these.
  • Useful flags: -e environment, -d data file, -r reporters, --folder subset.
  • Always generate HTML and JSON reports for debugging.
  • Integrate with CI/CD: install Newman, run the collection, fail the build on test failure, upload reports as artifacts.
Course continuity
Previously: Lesson 38 covered data-driven testing in Postman.
Today: You learned to run Postman collections from the command line and in CI.
Next: Module 7 is complete. Module 8 begins with lesson 40 — API Automation Architecture with JavaScript.

FAQ

Can I use Newman without Postman?

Yes. You can write collection JSON files by hand (or generate them with a script) and run them with Newman. Postman the GUI is just a friendly editor for the same JSON format. Some teams write collections programmatically.

How is Newman different from running tests with Jest or Mocha?

Newman runs Postman collections — requests and scripts authored in Postman. Jest/Mocha run JavaScript test files. They overlap but serve different workflows. Postman+Newman is faster for teams that already use Postman. Jest/Mocha is more flexible for custom test code. Module 8 covers the Jest/Mocha approach.

Test Your Knowledge
How did you find this?

Comments

Join the discussion! Sign in with your Google or Blogger account, or comment as Anonymous - no account needed. For quick questions, also reach me on Telegram @cytestch.

Comments