***

title: Use Newman external and custom reporters
updated: 2024-09-16T00:00:00.000Z
max-toc-depth: 2
----------------

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:

   ```javascript
   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](#use-external-and-custom-reporters).

   <Info class="iconless-callout">
     Scoped reporter package names like `@myorg/newman-reporter-<name>` are also supported.
   </Info>

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](https://github.com/postmanlabs/newman-reporter-html), install the reporter package:

```bash
npm install newman-reporter-html
```

<Info class="iconless-callout">
  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](https://github.com/postmanlabs/newman/tree/develop/lib/reporters).
</Info>

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:

```bash
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:

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

Programmatically:

```js
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`.

<Info class="iconless-callout">
  The reporter options used in these examples are optional.
</Info>