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:
- In Postman, right-click your collection.
- Click Export.
- Choose Collection v2.1 (the latest format).
- Save as
my-collection.json.
Also export your environment:
- Click the environment dropdown.
- Click the gear icon next to your environment.
- Click Export.
- 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
| Flag | What it does |
|---|---|
-e file.json | Environment file |
-d data.csv | Data file for data-driven testing |
-n 5 | Run the collection 5 times |
--folder "Posts" | Run only a specific folder |
-r cli,html | Reporters to use (cli = terminal output, html = HTML report) |
--reporter-html-export report.html | Save HTML report to a file |
--reporter-json-export report.json | Save JSON report to a file |
--timeout-request 30000 | Request timeout in ms |
--bail | Stop on first failure |
--insecure | Skip 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
- Forgetting to export the environment. Newman has no access to your Postman workspace. You must export both the collection and the environment.
- Hard-coding secrets in the environment file. Use CI secrets instead. In GitHub Actions:
env: TOKEN: ${{ secrets.API_TOKEN }}, then reference$TOKENin a script that injects it into the environment file. - 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.
- Skipping the report. Without a report, you cannot debug failures. Always generate HTML and JSON reports.
- Running every test on every push. For large collections, this is slow. Use
--folderto run only critical tests on PRs, full suite on merges to main.
Practical Exercise (20 minutes)
- Install Newman:
npm install -g newman - Export a Postman collection and environment as JSON files.
- Run the collection with Newman:
newman run collection.json -e env.json - Add the HTML reporter:
-r cli,html --reporter-html-export report.html - Open
report.htmlin a browser. - 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:
-eenvironment,-ddata file,-rreporters,--foldersubset. - 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.
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.
Comments
Comments
Post a Comment