Newman - Postman CLI Runner

Newman is the command-line Collection Runner for Postman. Run and test Postman collections directly from the command line with powerful reporting, environment management, and CI/CD integration.

Quick Start

Installation

bash

# Global install (recommended)
npm install -g newman

# Project-specific
npm install --save-dev newman

# Verify
newman --version

Basic Execution

bash

# Run collection
newman run collection.json

# With environment
newman run collection.json -e environment.json

# With globals
newman run collection.json -g globals.json

# Combined
newman run collection.json -e env.json -g globals.json -d data.csv

Core Workflows

1. Export from Postman Desktop

In Postman:

•Collections → Click "..." → Export
•Choose "Collection v2.1" (recommended)
•Save as collection.json

Environment:

•Environments → Click "..." → Export
•Save as environment.json

2. Run Tests

bash

# Basic run
newman run collection.json

# With detailed output
newman run collection.json --verbose

# Fail on errors
newman run collection.json --bail

# Custom timeout (30s)
newman run collection.json --timeout-request 30000

3. Data-Driven Testing

CSV format:

csv

username,password
user1,pass1
user2,pass2

Run:

bash

newman run collection.json -d test_data.csv --iteration-count 2

4. Reporters

bash

# CLI only (default)
newman run collection.json

# HTML report
newman run collection.json --reporters cli,html --reporter-html-export report.html

# JSON export
newman run collection.json --reporters cli,json --reporter-json-export results.json

# JUnit (for CI)
newman run collection.json --reporters cli,junit --reporter-junit-export junit.xml

# Multiple reporters
newman run collection.json --reporters cli,html,json,junit \
  --reporter-html-export ./reports/newman.html \
  --reporter-json-export ./reports/newman.json \
  --reporter-junit-export ./reports/newman.xml

5. Security Best Practices

❌ NEVER hardcode secrets in collections!

Use environment variables:

bash

# Export sensitive vars
export API_KEY="your-secret-key"
export DB_PASSWORD="your-db-pass"

# Newman auto-loads from env
newman run collection.json -e environment.json

# Or pass directly
newman run collection.json --env-var "API_KEY=secret" --env-var "DB_PASSWORD=pass"

In Postman collection tests:

javascript

// Use {{API_KEY}} in requests
pm.request.headers.add({key: 'Authorization', value: `Bearer {{API_KEY}}`});

// Access in scripts
const apiKey = pm.environment.get("API_KEY");

Environment file (environment.json):

json

{
  "name": "Production",
  "values": [
    {"key": "BASE_URL", "value": "https://api.example.com", "enabled": true},
    {"key": "API_KEY", "value": "{{$processEnvironment.API_KEY}}", "enabled": true}
  ]
}

Newman will replace {{$processEnvironment.API_KEY}} with the environment variable.

Common Use Cases

CI/CD Integration

See references/ci-cd-examples.md for GitHub Actions, GitLab CI, and Jenkins examples.

Automated Regression Testing

bash

#!/bin/bash
# scripts/run-api-tests.sh

set -e

echo "Running API tests..."

newman run collections/api-tests.json \
  -e environments/staging.json \
  --reporters cli,html,junit \
  --reporter-html-export ./test-results/newman.html \
  --reporter-junit-export ./test-results/newman.xml \
  --bail \
  --color on

echo "Tests completed. Report: ./test-results/newman.html"

Load Testing

bash

# Run with high iteration count
newman run collection.json \
  -n 100 \
  --delay-request 100 \
  --timeout-request 5000 \
  --reporters cli,json \
  --reporter-json-export load-test-results.json

Parallel Execution

bash

# Install parallel runner
npm install -g newman-parallel

# Run collections in parallel
newman-parallel -c collection1.json,collection2.json,collection3.json \
  -e environment.json \
  --reporters cli,html

Advanced Features

Custom Scripts

Pre-request Script (in Postman):

javascript

// Generate dynamic values
pm.environment.set("timestamp", Date.now());
pm.environment.set("nonce", Math.random().toString(36).substring(7));

Test Script (in Postman):

javascript

// Status code check
pm.test("Status is 200", function() {
    pm.response.to.have.status(200);
});

// Response body validation
pm.test("Response has user ID", function() {
    const jsonData = pm.response.json();
    pm.expect(jsonData).to.have.property('user_id');
});

// Response time check
pm.test("Response time < 500ms", function() {
    pm.expect(pm.response.responseTime).to.be.below(500);
});

// Set variable from response
pm.environment.set("user_token", pm.response.json().token);

SSL/TLS Configuration

bash

# Disable SSL verification (dev only!)
newman run collection.json --insecure

# Custom CA certificate
newman run collection.json --ssl-client-cert-list cert-list.json

# Client certificates
newman run collection.json \
  --ssl-client-cert client.pem \
  --ssl-client-key key.pem \
  --ssl-client-passphrase "secret"

Error Handling

bash

# Continue on errors
newman run collection.json --suppress-exit-code

# Fail fast
newman run collection.json --bail

# Custom error handling in wrapper
#!/bin/bash
newman run collection.json -e env.json
EXIT_CODE=$?

if [ $EXIT_CODE -ne 0 ]; then
    echo "Tests failed! Exit code: $EXIT_CODE"
    # Send alert, rollback deployment, etc.
    exit 1
fi

Troubleshooting

Collection not found:

•Use absolute paths: newman run /full/path/to/collection.json
•Check file permissions: ls -la collection.json

Environment variables not loading:

•Verify syntax: {{$processEnvironment.VAR_NAME}}
•Check export: echo $VAR_NAME
•Use --env-var flag as fallback

Timeout errors:

•Increase timeout: --timeout-request 60000 (60s)
•Check network connectivity
•Verify API endpoint is reachable

SSL errors:

•Development: Use --insecure temporarily
•Production: Add CA cert with --ssl-extra-ca-certs

Memory issues (large collections):

•Reduce iteration count
•Split collection into smaller parts
•Increase Node heap: NODE_OPTIONS=--max-old-space-size=4096 newman run ...

Best Practices

•Version Control: Store collections and environments in Git
•Environment Separation: Separate files for dev/staging/prod
•Secret Management: Use environment variables, never commit secrets
•Meaningful Names: Use descriptive collection and folder names
•Test Atomicity: Each request should test one specific thing
•Assertions: Add comprehensive test scripts to every request
•Documentation: Use Postman descriptions for context
•CI Integration: Run Newman in CI pipeline for every PR
•Reports: Archive HTML reports for historical analysis
•Timeouts: Set reasonable timeout values for production APIs

References

•CI/CD Examples: See references/ci-cd-examples.md
•Advanced Patterns: See references/advanced-patterns.md
•Official Docs: https://learning.postman.com/docs/running-collections/using-newman-cli/command-line-integration-with-newman/