Use Newman external and custom reporters

Generate reports for your collection runs in Newman with custom and external reporters. You can generate reports for specific use cases, for example, logging the response body when a request or test fails. Use existing external reporters to generate reports, or build your own custom reporters.

Build custom reporters

A custom reporter is a Node.js module with a name in the format newman-reporter-<name>.

To create a custom reporter, do the following:

1. In the directory of your choice, create a blank npm package with npm init.

2. Add an index.js file that exports a function in the following format:

   function CustomNewmanReporter (emitter, reporterOptions, collectionRunOptions) {
     // emitter is is an event emitter that triggers the following events: https://github.com/postmanlabs/newman#newmanrunevents
     // reporterOptions is an object of the reporter specific options. The usage examples below have more details.
     // collectionRunOptions is an object of all the collection run options: https://github.com/postmanlabs/newman#newmanrunoptions-object--callback-function--run-eventemitter
   }
   module.exports = CustomNewmanReporter
   

3. To use your reporter locally, use npm pack to create a TGZ file. This can be installed using npm i -g newman-reporter-<name>.<version>.tgz. Learn more about using custom reporters.

   Scoped reporter package names like @myorg/newman-reporter-<name> are also supported.

4. (Optional) You can publish your reporter to npm using npm publish.

Use external and custom reporters

You must install an external or custom reporter to use it. For example, to use the Newman HTML reporter, install the reporter package:

npm install newman-reporter-html

You can use external reporters with Newman if the reporter works with Newman's event sequence. To learn more, view examples of how Newman reporters work.

The name of the package follows the format newman-reporter-<name>, where <name> is the name of the reporter. The installation is global if Newman is installed globally, and local otherwise. Run npm install ... with the -g flag for a global installation.

To use local (non-published) reporters, run the following command:

npm install <path/to/local-reporter-directory>

You can use the installed reporter either with the command-line tool or programmatically. In either case, the newman-reporter prefix isn't required while specifying the reporter name in the options.

On the command line:

newman run /path/to/collection.json -r myreporter --reporter-myreporter-<option-name> <option-value> # The option is optional

Programmatically:

var newman = require('newman');

newman.run({
   collection: '/path/to/collection.json',
   reporters: 'myreporter',
   reporter: {
     myreporter: {
       'option-name': 'option-value' // this is optional
     }
   }
}, function (err, summary) {
  if (err) { throw err; }
  console.info('collection run complete!');
});

Scoped reporter packages must be specified with the scope prefix. For example, if your package name is @myorg/newman-reporter-name, you must specify the reporter with @myorg/name.

The reporter options used in these examples are optional.