postman-collections

Overview

Postman is a popular GUI for HTTP API authoring; Newman is its official CLI for running the same collections headlessly in CI (newman-readme). The integration shape is two-step:

1. Author the collection in the Postman desktop app or import an OpenAPI spec → save as collection.json.
2. Run via newman run collection.json in CI; emit JUnit / JSON for downstream gating.

This skill covers the headless Newman side. Authoring inside Postman itself is a GUI workflow; the canonical reference is learning.postman.com and is out of scope for an automated agent.

When to use

• The repo contains *.postman_collection.json (or the team exports collections to collections/).
• API testing is the team's primary integration-testing layer and the team is already in the Postman ecosystem.
• A CI workflow needs newman run with structured reporter output for PR gating.

If the team uses TypeScript / JavaScript and prefers code-first authoring, evaluate tavern-testing (YAML) or karate-testing (Karate DSL) before adopting Postman/Newman - those keep tests next to source code rather than in a separate JSON artifact.

Install

npm install -g newman

(Per newman-readme.)

For per-project install (preferred for CI determinism):

npm install --save-dev newman

For the HTML reporter (external, separate install):

npm install --save-dev newman-reporter-htmlextra

Running

The canonical invocation (newman-readme):

newman run <collection-file-source> [options]

<collection-file-source> can be:

• A local file path: ./collections/orders.postman_collection.json.
• A Postman Cloud URL: https://api.getpostman.com/collections/....
• A public-link URL exported from Postman.

Key flags

Per newman-readme:

Worked example

newman run examples/sample-collection.json \
  -e environment.json \
  -d data.csv \
  -r cli,json,junit \
  --timeout-request 5000 \
  --reporter-junit-export results.xml \
  --reporter-json-export results.json \
  --bail folder

(Adapted from newman-readme.)

Reporters

The four built-in / canonical reporters per newman-readme:

JUnit is the canonical CI choice - every major CI platform ingests JUnit XML, surfaces test counts on the run summary, and lets the team click through to per-assertion failures.

For richer per-test details (which assertion in which folder failed with which response), pair junit with json and upload both as build artifacts.

Authoring tests inside the collection

Tests in Postman live in the Tests tab of each request and run after the response is received. The runtime is a sandboxed JavaScript environment with pm.* globals:

pm.test('status is 200', () => {
  pm.response.to.have.status(200);
});

pm.test('body is JSON with .order_id', () => {
  const json = pm.response.json();
  pm.expect(json).to.have.property('order_id').that.is.a('number');
});

pm.test('saves order_id for next request', () => {
  pm.collectionVariables.set('order_id', pm.response.json().order_id);
});

Each pm.test('...', () => {}) call becomes one entry in the JUnit XML / JSON output - name them clearly so the CI run summary is readable.

CI integration

# .github/workflows/api-tests.yml
name: api-tests

on:
  pull_request:
  push:
    branches: [main]

jobs:
  newman:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5

      - uses: actions/setup-node@v4
        with:
          node-version: '20'

      - run: npm ci

      - name: Newman run
        env:
          API_BASE_URL: ${{ secrets.STAGING_BASE_URL }}
          API_TOKEN:    ${{ secrets.API_TOKEN }}
        run: |
          npx newman run collections/orders.postman_collection.json \
            -e environments/staging.postman_environment.json \
            -r cli,json,junit \
            --reporter-junit-export results.xml \
            --reporter-json-export results.json \
            --bail failure \
            --timeout-request 10000

      - name: Upload reports
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: newman-reports
          path: |
            results.xml
            results.json
          retention-days: 14

      - name: Surface JUnit results in summary
        if: always()
        uses: dorny/test-reporter@v1
        with:
          name: API tests
          path: results.xml
          reporter: java-junit

if: always() on both upload + reporter steps is critical - when a collection fails, the reports are exactly when you need them.

Anti-patterns

Limitations

• No code-first authoring. Postman's authoring story is the GUI; the JSON file is the artifact. Teams that prefer code-first DSLs should evaluate karate-testing or tavern-testing.
• Sandboxed JS only. Tests can't import npm packages - the pm.* sandbox provides chai / lodash / cheerio pre-loaded; for richer logic, consider Karate or Tavern.
• No native parallelism inside one Newman run. Parallelize across CI matrix jobs, not within a single Newman process.

References

• newman-readme - install, newman run syntax, flags, reporters, example invocation.
• tavern-testing - YAML alternative.
• karate-testing - DSL alternative.
• schemathesis-fuzzing - property-based fuzzing as a complement (not replacement) for example-based collections.