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

• 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

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

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