Newman

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

# Global install (recommended)
npm install -g newman
Project-specific
npm install --save-dev newman
Verify
newman --version

Basic Execution

# 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: 1. Collections → Click "..." → Export 2. Choose "Collection v2.1" (recommended) 3. Save as collection.json

Environment: 1. Environments → Click "..." → Export 2. Save as environment.json

2. Run Tests

# 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:

username,password
user1,pass1
user2,pass2

Run:

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

4. Reporters

# 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:

# 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:

// 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):

{
  "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

#!/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

# 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

# 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):

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

Test Script (in Postman):

// 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

# 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

# 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:

Environment variables not loading:

Timeout errors:

SSL errors:

Memory issues (large collections):

Best Practices

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

References

Installation

# Global install (recommended)
npm install -g newman
Project-specific
npm install --save-dev newman
Verify
newman --version

Basic Execution

# 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

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