Emits Newman CLI invocations, PowerShell or bash runners, and Jenkins/GitHub Actions stages for exported Postman collections, including CSV iteration data and JUnit/htmlextra reporters. Trigger on newman, postman cli, collection CI, or data-driven API suites. Do not use for Postman GUI collection authoring, the Postman CLI binary, Bruno/Insomnia clients, or Pact contract tests.
Emits Newman CLI invocations, PowerShell or bash runners, and Jenkins/GitHub Actions stages for exported Postman collections, including CSV iteration data and JUnit/htmlextra reporters. Trigger on newman, postman cli, collection CI, or data-driven API suites. Do not use for Postman GUI collection authoring, the Postman CLI binary, Bruno/Insomnia clients, or Pact contract tests.
Newman is the command-line collection runner for Postman. This skill generates ready-to-run Newman CLI commands, reusable shell scripts, and Jenkins pipeline configurations for automated API test execution in local or CI/CD environments. It covers basic runs, data-driven iterations, environment variable overrides, reporter selection, and CI integration patterns.
When to Use
Use this skill when the user needs to:
Run Postman collections from the command line (local or CI)
Automate API test suites with Newman
Integrate Postman tests into Jenkins (declarative or scripted pipelines)
Generate Newman shell scripts with exit-code handling and report archiving
Produce JUnit XML or HTML reports for CI consumption
Run data-driven tests using CSV or JSON iteration data
Override environment variables inline without an environment file
Trigger keywords: newman, postman cli, run postman collection, api test automation, jenkins postman, newman reporter, htmlextra, junit postman, postman ci/cd
Prerequisites
Node.js ≥ 14 installed and on PATH.
Newman installed globally:
npm install -g newman
Optional reporters (install only if the user requests HTML or custom reports):
npm install -g newman-reporter-htmlextra
Postman collection file (exported JSON) or a Postman API UID with a valid API key.
Environment file (optional) — exported from Postman as JSON.
On Windows (PowerShell), line continuations use backtick (`) instead of backslash (\). All bash examples below are for CI/Linux runners; see the PowerShell note in Step 2 for local Windows execution.
Procedure
Step 1 — Gather Requirements
Ask or infer from context before generating any command:
Replace <UID> with the collection UID and {{POSTMAN_API_KEY}} with a valid Postman API key (e.g., YOUR_POSTMAN_API_KEY). Never hardcode live keys in committed files — use environment variables or CI secret injection.
Provide the following based on what the user needs:
Newman command — ready to paste in terminal (bash or PowerShell as appropriate)
Shell script (run-tests.sh or run-tests.ps1) — with exit-code handling
Jenkinsfile — declarative or scripted based on context
Setup notes — Node.js version requirement (≥14), npm install commands
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 log files)
Pitfalls
Missing report directory — Newman does not create output directories. Always mkdir -p reports (Linux) or New-Item -ItemType Directory -Force -Path reports (PowerShell) before running.
htmlextra not installed — If --reporters htmlextra is used but newman-reporter-htmlextra is not installed globally, Newman will error. Install it first: npm install -g newman-reporter-htmlextra.
Windows line continuation — PowerShell uses backtick (`), not backslash (\). Mixing these causes parse errors. Bash examples are for Linux/macOS/CI runners only.
Postman API key exposure — Never commit apikey= in a repository. Use environment variables (POSTMAN_API_KEY) or CI secret injection (Jenkins credentials()).
--bail hides later failures — When --bail is set, only the first failure is reported. Remove it if the user wants a full failure summary.
set -e with exit-code capture — In the shell script, set -e will exit before the EXIT_CODE=$? line if Newman fails. Either remove set -e or capture the exit code with set +e before the Newman call and set -e after.
Node.js version too old — Newman requires Node.js ≥ 14. Older versions will fail with cryptic module errors. Verify with node --version.
Jenkins publishHTML plugin missing — The publishHTML step requires the HTML Publisher plugin. If it is not installed, the pipeline will fail at the post block. Use junit alone as a fallback.
CSV encoding — Iteration data CSV files must be UTF-8 encoded. Excel may export as UTF-8 with BOM, which can cause parsing issues. Re-save as plain UTF-8 if errors occur.
--suppress-exit-code in CI — Using this flag means Newman always exits 0, so CI will never fail on test failures. Only use it when you want to collect reports without gating the build.
Verification
After generating commands or scripts, verify correctness with these checks:
Jenkinsfile syntax validation (if pipeline generated):
Use Jenkins' Replay or jenkinsfile-runner, or validate via the Jenkins UI Pipeline Syntax > Declarative Directive Generator. At minimum, confirm Groovy compiles without syntax errors.
Exit code reflects test results:
newman run collection.json --reporters cli; echo "Exit code: $LASTEXITCODE"
Expected: 0 when all tests pass, non-zero when failures exist (unless --suppress-exit-code is used).
Related Skills
API Documentation — After generating Newman automation, ask the user: "Would you like me to generate API documentation for this collection?" If yes and the API Documentation skill is installed, follow that skill's instructions using the collection as input. If not installed, inform the user they can install it and re-run.
Limitations
Use this skill only when the task clearly matches Newman/Postman CLI automation.
Verify all generated commands, dependencies, credentials, and external service behavior before applying changes in production.
Do not treat examples as a substitute for environment-specific tests, security review, or user approval for destructive or costly actions.
No live secrets are included in this skill; all API keys and tokens are placeholders (e.g., YOUR_POSTMAN_API_KEY, YOUR_TOKEN).
