newman-reporter-htmlextra

A Newman HTML reporter that has been extended to include the separation of the iteration runs so these are no longer aggregated together and also some additional handlebars helpers to enable users to create better custom templates.

This reporter comes with a dashboard style summary landing page and a set of different tabs which contain the detailed request information. There are also a few optional configuration flags available, to tailor the final report in a number of different ways.

This project will always continue to be fully maintained free of charge - If you're a fan of the project and it's something you get value from, it would be lovely to pay that forward in the means of a donation.

All donations are not kept by me, these are passed on to local charities. Other people need the help that these donations will provide more than I need coffee. 😍

Report Example

Interactive Example Report

To give you an idea of what the final report will look like, I've added a working example here for you to get your hands on:

• Standard Report Showing All Successful Requests

Install

The reporter works as a plugin with Newman so ensure that you have already installed that package globally, using npm install -g newman.

To globally install the htmlextra package:

npm install -g newman-reporter-htmlextra

To use htmlextra as a library, install the package as a dependency into a nodejs project's package.json file using:

npm install -S newman-reporter-htmlextra

To install node, newman and the htmlextra packages together, use this command to pull the Docker image:

docker pull dannydainton/htmlextra

Usage

In order to enable this reporter, specify htmlextra in Newman's -r or --reporters option. The following command will create a new report in the ./newman directory, if the directory does not exist, it will be created as part of the Newman run.

newman run collection.json -r htmlextra

CLI Options

With Newman CLI

With Newman as a Library

All the CLI functionality is available for programmatic use within a nodejs script.

Creating a very basic nodejs project can be done like this:

• Create a new directory using mkdir <new dir name>
• Move to the new directory using cd <new dir name>
• Create a package.json file using npm init -y
• Install the required node modules using npm i -S newman newman-reporter-htmlextra
• Create a new <filename>.js file and add the script below which contains the current list of reporter options
• Add your collection.json file reference to the script and run using node <filename>.js

Once the node script has run, the report will be created in the default ./newman directory. A new save location can be specified using the export flag.

To enable the functionality of a given feature, uncomment any of the options within the htmlextra object.

const newman = require('newman');

newman.run({
    collection: './pathToFile/collection.json', // Collection URL from a public link or the Postman API can also be used
    reporters: ['htmlextra'],
    iterationCount: 1,
    reporter: {
        htmlextra: {
            // export: './report.html',
            // template: './template.hbs'
            // logs: true,
            // showOnlyFails: true,
            // noSyntaxHighlighting: true,
            // testPaging: true,
            // browserTitle: "My Newman report",
            // title: "My Newman Report",
            // titleSize: 4,
            // omitHeaders: true,
            // skipHeaders: "Authorization",
            // omitRequestBodies: true,
            // omitResponseBodies: true,
            // hideRequestBody: ["Login"],
            // hideResponseBody: ["Auth Request"],
            // showEnvironmentData: true,
            // skipEnvironmentVars: ["API_KEY"],
            // showGlobalData: true,
            // skipGlobalVars: ["API_TOKEN"],
            // skipSensitiveData: true,
            // showMarkdownLinks: true,
            // showFolderDescription: true,
            // timezone: "Australia/Sydney",
            // skipFolders: "folder name with space,folderWithoutSpace",
            // skipRequests: "request name with space,requestNameWithoutSpace",
            // displayProgressBar: true
        }
    }
});

Running The Reporter With Docker

A docker image dannydainton/htmlextra has been created for the reporter and can be found on Docker Hub

Basic Usage

Using this command, it will pull down the image and run the Postman Collection with Newman. Once the run has completed it will create a new report file in the /newman dir.

docker run -t -v $(pwd):/etc/newman dannydainton/htmlextra run collection.json -r htmlextra

Using an environment file during the Newman run:

docker run -t -v $(pwd):/etc/newman dannydainton/htmlextra run collection.json -e environment.json -r htmlextra

Using either the Shared Collection link from the Postman App or using the Postman API Link to the files:

docker run -t -v $(pwd):/etc/newman dannydainton/htmlextra run <URL to Collection> -e <URL to Environment> -r htmlextra

Each of these command can be used with the different CLI flags to create the final report that you require.

Compatibility

Contributing To The Project

This is an open soruce project and PRs for improvements and bug fixes are ALWAYS welcome!!

The easiest way to contribute is to locally pull down the repository code, make your awesome changes and submit a PR - I've listed a few steps here to hopefully make this a simple process:

1. Clone the newman-reporter-htmlextra repository
2. Create a New Branch
3. Run npm i
4. Run npm run local-dev to globally link the project with Newman
5. Make your changes to the reporter
6. Run npx newman run collection_file.json -r htmlextra to create a new report and see your changes in the output
7. Submit a PR for review

Project Contributors

I would be lying if I said that I've created this reporter all on my own, I need to say a massive Thank You! to the following folks for helping make htmlextra even better:

• @codenirvana
• @ldz-w
• @sam-viz
• @bassie1995
• @praveendvd
• @Prachi481992
• @sweetnoods
• @manoelagonzaga
• @stickpin
• @dersvenhesse
• @b-pagis
• @IceBjerg
• @w4dd325

A huge amount of love and appreciation also goes to Bruce The Legend, for creating the awesome project logo ♥️

License

This software is licensed under Apache-2.0. See the LICENSE.md file for more information.

Special mention

This work have been hugely inspired and copied several aspects of the great work done by Martijn Vander Vlag to create the newman-reporter-htmlfull package. Check out that package too, this contains many of the same aggregation features.

It was also brought together by reviewing the feature requests, from the official Postman HTML reporter and implementing them into this reporter.