Postman and Newman: A Comprehensive Guide to Command-Line API Testing

Picture a QA lead whose Postman collection passes every check, but only on her own laptop. Nobody runs it on commits, so when a renamed response field breaks the mobile app in production, the collection could have caught the problem much earlier but never got the chance to run.

Postman is an API platform for building and testing requests. Newman is its command-line runner, which executes exported collections, so the same API tests run in a terminal or a CI pipeline. This guide takes you from installation to a pipeline job that fails the build whenever an API endpoint breaks.

What Is Postman?

Postman is an API platform for building, sending, and testing HTTP requests. You can use the desktop app or Postman online, and the Postman API lets you manage collections programmatically. Five building blocks matter most when you test an API:

• Collections group HTTP requests, one folder per service.
• Environments store environment variables, such as base URLs and tokens.
• Test scripts run JavaScript after every response.
• A mock server returns saved example responses, so tests don't wait on a live backend.
• Postman can generate API documentation from a collection, supporting the whole API development cycle.

APIs now sit at the centre of most products. According to Postman's 2025 State of the API report, 82% of organisations have adopted some level of an API-first approach and 65% generate revenue from their APIs, so an untested endpoint is a liability. 

In search of a browser version of Postman, an online Postman-like tool or a Postman alternative? A web-based client will suffice for manual testing, but in the pipeline, you need a command-line runner such as Newman.

What Is Newman?

Newman is the command-line runner that executes exported Postman collections. It is a Node.js tool installed through npm, built for CI and build systems. Two facts decide whether it fits:

• It suits REST APIs, or any API REST service where each call returns a status code and a JSON body.
• Its main limit: Newman is not compatible with the collection v3 format used in Postman v12 and later, so Postman advises migrating to the Postman CLI.

New to REST? Start with a primer on what is REST API design, the REST API meaning, and SOAP vs rest api trade-offs, then come back for the testing side. New to the wider field? If you're asking what software test automation is, or what test automation is in software teams, start with our software testing automation guide and our explainer on regression testing.

What Is the Difference Between Postman and Newman?

The difference is authoring versus running. You write and debug requests in the Postman app, export the collection, and Newman executes it headlessly. Among API testing tools, this pair is the cheapest route to a regression gate.

Which runner fits your team? Stop at the first match:

1. Collections still in the older format, and a Node-friendly pipeline? Newman.
2. On Postman v12 with v3 collections? Postman CLI.
3. Just exploring or debugging an endpoint? The Postman app.

How to Install Postman and Newman

The format check in step 4 decides whether Newman suits you.

1. Open the official Postman download page. Then download Postman for Windows or Postman for Mac, and run the installer.
2. Confirm Node.js is present and install Newman:

node -v                  # confirm Node.js is installed
npm install -g newman    # install Newman globally
newman -v                # confirm the version prints

3. No Node.js on your build agent? Postman documents running Newman in Docker.
4. Check your collection format. Newman won't run v3 collections, and Postman's migration guide covers the move to the Postman CLI.

Create Your First Postman Collection

Postman Echo is a public testing service, so every step works without your own API.

Send a Test API Request

Create a collection, add a GET request to https://postman-echo.com/get?team=qa and press Send. Then read three things in the response:

• The status code.
• The JSON body.
• The response time.

Add Basic Test Scripts

Open Scripts > Post-response and add three pm.test assertions. Results show in the Test Results tab. Each checks one fact: 

pm.test("Status is 200", () => pm.response.to.have.status(200));

pm.test("Responds in under 800 ms", () => {
  pm.expect(pm.response.responseTime).to.be.below(800);
});

pm.test("Echoes the query parameter", () => {
  pm.expect(pm.response.json().args.team).to.eql("qa");
});

Without assertions, Newman has nothing to fail on. Set a time limit your API can meet.

Scripts also handle API chaining, where one response feeds the next request. A login request can pass its token on: 

• It reads pm.response.json().token and saves it with pm.environment.set.
• The next request sends that environment variable as a bearer header, which covers token authentication.

Export the Collection and Environment

Export both as JSON files and treat them differently. The collection travels to the repository, while the environment holds values that change per stage.

• Collection file: Commit it and review changes like code.
• Environment file: One per stage, with keys kept out of Git.

Run Command-Line API Tests with Newman

You run a collection with newman run, pointing it at the exported collection and, usually, an environment file.

Run Your First Newman Command

Point Newman at the two exported files.

newman run echo-collection.json -e staging.environment.json

Newman prints each request with its assertions, then a summary table. A failure block names the request, the assertion, and the actual value.

On Postman v12 with v3 collections? Install the Postman CLI with npm install -g postman-cli and sign in with an API key.

postman login --with-api-key $POSTMAN_API_KEY
postman collection run echo-collection.json -e staging.environment.json

Useful Newman Options

Six flags do most of the work:

• -e or --environment loads an environment file.
• -d or --iteration-data feeds a JSON or CSV data file.
• --bail stops the run when a test fails.
• --delay-request is a pause between requests, measured in milliseconds.
• --env-var "key=value" is a single variable that works well for secrets passed from CI.
• --cookie-jar is a JSON cookie file that handles cookie authentication.

There is one option to be wary of. -x (--suppress-exit-code) will ensure that Newman exits successfully even with errors, making your CI pipeline pass while your API crumbles.

Generate HTML Test Reports

Reporters control how Newman presents a run. Built-in ones are cli, json, junit, progress, and emojitrain, and none produces HTML, so add an external one such as htmlextra.

• List cli explicitly. Name any other reporter, and the default terminal output switches off.
• For build dashboards, -r cli,junit writes XML most CI tools can read.

npm install -g newman-reporter-htmlextra
newman run echo-collection.json -e staging.environment.json \
  -r cli,htmlextra --reporter-htmlextra-export reports/api.html

How to Add Newman to Your CI/CD Pipeline

Newman exits with 0 in case of a successful run; therefore, CI can either pass or fail the build based on this result. Postman documentation talks about using Jenkins and Travis CI, but we will use GitHub Actions. The pipeline has four stages:

1. Install Node.js.
2. Install Newman.
3. Run the collection.
4. Fail the job on a non-zero exit code.

name: api-tests
on: [push]
jobs:
  newman:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 24
      - run: npm install -g newman newman-reporter-htmlextra
      - run: >
          newman run collections/api.json
          -e environments/staging.json
          --env-var "apiKey=${{ secrets.API_KEY }}"
          -r cli,htmlextra
          --reporter-htmlextra-export reports/api.html
      - uses: actions/upload-artifact@v4
        if: always()
        with:
          name: api-report
          path: reports/

Two lines in this file matter most, and both are easy to lose when you copy the job:

• if: always() uploads the report even when the run fails, which is when you need it.
• The key comes from the CI secret store, never the repository.

Across our API testing engagements, the most common failure is not a broken endpoint. It is a Newman job that went red once, printed unreadable output, and got muted within the week. Our guide to test automation in CI/CD shows where these jobs fit.

Best Practices for Postman and Newman Testing

Most Newman suites fail slowly: A flat folder, a leaked key, a cascade of red requests nobody reads. These habits keep a collection readable, safe, and trustworthy as it grows.

• Keep tests independent: Chain API calls carefully and prepare state using pre-request scripts, so a bad login doesn't ruin ninety requests.
• Remove secrets before exporting: Store keys in CI secret storage and do not commit a real environment.
• Check what happy path doesn't: OWASP's API Security Top 10 lists the broken object-level authorization vulnerability as #1, and a collection that only expects a 200 response code won't ever find it.
• Test at different layers: Collections run against a service as part of integration tests, so leave unit testing in the codebase and use other tools for load testing, contract testing, and security testing.
• Select test automation tools by layer, not by ranking: Newman is one of the software test automation tools, while lists of the top test automation tools or the best test automation tools are a mix of API, UI, and codeless test automation tools.
• Use humans for assertions: AI for test automation and AI-based test automation can generate test cases, but AI in test automation still requires manually written assertions to be able to block the pipeline.

How Frugal Testing Helps You Automate API Testing Without the Overhead

As a QA services company, we help teams turn Postman collections into a working pipeline instead of a laptop-only habit. Our software QA services engineers review your collections, scope the endpoints that carry the most risk, and build the Newman job around them, so releases are checked automatically.

Every engagement ends with a handover rather than a dependency on us. You get reviewed collections, a pipeline job that fails builds on broken endpoints, readable reports, and a runbook your team can maintain. For critical endpoints, our regression testing services add a repeatable gate on every release.

What Our API Testing Engagement Looks Like

• Week 1: Scope endpoints by risk and review your existing collections.
• Week 2: Add assertions, environments, and chained requests; remove flaky tests.
• Week 3: Wire Newman into your pipeline with reports and secrets.
• Week 4: Hand over the runbook and reports; your team owns the pipeline.

Conclusion

Postman generates the collection, Newman executes it via command line, and CI uses the output to decide whether or not to ship. Together, these three tools make command-line API testing fast, cheap, and easy by doing what each of them does best while testing every new release the same way.

The only problem that we face is the v3 format of collections, which cannot be read by Newman. There is no way for anyone to know how long your collections are going to be supported, so do this before you update Postman.

People Also Ask (FAQs)

Q1. What is the difference between SOAP and REST APIs?

Ans: SOAP is a rigorous protocol using XML, while REST is an architectural style that employs standard HTTP requests and normally uses JSON. New web services usually adopt REST architecture.

Q2. What is software test automation?

Ans: Automated testing involves conducting tests automatically and validating them based on the expected results. Through automated testing, one is able to detect regressions without having to repeat the tests manually.

Q3. How does AI help in test automation?

Ans: The role of AI in testing is that it can generate test cases, make assertions, identify fragile test cases, and repair faulty scripts. Engineers evaluate AI output to determine failures.

Q4. Is Postman free, and is there a good alternative?

Ans: Postman has a free plan and paid team tiers, so check its pricing page for current limits. Insomnia, Bruno, and Hoppscotch are popular alternatives for API testing.

Q5. What are codeless test automation tools?

Ans: They help testers write automated tests using visual flows or recorded steps rather than script writing. They make simple scenarios easier to handle, but may be restrictive in complex pipelines.