# Newman — Run Postman API Collections from the Command Line

> Command-line collection runner for Postman that executes API tests in CI/CD pipelines with detailed reporting.

## Install

Save as a script file and run:

# Newman — Run Postman API Collections from the Command Line

## Quick Use
```bash
# Install globally
npm install -g newman

# Run a Postman collection file
newman run my-collection.json

# Run with an environment file and HTML report
newman run my-collection.json -e staging.json -r htmlextra

# Run from a Postman shared link
newman run https://api.getpostman.com/collections/<id>?apikey=<key>
```

## Introduction
Newman is the official command-line companion for Postman that lets you run Postman collections outside the Postman app. It executes every request in a collection, runs the associated pre-request scripts and test assertions, and reports pass/fail results to stdout or external reporters. This bridges the gap between interactive API design in Postman and automated regression testing in CI/CD pipelines.

## What Newman Does
- Executes Postman collections including requests, folders, pre-request scripts, and tests
- Supports environment and global variable files for multi-stage deployments
- Generates reports via built-in CLI reporter and community plugins (HTML, JUnit, JSON)
- Runs collections from local files, URLs, or the Postman API
- Returns non-zero exit codes on test failures for CI/CD gate integration

## Architecture Overview
Newman loads a Postman collection JSON file and iterates through its items in the defined order. For each request, it resolves variables from the environment and globals, executes pre-request scripts in a sandboxed JavaScript runtime, sends the HTTP request, and then runs the test scripts against the response. Results are accumulated and passed to one or more reporter plugins. The entire flow is orchestrated by the Postman Runtime SDK, which handles cookie jars, authentication helpers, and request chaining.

## Self-Hosting & Configuration
- Install globally via `npm install -g newman` or as a project dependency
- Export collections from Postman as JSON v2.1 files for version control
- Pass environment files with `-e env.json` and globals with `-g globals.json`
- Install reporter plugins: `npm install -g newman-reporter-htmlextra`
- Use `--delay-request` to add pauses between requests for rate-limited APIs

## Key Features
- Full Postman collection execution including scripts, tests, and variable resolution
- Extensible reporter system with community plugins for HTML, JUnit, Allure, and more
- Supports collection iteration with `--iteration-count` and CSV/JSON data files
- Works with Postman's authentication helpers: OAuth2, Bearer, Basic, Digest, AWS Sig v4
- Programmatic Node.js API for embedding collection runs in custom tooling

## Comparison with Similar Tools
- **Postman (GUI)** — interactive API design; Newman brings the same collections to the terminal and CI
- **Bruno** — open-source API client with its own CLI runner; Newman leverages the existing Postman ecosystem
- **Hoppscotch CLI** — lightweight open-source API testing; Newman supports richer scripting and auth helpers
- **Insomnia Inso** — CLI companion for Insomnia; Newman has a larger plugin ecosystem
- **HTTPie CLI** — excellent for ad-hoc requests; Newman runs scripted test suites with assertions

## FAQ
**Q: Can I run a single request from a collection?**
A: Yes. Use `--folder "folder name"` to run a specific folder, or filter via the programmatic API for individual requests.

**Q: How do I pass secrets without hardcoding them?**
A: Use environment files with placeholder values and override them via `--env-var "key=value"` from CI secrets.

**Q: Does Newman support file uploads in requests?**
A: Yes. Reference files in form-data fields using the `src` property in the collection JSON, and ensure the files are available at the specified paths.

**Q: How do I get JUnit reports for CI integration?**
A: Install `newman-reporter-junitfull` and run with `-r junitfull --reporter-junitfull-export results.xml`.

## Sources
- https://github.com/postmanlabs/newman
- https://learning.postman.com/docs/collections/using-newman-cli/command-line-integration-with-newman/

---
Source: https://tokrepo.com/en/workflows/a6df8fbf-41af-11f1-9bc6-00163e2b0d79
Author: Script Depot