# 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:

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