How to Automate API Testing with Newman: A Complete Step-by-Step Guide

If you’ve ever spent your Monday morning manually clicking through twenty different requests in Postman just to make sure your latest deploy didn’t break the API, you know the pain. It’s tedious, error-prone, and simply doesn’t scale. That’s why I started using Newman. If you’re wondering how to automate API testing with Newman, you’re in the right place.

Newman is essentially the command-line companion for Postman. It allows you to take the collections you’ve already built in the Postman UI and run them as scripts. This is the missing link that lets you move from ‘manual testing’ to ‘automated regression testing’ and eventually into a full CI/CD pipeline. While there are many best open source api testing tools available, Newman is the logical choice if you are already invested in the Postman ecosystem.

Prerequisites

Before we dive into the automation, make sure you have the following ready in your environment:

Node.js installed: Newman is a Node package, so you’ll need npm (Node Package Manager) on your machine.
A Postman Collection: You should have a collection with at least one request and some basic tests written in the “Tests” tab of Postman.
Exported JSON files: You’ll need your Collection JSON file and, if you use variables, your Environment JSON file.

Step 1: Installing Newman

Installing Newman is straightforward. I recommend installing it globally so you can run it from any directory in your terminal.

npm install -g newman

Once installed, you can verify it’s working by running newman -v. You should see the version number printed in your terminal. If you’re looking for alternatives to Postman entirely, I’ve put together a list of postman alternatives 2026 that might fit your workflow better, but for now, let’s stick with Newman.

Step 2: Running Your First Automated Test

To run your tests, you need the exported JSON files from Postman. Navigate to your collection in Postman, click the three dots (…) next to the collection name, and select Export. Save it as a JSON file.

Now, open your terminal and run the following command:

newman run my_collection.json

If you have an environment file (for things like {{base_url}}), include it using the -e flag:

newman run my_collection.json -e my_environment.json

As shown in the image below, you’ll see a clean table in your terminal showing which tests passed and which failed. This is a massive upgrade over manual clicking because you get an immediate, high-level overview of your API’s health.

Terminal output showing a successful Newman test run with a detailed results table

Step 3: Automating with HTML Reports

While terminal output is great for developers, it’s not great for stakeholders or audit trails. In my experience, the newman-reporter-htmlextra is a game-changer. It generates a beautiful, interactive HTML report.

First, install the reporter:

npm install -g newman-reporter-htmlextra

Then, run your tests with the reporter flag:

newman run my_collection.json -r cli,htmlextra

This will generate a folder containing a detailed HTML page. I usually commit these reports to a build artifact folder in my pipeline so I can track regressions over time.

Step 4: Integrating into CI/CD (GitHub Actions)

The real power of learning how to automate API testing with Newman comes when you integrate it into your pipeline. Here is a simplified GitHub Actions workflow file .github/workflows/api-tests.yml that I use for my projects:

name: API Regression Tests
on: [push]
jobs:
  test-api:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Install Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'
      - name: Install Newman
        run: npm install -g newman
      - name: Run API Tests
        run: newman run tests/my_collection.json -e tests/env.json

Pro Tips for Newman Automation

Use Environment Variables: Never hardcode URLs or API keys in your collection. Use environment files to switch between staging and production seamlessly.
Fail Fast: Use the --bail flag if you want Newman to stop executing the collection as soon as the first test fails. This saves time in CI pipelines.
Iterate with Data Files: If you need to test the same endpoint with 100 different user IDs, use a CSV or JSON data file with the -d flag.

Troubleshooting Common Issues

Issue: “Cannot find module ‘newman'”
This usually happens when the global npm path isn’t in your system’s PATH variable. Try running npm list -g to see where it’s installed or use npx newman run ... to execute it without a global install.

Issue: Environment variables are undefined
Double-check that you are passing the environment file with -e. Remember that Newman does not automatically sync with the Postman Cloud unless you use the API Key method (which I generally avoid for security reasons in public repos).

What’s Next?

Now that you’ve mastered the basics of how to automate API testing with Newman, you can explore more advanced automation patterns. I recommend looking into Contract Testing to ensure your frontend and backend stay in sync, or exploring other open source tools to see if a code-first approach (like Jest or PyTest) suits your team’s scaling needs better.