Use Newman external and custom reporters

External and custom reporters are useful to generate collection run reports with Newman that cater to specific use cases, for example, logging out the response body when a request (or test) fails. You can use existing external reporters or build your own custom reporters.

Building custom reporters

A custom reporter is a Node.js module with a name of the form 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.

Using external and custom reporters

You must install the 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. You can view examples of how Newman reporters work.

The name of the package follows the format newman-reporter-<name>, where <name> is the actual 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 command npm install <path/to/local-reporter-directory>.

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

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.

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!');
});

The reporter options used in these examples are optional.