Newman, Postman’s command-line runner, lets you automate your API tests in CI/CD pipelines, turning your Postman collections into reproducible, verifiable checks.
Let’s see Newman in action. Imagine you have a Postman collection named my-api-tests.json that verifies your user registration endpoint. You want to run this collection every time code is pushed to your main branch.
Here’s a simple package.json script that installs Newman and then runs your collection, outputting results to a JUnit XML file for CI integration:
{
"scripts": {
"test": "newman run my-api-tests.json --reporters cli junit --reporter-junit-export test-results.xml"
},
"devDependencies": {
"newman": "^5.3.0"
}
}
When this script runs in your CI environment (e.g., GitHub Actions, GitLab CI), npm install will pull down Newman, and then newman run will execute your tests. The --reporters cli junit flags tell Newman to show basic output on the command line and generate a JUnit XML report. The --reporter-junit-export test-results.xml flag specifies the output file name.
Your CI job would then look something like this:
name: API Tests
on: [push]
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Use Node.js 16.x
uses: actions/setup-node@v3
with:
node-version: '16.x'
- name: Install dependencies
run: npm ci
- name: Run Newman tests
run: npm test
- name: Upload test results
uses: actions/upload-artifact@v3
with:
name: test-results
path: test-results.xml
This setup ensures that every push to main triggers an automated test run, and the results are archived.
The core problem Newman solves is bridging the gap between manual API testing in Postman’s GUI and automated, consistent checks in a production pipeline. It takes your meticulously crafted Postman collections—requests, assertions, pre-request scripts, environment variables—and runs them headlessly. This means you get the power of Postman’s testing framework without needing a human to click buttons.
Internally, Newman parses your collection JSON. It then iterates through each request, executing any pre-request scripts (like generating dynamic data or setting headers). It sends the actual HTTP request to your API. Once the response comes back, it evaluates all the assertions defined in your Postman tests. If any assertion fails, Newman flags the entire collection run as failed, providing detailed error messages. It supports environments and global variables, allowing you to configure your tests for different stages (development, staging, production) directly from the command line or by referencing .postman_environment files.
You can control Newman’s execution with a rich set of command-line options. For instance, to run a collection with a specific environment file and set a global variable on the fly, you’d use:
newman run my-api-tests.json --environment staging.postman_environment.json --globals vars.json --folder "User API" --delay 1000
Here, --environment staging.postman_environment.json loads your staging configuration. --globals vars.json merges variables from a JSON file into Newman’s global scope. --folder "User API" limits the run to only tests within that specific folder in your collection. --delay 1000 introduces a 1-second pause between requests, which can be crucial for APIs with rate limits or to allow downstream services to catch up.
A powerful, often overlooked, feature is Newman’s ability to handle data files. If your collection needs to test various inputs, you can parameterize it using a CSV or JSON file. For example, to run your user registration tests with multiple sets of user data:
newman run user-registration.json --iteration-data users.csv
Newman will then execute the user-registration.json collection once for each row in users.csv, substituting the column headers as variable names within your requests and tests. This allows for comprehensive data-driven testing without duplicating collection logic.
The most impactful aspect for CI/CD is Newman’s reporter system. Beyond cli and junit, it supports html, json, emojitrain, and custom reporters. The junit reporter is the standard for most CI platforms, enabling them to parse test results, track pass/fail rates, and display detailed reports.
When you use --bail, Newman will stop executing the collection immediately after the first test failure. This is invaluable in CI because it prevents wasted compute time and provides faster feedback on what broke first.
The next logical step after integrating basic collection runs is to manage sensitive data like API keys or tokens.