Generating HTML Reports with Newman

Newman's default CLI output is fine for a developer running tests locally. It's terrible for everyone else: stakeholders, managers, on-call engineers triaging a 3 AM failure. They want a clickable, filterable report that shows what passed, what failed, and which assertion broke — without learning to read terminal output. Newman reporters are the answer. This lesson covers the htmlextra reporter for human-readable HTML, JUnit XML for CI dashboards, and the multi-reporter pattern that produces all formats from one run.

Why one CLI run isn't enough

A green CLI summary is invisible the moment the terminal closes. A failing assertion buried in 200 lines of CLI output is hard to find. And handing a non-developer a screenshot of → GET /users [200 OK, 5.6kB, 215ms] does nothing.

Reporters solve three different problems at once:

• Stakeholder-friendly summary. A polished HTML page with charts, request/response detail, and filter-by-failure that anyone can open in a browser.
• CI dashboard integration. JUnit XML that Jenkins, GitLab, CircleCI, and TeamCity all consume natively — failures show up in the build's test tab.
• Programmatic processing. JSON output so custom scripts can post results to Slack, parse trends, or feed a metrics dashboard.

You don't pick one — you generate them all from a single Newman invocation.

The reporter pipeline

One run, four outputs, each consumed by different audiences and tools. The cost is one extra flag per reporter; the benefit is everyone in the org sees the right shape of report.

htmlextra — the human-friendly reporter

newman-reporter-htmlextra is the community-maintained HTML reporter — significantly more featureful than the original html one. Install it once globally (or as a dev dependency in your repo):

npm install -g newman-reporter-htmlextra

Generate a report:

newman run collection.json -e env.json \
  -r htmlextra \
  --reporter-htmlextra-export ./reports/api-test-report.html

The -r htmlextra selects the reporter; --reporter-htmlextra-export says where to write the file. (Reporter-specific flags use the --reporter-<name>-<flag> pattern.)

Open reports/api-test-report.html in a browser. You get:

• A summary dashboard with totals (requests, assertions, pass/fail), run duration, and a pass/fail donut chart.
• A collection breakdown showing every folder and request, with per-request status and assertion count.
• A request detail view — click any request to see the full URL, headers, request body, response status, headers, body, and individual assertion results.
• A failed-only filter at the top — click "show only failed" and the noise disappears.
• Folder-level grouping that mirrors your collection structure.

It's a full report you can hand to anyone — share the HTML by Slack, attach to a Jira ticket, archive in a CI artifact bucket.

Multiple reporters in one run

Pass a comma-separated list to -r:

newman run collection.json -e env.json \
  -r cli,htmlextra,junit,json \
  --reporter-htmlextra-export ./reports/report.html \
  --reporter-junit-export ./reports/results.xml \
  --reporter-json-export ./reports/results.json

Now one Newman invocation produces:

• Live CLI output in the terminal.
• An HTML report at reports/report.html.
• JUnit XML at reports/results.xml.
• Raw JSON at reports/results.json.

Each reporter takes its own --reporter-<name>-<option> flags. Reporters that aren't told where to write to have sensible defaults, but explicit paths are clearer.

JUnit XML for CI dashboards

Most CI platforms speak JUnit XML natively. Generate it with:

newman run collection.json -r junit --reporter-junit-export results.xml

The XML lists every test (pm.test() block) with pass/fail and timing. CI ingests it and renders failures in the build's "Tests" tab — exactly the same as unit tests would.

For richer XML (with response bodies, assertion details), the community junitfull reporter is a drop-in upgrade:

npm install -g newman-reporter-junitfull
newman run collection.json -r junitfull --reporter-junitfull-export results.xml

Same XML format, more detail per test. Pick whichever your CI dashboard prefers.

JSON output for custom processing

The json reporter dumps the entire run as a single JSON file. You can then process it with anything — jq, a Node script, a Python script. A common use is sending Slack notifications on failure:

newman run collection.json -r json --reporter-json-export results.json
node scripts/notify-slack.js results.json

Or extracting the failed-test count with jq:

jq '.run.failures | length' results.json

For most teams the htmlextra + JUnit combo is enough; reach for JSON when you genuinely need bespoke processing.

Other reporters worth knowing

A non-exhaustive list of community reporters you can install via npm:

• teamcity — TeamCity-flavoured output.
• allure — feeds Allure dashboards.
• csv — single-row-per-test summary for spreadsheets.
• html — original HTML reporter, much simpler than htmlextra.
• slackmail — direct Slack notifications without a custom script.

Install with npm install -g newman-reporter-<name>, use with -r <name>. They all follow the same --reporter-<name>-<flag> convention.

Wiring reports into package.json

A clean shape that scales as the suite grows:

{
  "scripts": {
    "test:api": "newman run postman/collection.json -e postman/staging.json -r cli,htmlextra --reporter-htmlextra-export reports/api-report.html",
    "test:api:ci": "newman run postman/collection.json -e postman/staging.json -r cli,htmlextra,junit --reporter-htmlextra-export reports/api-report.html --reporter-junit-export reports/results.xml",
    "test:api:smoke": "newman run postman/collection.json --folder Smoke -e postman/staging.json -r cli --bail"
  },
  "devDependencies": {
    "newman": "^6.0.0",
    "newman-reporter-htmlextra": "^1.22.0"
  }
}

Three scripts: a developer-friendly local run, a CI-ready run that writes both HTML and JUnit, and a fast smoke variant for quick feedback. CI calls npm run test:api:ci; developers call npm run test:api and open the HTML.

Sharing reports — the practical handoffs

A few patterns that work in real teams:

• CI artifact. GitHub Actions and GitLab support uploading the reports/ folder as a build artifact. Failed runs include the HTML — anyone with access to the CI run can open it.
• Slack on failure. Use the JSON reporter and a small script to post a summary on failed runs only. Includes the failure count and a link to the artifact.
• Jira attachments. When raising a bug from a failed test, attach the HTML report to the ticket. The dev sees the exact request, response, and assertion that broke without rerunning anything.
• Trend dashboards. Post selected fields from the JSON reporter to a metrics service (Datadog, Grafana, Honeycomb). Track pass rate and average response time over time.

The htmlextra report is the "deliverable" most often shared with humans; the JUnit XML is the deliverable most often shared with machines.

⚠️ Common mistakes

• Letting the reports folder grow forever. Each CI run writes a new HTML; without cleanup, the artifact bucket fills. Either rotate (keep last 30) or upload as a CI artifact rather than committing.
• Running htmlextra without installing it. Newman exits with Could not find reporter if you -r htmlextra without npm install -g newman-reporter-htmlextra first. Install both Newman and the reporter on every CI worker.
• Treating the HTML as authoritative when it lies about timing. htmlextra's response times are wall-clock from Newman's perspective, including its own overhead. For real performance numbers, use a load-test tool — see the masterclass Response Time and Performance lesson.

🎯 Practice task

Generate a real report and inspect it. 20-25 minutes.

1. Install the reporter: npm install -g newman-reporter-htmlextra. Verify with newman --version (should still work) and a quick test run.
2. Make a reports/ folder next to your collection JSON. Run:

   Copy

   newman run "JSONPlaceholder API Tests.postman_collection.json" \
     -e JSONPlaceholder.postman_environment.json \
     -r cli,htmlextra \
     --reporter-htmlextra-export reports/api-report.html

3. Open reports/api-report.html in your browser. Click around — read the summary dashboard, the per-request breakdown, the assertion details. Try the "show failed only" filter (it'll be empty for a passing run).
4. Force a failure. In Postman, change one of the test assertions to expect 999. Re-export the collection. Re-run Newman with the same command. Refresh the HTML — there should now be a red row, and the "show failed only" filter narrows to it.
5. Click the failed row. The detail view should show the exact request, response, and the assertion message ("expected response to have status code 999 but got 200"). This is what you'd hand a developer to triage. Revert the test.
6. Add JUnit:

   Copy

   newman run "JSONPlaceholder API Tests.postman_collection.json" \
     -e JSONPlaceholder.postman_environment.json \
     -r cli,htmlextra,junit \
     --reporter-htmlextra-export reports/api-report.html \
     --reporter-junit-export reports/results.xml

   Open reports/results.xml in a text editor — see the <testsuite> and <testcase> elements. This is what CI dashboards consume.
7. Add a script to package.json. Initialise a project if you haven't (npm init -y), then add:

   Copy

   "scripts": {
     "test:api": "newman run \"JSONPlaceholder API Tests.postman_collection.json\" -e JSONPlaceholder.postman_environment.json -r cli,htmlextra --reporter-htmlextra-export reports/api-report.html"
   }

   Run npm run test:api. Same outputs, fewer keystrokes.
8. Stretch: install the JSON reporter is built in (no install needed) — add json to the reporter list and --reporter-json-export reports/results.json. Open the JSON file. Note the rich structure — it's the raw data the HTML report renders.

You can now produce a polished HTML report out of any Newman run. The next (and last) lesson of this chapter takes the same Newman command and wires it into a real CI/CD pipeline — GitHub Actions and Jenkins.