postman-newman-automation

Postman Newman Automation

Generates Newman CLI commands, shell scripts, and Jenkins pipeline configs for running Postman collections in automated environments.

Newman Basics

Newman is Postman's CLI runner. Install with:

npm install -g newman
# Optional HTML reporter:
npm install -g newman-reporter-htmlextra

Core Command Structure

newman run <collection> \
  --environment <env-file> \
  --globals <globals-file> \
  --iteration-count <n> \
  --iteration-data <csv-or-json> \
  --reporters <reporter-list> \
  --reporter-htmlextra-export <output.html> \
  --reporter-junit-export <results.xml> \
  --timeout-request <ms> \
  --delay-request <ms> \
  --bail \
  --color on

Step 1 — Gather Requirements

Ask or infer from context:

| Parameter | Question | |---|---| | Collection source | File path, URL, or Postman API UID? | | Environment | File path or inline variables? | | Reporter(s) | CLI only, HTML report, JUnit XML? | | Fail behavior | Stop on first failure (--bail) or run all? | | Iterations | Single run or data-driven (CSV/JSON)? | | Target | Local shell, Jenkins, or both? |

Step 2 — Generate Newman Command

Basic run (local)

newman run collection.json \
  --environment environment.json \
  --reporters cli,htmlextra \
  --reporter-htmlextra-export reports/report.html \
  --bail

Run from Postman API (by UID)

newman run "https://api.getpostman.com/collections/<UID>?apikey={{POSTMAN_API_KEY}}" \
  --environment environment.json \
  --reporters cli,junit \
  --reporter-junit-export results/junit.xml

Data-driven run (CSV)

newman run collection.json \
  --iteration-data test-data.csv \
  --iteration-count 5 \
  --reporters cli,htmlextra \
  --reporter-htmlextra-export reports/data-driven-report.html

With environment variable overrides (no file needed)

newman run collection.json \
  --env-var "base_url=https://staging.api.example.com" \
  --env-var "token=abc123" \
  --reporters cli

Step 3 — Shell Script

Generate a reusable shell script:

#!/bin/bash
set -e

# Configuration
COLLECTION="./collection.json"
ENVIRONMENT="./environment.json"
REPORT_DIR="./reports"
TIMESTAMP=$(date +"%Y%m%d_%H%M%S")

# Ensure report directory exists
mkdir -p "$REPORT_DIR"

echo "Running Newman collection: $COLLECTION"

newman run "$COLLECTION" \
  --environment "$ENVIRONMENT" \
  --reporters cli,htmlextra,junit \
  --reporter-htmlextra-export "$REPORT_DIR/report_$TIMESTAMP.html" \
  --reporter-junit-export "$REPORT_DIR/junit_$TIMESTAMP.xml" \
  --timeout-request 10000 \
  --bail

EXIT_CODE=$?

if [ $EXIT_CODE -eq 0 ]; then
  echo "✅ All tests passed."
else
  echo "❌ Tests failed. Check report: $REPORT_DIR/report_$TIMESTAMP.html"
  exit $EXIT_CODE
fi

Step 4 — Jenkins Pipeline

Declarative Jenkinsfile (preferred)

pipeline {
  agent any

  environment {
    POSTMAN_ENV = credentials('postman-environment-file') // Jenkins credential ID
  }

  stages {
    stage('Install Newman') {
      steps {
        sh 'npm install -g newman newman-reporter-htmlextra'
      }
    }

    stage('Run API Tests') {
      steps {
        sh """
          newman run collection.json \\
            --environment ${POSTMAN_ENV} \\
            --reporters cli,htmlextra,junit \\
            --reporter-htmlextra-export reports/report.html \\
            --reporter-junit-export reports/junit.xml \\
            --timeout-request 10000 \\
            --bail
        """
      }
    }
  }

  post {
    always {
      // Archive HTML report
      publishHTML(target: [
        allowMissing: false,
        alwaysLinkToLastBuild: true,
        keepAll: true,
        reportDir: 'reports',
        reportFiles: 'report.html',
        reportName: 'Newman API Test Report'
      ])
      // Archive JUnit results
      junit 'reports/junit.xml'
    }
    failure {
      echo 'API tests failed! Check the Newman report.'
    }
  }
}

Scripted Jenkinsfile (if declarative not available)

node {
  stage('Install Newman') {
    sh 'npm install -g newman newman-reporter-htmlextra'
  }

  stage('Run API Tests') {
    try {
      sh """
        newman run collection.json \\
          --environment environment.json \\
          --reporters cli,junit \\
          --reporter-junit-export reports/junit.xml \\
          --bail
      """
    } catch (err) {
      currentBuild.result = 'FAILURE'
      throw err
    } finally {
      junit 'reports/junit.xml'
    }
  }
}

Jenkins with environment variables (no credentials file)

environment {
  BASE_URL = 'https://api.example.com'
  API_TOKEN = credentials('api-token-secret')
}

steps {
  sh """
    newman run collection.json \\
      --env-var "base_url=${BASE_URL}" \\
      --env-var "token=${API_TOKEN}" \\
      --reporters cli,junit \\
      --reporter-junit-export results/junit.xml
  """
}

Step 5 — Reporter Reference

| Reporter | Install | Flag | Output | |---|---|---|---| | cli | built-in | --reporters cli | Terminal output | | junit | built-in | --reporters junit | JUnit XML (for Jenkins) | | htmlextra | npm i -g newman-reporter-htmlextra | --reporters htmlextra | Rich HTML report | | json | built-in | --reporters json | Raw JSON results |

Multiple reporters: --reporters cli,htmlextra,junit

Step 6 — Output

Provide based on what the user needs:

1. Newman command — ready to paste in terminal
2. Shell script (run-tests.sh) — with exit code handling
3. Jenkinsfile — declarative or scripted based on context
4. Setup notes — Node.js version requirement (≥14), npm install commands
5. Report locations — where output files will be written

Common Flags Quick Reference

| Flag | Purpose | |---|---| | --bail | Stop run on first test failure | | --timeout-request 5000 | Per-request timeout in ms | | --delay-request 200 | Delay between requests in ms | | --iteration-count 3 | Run collection N times | | --folder "Folder Name" | Run only a specific folder | | --env-var "k=v" | Inline environment variable | | --suppress-exit-code | Always exit 0 (don't fail CI) | | --verbose | Show full request/response details | | --color off | Disable color (useful for logs) |

After Completing the Newman Commands

Once the CLI command output is delivered, ask the user:

"Would you like me to generate API documentation for this design? (yes/no)"

If the user says yes:

• Check if the API Documentation skill is available in the installed skills list
• If the skill is available:
• Read and follow the instructions in the API Documentation skill
• Use the API design output above as the input
• Deliver the documentation as plain text output
• If the skill is NOT available:
• Inform the user: "It looks like the API Documentation skill isn't installed. You can install it and re-run.

If the user says no:

• End the task here