## 1. Project Overview & Quickstart (postmanlabs/newman)

## File: README.md

[](https://www.postman.com/)
_Manage all of your organization's APIs in Postman, with the industry's most complete API development environment._

# newman <sub>_the cli companion for postman_</sub> [](https://github.com/postmanlabs/newman/actions/workflows/ci.yml) [](https://codecov.io/gh/postmanlabs/newman)

Newman is a command-line collection runner for Postman. It allows you to effortlessly run and test a Postman collection directly from the command-line. It is built with extensibility in mind so that you can easily integrate it with your continuous integration servers and build systems.


## Table of contents

1. [Getting Started](#getting-started)
2. [Usage](#usage)
    1. [Using Newman CLI](#using-newman-cli)
    2. [Using Newman as a Library](#using-newman-as-a-library)
    3. [Using Reporters with Newman](#using-reporters-with-newman)
3. [Command Line Options](#command-line-options)
    1. [newman-options](#newman-options)
    2. [newman-run](#newman-run-collection-file-source-options)
    3. [SSL](#ssl)
    4. [Configuring Proxy](#configuring-proxy)
4. [API Reference](#api-reference)
    1. [newman run](#newmanrunoptions-object--callback-function--run-eventemitter)
    2. [Run summary object](#newmanruncallbackerror-object--summary-object)
    3. [Events emitted during a collection run](#newmanrunevents)
5. [Reporters](#reporters)
    1. [Configuring Reporters](#configuring-reporters)
    2. [CLI Reporter](#cli-reporter)
    3. [JSON Reporter](#json-reporter)
    4. [JUnit Reporter](#junitxml-reporter)
    5. [HTML Reporter](#html-reporter)
6. [External Reporters](#external-reporters)
    1. [Using External Reporters](#using-external-reporters)
    2. [Creating Your Own Reporter](#creating-your-own-reporter)
7. [File Uploads](#file-uploads)
8. [Using Newman with the Postman API](#using-newman-with-the-postman-api)
9. [Using Newman in Docker](#using-newman-in-docker)
10. [Using Socks Proxy](#using-socks-proxy)
11. [Migration Guide](#migration-guide)
12. [Compatibility](#compatibility)
13. [Contributing](#contributing)
14. [Community Support](#community-support)
15. [License](#license)


## Getting started

To run Newman, ensure that you have Node.js >= v16. [Install Node.js via package manager](https://nodejs.org/en/download/package-manager/).

### Installation
The easiest way to install Newman is using NPM. If you have Node.js installed, it is most likely that you have NPM installed as well.

```console
$ npm install newman
```
This installs Newman globally on your system allowing you to run it from anywhere. If you want to install it locally, Just remove the `-g` flag.

#### Using Homebrew
Install Newman globally on your system using Homebrew.
```console
$ brew install newman
```

[back to top](#table-of-contents)

## Usage

### Using Newman CLI
The `newman run` command allows you to specify a collection to be run. You can easily export your Postman
Collection as a json file from the [Postman App](https://www.postman.com/downloads/) and run it using Newman.

```console
$ newman run examples/sample-collection.json
```

If your collection file is available as an URL (such as from our [Cloud API service](https://api.getpostman.com)),
Newman can fetch your file and run it as well.

```console
$ newman run https://www.getpostman.com/collections/631643-f695cab7-6878-eb55-7943-ad88e1ccfd65-JsLv
```

For the complete list of options, refer the [Command Line Options](#command-line-options) section below.



### Using Newman as a Library
Newman can be easily used within your JavaScript projects as a Node.js module. The entire set of Newman CLI functionality is available for programmatic use as well. The following example runs a collection by reading a JSON collection file stored on disk.

```javascript
const newman = require('newman'); // require newman in your project

// call newman.run to pass `options` object and wait for callback
newman.run({
    collection: require('./sample-collection.json'),
    reporters: 'cli'
}, function (err) {
	if (err) { throw err; }
    console.log('collection run complete!');
});
```

For the complete list of options, refer the [API Reference](#api-reference) section below.

### Using Reporters with Newman
Reporters provide information about the current collection run in a format that is easy to both: disseminate and assimilate.
Reporters can be configured using the `-r` or `--reporters` options. Inbuilt reporters in newman are: `cli`, `json`, `junit`, `progress` and `emojitrain`.

CLI reporter is enabled by default when Newman is used as a CLI, you do not need to specifically provide the same as part of reporters option. However, enabling one or more of the other reporters will result in no CLI output. Explicitly enable the CLI option in such a scenario. Check the example given below using the CLI and JSON reporters:

```console
$ newman run examples/sample-collection.json -r cli,json
```

For more details on [Reporters](#reporters) and writing your own [External Reporters](#external-reporters) refer to their corresponding sections below.

[back to top](#table-of-contents)

## Command Line Options

### `newman [options]`

- `-h`, `--help`
  Show command line help, including a list of options, and sample use cases.

- `-v`, `--version`
  Displays the current Newman version, taken from [package.json](https://github.com/postmanlabs/newman/blob/main/package.json)


### `newman run <collection-file-source> [options]`

- `-e `, `--environment `
  Specify an environment file path or URL. Environments provide a set of variables that one can use within collections.
  [Read More](https://learning.postman.com/docs/postman/variables-and-environments/managing-environments/)

- `-g `, `--globals `
  Specify the file path or URL for global variables. Global variables are similar to environment variables but have a lower
  precedence and can be overridden by environment variables having the same name.

- `-d `, `--iteration-data `
  Specify a data source file (JSON or CSV) to be used for iteration as a path to a file or as a URL.
  [Read More](https://learning.postman.com/docs/postman/collection-runs/working-with-data-files/)

- `-n <number>`, `--iteration-count <number>`
  Specifies the number of times the collection has to be run when used in conjunction with iteration data file.

- `--folder <name>`
  Run requests within a particular folder/folders or specific requests in a collection. Multiple folders or requests can be specified by using
  --folder multiple times, like so: --folder f1 --folder f2 --folder r1 --folder r2.


- `--working-dir `
  Set the path of the working directory to use while reading files with relative paths. Default to current directory.

- `--no-insecure-file-read`
  Prevents reading of files situated outside of the working directory.

- `--export-environment `
  The path to the file where Newman will output the final environment variables file before completing a run.

- `--export-globals `
  The path to the file where Newman will output the final global variables file before completing a run.

- `--export-collection `
  The path to the file where Newman will output the final collection file before completing a run.

- `--timeout <ms>`
  Specify the time (in milliseconds) to wait for the entire collection run to complete execution.

- `--timeout-request <ms>`
  Specify the time (in milliseconds) to wait for requests to return a response.

- `--timeout-script <ms>`
  Specify the time (in milliseconds) to wait for scripts to complete execution.

- `-k`, `--insecure`
  Disables SSL verification checks and allows self-signed SSL certificates.

- `--ignore-redirects`
  Prevents newman from automatically following 3XX redirect responses.

- `--delay-request`
  Specify the extent of delay between requests (milliseconds).

- `--cookie-jar `
  Specify the file path for a JSON Cookie Jar. Uses [`tough-cookie`](https://github.com/salesforce/tough-cookie) to deserialize the file.

- `--export-cookie-jar `
  The path to the file where Newman will output the final cookie jar file before completing a run. Uses `tough-cookie`'s serialize method.

- `--bail [optional modifiers]`
  Specify whether or not to stop a collection run on encountering the first test script error.
  Can optionally accept modifiers, currently include `folder` and `failure`.
  `folder` allows you to skip the entire collection run in case an invalid folder
  was specified using the `--folder` option or an error was encountered in general.
  On the failure of a test, `failure` would gracefully stop a collection run after completing the current test script.

- `-x`, `--suppress-exit-code`
  Specify whether or not to override the default exit code for the current run.

- `--color <value>`
  Enable or Disable colored CLI output. The color value can be any of the three: `on`, `off` or `auto`*(default)*.
  With `auto`, Newman attempts to automatically turn color on or off based on the color support in the terminal.
  This behaviour can be modified by using the `on` or `off` value accordingly.

- `--disable-unicode`
  Specify whether or not to force the unicode disable option. When supplied, all symbols in the output will be replaced
  by their plain text equivalents.

- `--global-var "<global-variable-name>=<global-variable-value>"`
  Allows the specification of global variables via the command line, in a key=value format. Multiple CLI global variables
  can be added by using `--global-var` multiple times, like so: `--global-var "foo=bar" --global-var "alpha=beta"`.

- `--env-var "<environment-variable-name>=<environment-variable-value>"`
  Allows the specification of environment variables via the command line, in a key=value format. Multiple CLI environment variables
  can be added by using `--env-var` multiple times, like so: `--env-var "foo=bar" --env-var "alpha=beta"`.

- `--verbose`
  Show detailed information of collection run and each request sent.

### SSL

#### Client Certificates

Client certificates are an alternative to traditional authentication mechanisms. These allow their users to make authenticated requests to a server, using a public certificate, and an optional private key that verifies certificate ownership. In some cases, the private key may also be protected by a secret passphrase, providing an additional layer of authentication security.

Newman supports SSL client certificates, via the following CLI options:

#### Using a single SSL client certificate
- `--ssl-client-cert`
The path to the public client certificate file.

- `--ssl-client-key`
The path to the private client key (optional).

- `--ssl-client-passphrase`
The secret passphrase used to protect the private client key (optional).


#### Using SSL client certificates configuration file (supports multiple certificates per run)

- `--ssl-client-cert-list`
The path to the SSL client certificate list configuration file (JSON format). See [examples/ssl-client-cert-list.json](https://github.com/postmanlabs/newman/blob/develop/examples/ssl-client-cert-list.json).

This option allows setting different SSL client certificate according to URL or hostname.
This option takes precedence over `--ssl-client-cert`, `--ssl-client-key` and `--ssl-client-passphrase` options. If there is no match for the URL in the list, these options are used as fallback.


#### Trusted CA

When it is not wanted to use the `--insecure` option, additionally trusted CA certificates can be provided like this:

- `--ssl-extra-ca-certs`
The path to the file, that holds one or more trusted CA certificates in PEM format

### Configuring Proxy

Newman can also be configured to work with proxy settings via the following environment variables:

 * `HTTP_PROXY` / `http_proxy`
 * `HTTPS_PROXY` / `https_proxy`
 * `NO_PROXY` / `no_proxy`

For more details on using these variables, [refer here](https://github.com/postmanlabs/postman-request/blob/master/README.md#controlling-proxy-behaviour-using-environment-variables).

[back to top](#table-of-contents)

## API Reference

### newman.run(options: _object_ , callback: _function_) => run: EventEmitter
The `run` function executes a collection and returns the run result to a callback function provided as parameter. The
return of the `newman.run` function is a run instance, which emits run events that can be listened to.

| Parameter | Description   |
|-----------|---------------|
| options                   | This is a required argument and it contains all information pertaining to running a collection._Required_Type: `object` |
| options.collection        | The collection is a required property of the `options` argument. It accepts an object representation of a Postman Collection which should resemble the schema mentioned at [https://schema.getpostman.com/](https://schema.getpostman.com/). The value of this property could also be an instance of Collection Object from the [Postman Collection SDK](https://github.com/postmanlabs/postman-collection).As `string`, one can provide a URL where the Collection JSON can be found (e.g. [Postman Cloud API](https://api.getpostman.com/) service) or path to a local JSON file._Required_Type: `object\|string` [PostmanCollection](https://github.com/postmanlabs/postman-collection/wiki#Collection) |
| options.environment       | One can optionally pass an environment file path or URL as `string` to this property and that will be used to read Postman Environment Variables from. This property also accepts environment variables as an `object`. Environment files exported from Postman App can be directly used here._Optional_Type: `object\|string` |
| options.envVar            | One can optionally pass environment variables as an array of key-value string object pairs. It will be used to read Postman Environment Variables as well as overwrite environment variables from `options.environments`. _Optional_Type: `array\|object` |
| options.globals           | Postman Global Variables can be optionally passed on to a collection run in form of path to a file or URL. It also accepts variables as an `object`._Optional_Type: `object\|string` |
| options.globalVar         | One can optionally pass global environment variables as an array of key-value string object pairs. It will be used to read Postman Global Environment Variables as well as overwrite global environment variables from `options.globals`. _Optional_Type: `array\|object` |
| options.iterationCount    | Specify the number of iterations to run on the collection. This is usually accompanied by providing a data file reference as `options.iterationData`._Optional_Type: `number`, Default value: `1` |
| options.iterationData     | Path to the JSON or CSV file or URL to be used as data source when running multiple iterations on a collection._Optional_Type: `string` |
| options.folder            | The name or ID of the folder/folders (ItemGroup) in the collection which would be run instead of the entire collection._Optional_Type: `string\|array` |
| options.workingDir        | The path of the directory to be used as working directory._Optional_Type: `string`, Default value: `Current Directory` |
| options.insecureFileRead  | Allow reading files outside of working directory._Optional_Type: `boolean`, Default value: `true` |
| options.timeout           | Specify the time (in milliseconds) to wait for the entire collection run to complete execution._Optional_Type: `number`, Default value: `Infinity` |
| options.timeoutRequest    | Specify the time (in milliseconds) to wait for requests to return a response._Optional_Type: `number`, Default value: `Infinity` |
| options.timeoutScript     | Specify the time (in milliseconds) to wait for scripts to return a response._Optional_Type: `number`, Default value: `Infinity` |
| options.delayRequest      | Specify the time (in milliseconds) to wait for between subsequent requests._Optional_Type: `number`, Default value: `0` |
| options.ignoreRedirects   | This specifies whether newman would automatically follow 3xx responses from servers._Optional_Type: `boolean`, Default value: `false` |
| options.insecure          | Disables SSL verification checks and allows self-signed SSL certificates._Optional_Type: `boolean`, Default value: `false` |
| options.bail              | A switch to specify whether or not to gracefully stop a collection run (after completing the current test script) on encountering the first error. Takes additional modifiers as arguments to specify whether to end the run with an error for invalid name or path.Available modifiers: `folder` and `failure`.eg. `bail : ['folder']`_Optional_Type: `boolean\|object`, Default value: `false` |
| options.suppressExitCode  | If present, allows overriding the default exit code from the current collection run, useful for bypassing collection result failures. Takes no arguments._Optional_Type: `boolean`, Default value: `false` |
| options.reporters         | Specify one reporter name as `string` or provide more than one reporter name as an `array`.Available reporters: `cli`, `json`, `junit`, `progress` and `emojitrain`._Optional_Type: `string\|array` |
| options.reporter          | Specify options for the reporter(s) declared in `options.reporters`.  e.g. `reporter : { junit : { export : './xmlResults.xml' } }`  e.g. `reporter : { html : { export : './htmlResults.html', template: './customTemplate.hbs' } }` _Optional_Type: `object` |
| options.color             | Enable or Disable colored CLI output.Available options: `on`, `off` and `auto`_Optional_Type: `string`, Default value: `auto` |
| options.sslClientCert     | The path to the public client certificate file._Optional_Type: `string` |
| options.sslClientKey      | The path to the private client key file._Optional_Type: `string` |
| options.sslClientPassphrase | The secret client key passphrase._Optional_Type: `string` |
| options.sslClientCertList | The path to the client certificate configuration list file. This option takes precedence over `sslClientCert`, `sslClientKey` and `sslClientPassphrase`. When there is no match in this configuration list, `sslClientCert` is used as fallback._Optional_Type: `string\|array` |
| options.sslExtraCaCerts   | The path to the file, that holds one or more trusted CA certificates in PEM format._Optional_Type: `string` |
| options.requestAgents     | Specify the custom requesting agents to be used when performing HTTP and HTTPS requests respectively. Example: [Using Socks Proxy](#using-socks-proxy)_Optional_Type: `object` |
| options.cookieJar     | One can optionally pass a CookieJar file path as `string` to this property and that will be deserialized using [`tough-cookie`](https://github.com/salesforce/tough-cookie). This property also accepts a `tough-cookie` CookieJar instance._Optional_Type: `object\|string` |
| options.newmanVersion     | The Newman version used for the collection run._This will be set by Newman_ |
| callback                  | Upon completion of the run, this callback is executed with the `error`, `summary` argument._Required_Type: `function` |

### newman.run~callback(error: _object_ , summary: _object_)

The `callback` parameter of the `newman.run` function receives two arguments: (1) `error` and (2) `summary`

| Argument  | Description   |
|-----------|---------------|
| error                     | In case newman faces an error during the run, the error is passed on to this argument of callback. By default, only fatal errors, such as the ones caused by any fault inside Newman is passed on to this argument. However, setting `abortOnError:true` or `abortOnFailure:true` as part of run options will cause newman to treat collection script syntax errors and test failures as fatal errors and be passed down here while stopping the run abruptly at that point.Type: `object` |
| summary                   | The run summary will contain information pertaining to the run.Type: `object` |
| summary.error             | An error object which if exists, contains an error message describing the message Type: `object` |
| summary.collection        | This object contains information about the collection being run, it's requests, and their associated pre-request scripts and tests.Type: `object` |
| summary.environment       | An object with environment variables used for the current run, and the usage status for each of those variables.Type: `object` |
| summary.globals           | This object holds details about the globals used within the collection run namespace.Type: `object` |
| summary.run               | A cumulative run summary object that provides information on .Type: `object` |
| summary.run.stats         | An object which provides details about the total, failed, and pending counts for pre request scripts, tests, assertions, requests, and more.Type: `object` |
| summary.run.failures      | An array of failure objects, with each element holding details, including the assertion that failed, and the request.Type: `array.<object>` |
| summary.run.executions    | This object contains information about each request, along with it's associated activities within the scope of the current collection run.Type: `array.<object>` |

### newman.run~events

Newman triggers a whole bunch of events during the run.

```javascript
newman.run({
    collection: require('./sample-collection.json'),
    iterationData: [{ "var": "data", "var_beta": "other_val" }],
    globals: {
        "id": "5bfde907-2a1e-8c5a-2246-4aff74b74236",
        "name": "test-env",
        "values": [
            {
                "key": "alpha",
                "value": "beta",
                "type": "text",
                "enabled": true
            }
        ],
        "timestamp": 1404119927461,
        "_postman_variable_scope": "globals",
        "_postman_exported_at": "2016-10-17T14:31:26.200Z",
        "_postman_exported_using": "Postman/4.8.0"
    },
    globalVar: [
        { "key":"glboalSecret", "value":"globalSecretValue" },
        { "key":"globalAnotherSecret", "value":`${process.env.GLOBAL_ANOTHER_SECRET}`}
    ],
    environment: {
        "id": "4454509f-00c3-fd32-d56c-ac1537f31415",
        "name": "test-env",
        "values": [
            {
                "key": "foo",
                "value": "bar",
                "type": "text",
                "enabled": true
            }
        ],
        "timestamp": 1404119927461,
        "_postman_variable_scope": "environment",
        "_postman_exported_at": "2016-10-17T14:26:34.940Z",
        "_postman_exported_using": "Postman/4.8.0"
    },
    envVar: [
        { "key":"secret", "value":"secretValue" },
        { "key":"anotherSecret", "value":`${process.env.ANOTHER_SECRET}`}
    ],
}).on('start', function (err, args) { // on start of run, log to console
    console.log('running a collection...');
}).on('done', function (err, summary) {
    if (err || summary.error) {
        console.error('collection run encountered an error.');
    }
    else {
        console.log('collection run completed.');
    }
});
```

All events receive two arguments (1) `error` and (2) `args`. The list below describes the properties of the second
argument object. [Learn more](https://github.com/postmanlabs/newman/wiki/Newman-Run-Events)

| Event     | Description   |
|-----------|---------------|
| start                     | The start of a collection run |
| beforeIteration           | Before an iteration commences |
| beforeItem                | Before an item execution begins (the set of prerequest->request->test) |
| beforePrerequest          | Before `prerequest` script is execution starts |
| prerequest                | After `prerequest` script execution completes |
| beforeRequest             | Before an HTTP request is sent |
| request                   | After response of the request is received |
| beforeTest                | Before `test` script is execution starts |
| test                      | After `test` script execution completes |
| beforeScript              | Before any script (of type `test` or `prerequest`) is executed |
| script                    | After any script (of type `test` or `prerequest`) is executed |
| item                      | When an item (the whole set of prerequest->request->test) completes |
| iteration                 | After an iteration completes |
| assertion                 | This event is triggered for every test assertion done within `test` scripts |
| console                   | Every time a `console` function is called from within any script, this event is propagated |
| exception                 | When any asynchronous error happen in `scripts` this event is triggered |
| beforeDone                | An event that is triggered prior to the completion of the run |
| done                      | This event is emitted when a collection run has completed, with or without errors |

[back to top](#table-of-contents)

## Reporters

### Configuring Reporters

- `-r <reporter-name>`, `--reporters <reporter-name>`
  Specify one reporter name as `string` or provide more than one reporter name as a comma separated list of reporter names. Available reporters are: `cli`, `json`, `junit`, `progress` and `emojitrain`.
  Spaces should **not** be used between reporter names / commas whilst specifying a comma separated list of reporters. For instance:
  :white_check_mark: `-r cli,json,junit`
  :x: `-r cli , json,junit`

- `--reporter-{{reporter-name}}-{{reporter-option}}`
  When multiple reporters are provided, if one needs to specifically override or provide an option to one reporter, this
  is achieved by prefixing the option with `--reporter-{{reporter-name}}-`.
  For example, `... --reporters cli,json --reporter-cli-silent` would silence the CLI reporter only.

- `--reporter-{{reporter-options}}`
  If more than one reporter accepts the same option name, they can be provided using the common reporter option syntax.
  
  For example, `... --reporters cli,json --reporter-silent` passes the `silent: true` option to both JSON and CLI
  reporter.

**Note:** Sample collection reports have been provided in [examples/reports](https://github.com/postmanlabs/newman/blob/develop/examples/reports).

### CLI Reporter
The built-in CLI reporter supports the following options, use them with appropriate argument switch prefix. For example, the
option `no-summary` can be passed as `--reporter-no-summary` or `--reporter-cli-no-summary`.

CLI reporter is enabled by default when Newman is used as a CLI, you do not need to specifically provide the same as part of `--reporters` option.
However, enabling one or more of the other reporters will result in no CLI output. Explicitly enable the CLI option in
such a scenario.

| CLI Option  | Description       |
|-------------|-------------------|
| `--reporter-cli-silent`         | The CLI reporter is internally disabled and you see no output to terminal. |

| `--reporter-cli-show-timestamps` | This prints the local time for each request made. |
| `--reporter-cli-no-summary`     | The statistical summary table is not shown. |
| `--reporter-cli-no-failures`    | This prevents the run failures from being separately printed. |
| `--reporter-cli-no-assertions`  | This turns off the output for request-wise assertions as they happen. |
| `--reporter-cli-no-success-assertions`  | This turns off the output for successful assertions as they happen. |
| `--reporter-cli-no-console`     | This turns off the output of `console.log` (and other console calls) from collection's scripts. |
| `--reporter-cli-no-banner`      | This turns off the `newman` banner shown at the beginning of each collection run. |

### JSON Reporter
The built-in JSON reporter is useful in producing a comprehensive output of the run summary. It takes the path to the
file where to write the report. The content of this file is exactly the same as the `summary` parameter sent to the callback
when Newman is used as a library.

To enable JSON reporter, provide `--reporters json` as a CLI option.

| CLI Option  | Description       |
|-------------|-------------------|
| `--reporter-json-export ` | Specify a path where the output JSON file will be written to disk. If not specified, the file will be written to `newman/` in the current working directory. If the specified path does not exist, it will be created. However, if the specified path is a pre-existing directory, the report will be generated in that directory. |

### JUNIT/XML Reporter
The built-in JUnit reporter can output a summary of the collection run to a JUnit compatible XML file. To enable the JUNIT reporter, provide
`--reporters junit` as a CLI option.

| CLI Option  | Description       |
|-------------|-------------------|
| `--reporter-junit-export ` | Specify a path where the output XML file will be written to disk. If not specified, the file will be written to `newman/` in the current working directory. If the specified path does not exist, it will be created. However, if the specified path is a pre-existing directory, the report will be generated in that directory. |

### HTML Reporter
An external reporter, maintained by Postman, which can be installed via `npm install newman-reporter-html`. This reporter was part of the Newman project but was separated out into its own project in V4.

The complete installation and usage guide is available at [newman-reporter-html](https://github.com/postmanlabs/newman-reporter-html#readme). Once the HTML reporter is installed you can provide `--reporters html` as a CLI option.

[back to top](#table-of-contents)

## External Reporters

### Using External Reporters
Newman also supports external reporters, provided that the reporter works with Newman's event sequence. Working examples of
how Newman reporters work can be found in [lib/reporters](https://github.com/postmanlabs/newman/tree/develop/lib/reporters).

For instance, to use the [Newman HTML Reporter](https://github.com/postmanlabs/newman-reporter-html):

- Install the reporter package. Note that the name of the package is of the form `newman-reporter-<name>`. The installation should be global if Newman is installed globally, local otherwise. (Remove `-g` flag from the command below for a local installation.)
```console
$ npm install newman-reporter-html
```

- Use the installed reporter, either via the CLI, or programmatic usage. Here, the `newman-reporter` prefix is **not** required while specifying the reporter name in the options.
```console
$ newman run /path/to/collection.json -r cli,html
```
```javascript
const newman = require('newman');

newman.run({
    collection: '/path/to/collection.json',
    reporters: ['cli', 'html']
}, process.exit);
```

#### Community Maintained Reporters

Several members of the Postman community have created custom reporters offering different option to output the data coming from Newman. Listed below is a selection of these but more can be found [here](https://www.npmjs.com/search?q=newman-reporter) on NPM.

Once the custom reporter NPM package has been installed either globally or locally, this can be then used with Newman in the following ways:

```console
$ newman run /path/to/collection.json -r htmlextra,csv
```

```javascript
const newman = require('newman');

newman.run({
    collection: '/path/to/collection.json',
    reporters: ['htmlextra', 'csv']
}, process.exit);
```

- [allure](https://github.com/allure-framework/allure-js/tree/master/packages/newman-reporter-allure) -
This reporter allow to create fully-featured allure reports that can allow you to have easy to understand HTML reports with features like historical data, link tests to the JIRA and all other benefits of using [allure framework](https://allurereport.org/).
- [htmlextra](https://github.com/DannyDainton/newman-reporter-htmlextra) -
This is an updated version of the standard HTML reporter containing a more in-depth data output and a few helpful extras
- [csv](https://github.com/matt-ball/newman-reporter-csv) -
This reporter creates a `csv` file containing the high level summary of the Collection run
- [json-summary](https://github.com/spenceclark/newman-reporter-json-summary) -
A Newman JSON Reporter that strips the results down to a minimum
- [teamcity](https://github.com/leafle/newman-reporter-teamcity) -
A reporter built to be used with the [Team City](https://www.jetbrains.com/teamcity/) CI server
- [testrail](https://github.com/billylam/newman-reporter-testrail) -
A reporter built for [Test Rail](https://www.gurock.com/testrail/), the test case management tool
- [statsd](https://github.com/gsorry/newman-reporter-statsd) -
This reporter can be used to send the Collection run data to `statsd` and used on time series analytic tools like [Grafana](https://grafana.com/)
- [confluence](https://github.com/OmbraDiFenice/newman-reporter-confluence) -
Confluence reporter for Newman that uploads a Newman report on a Confluence page
- [influxdb](https://github.com/vs4vijay/newman-reporter-influxdb) -
This reporter sends the test results information to InfluxDB which can be used from [Grafana](https://grafana.com/) to build dashboards

### Creating Your Own Reporter
A custom reporter is a Node module with a name of the form `newman-reporter-<name>`. To create a custom reporter:
1. Navigate to a directory of your choice, and create a blank npm package with `npm init`.
2. Add an `index.js` file, that exports a function of the following form:
```javascript
function CustomNewmanReporter (emitter, reporterOptions, collectionRunOptions) {
  // emitter is an event emitter that triggers the following events: https://github.com/postmanlabs/newman#newmanrunevents
  // reporterOptions is an object of the reporter specific options. See usage examples below for 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 the `npm pack` command to create a `.tgz` file. Once created, this can be installed using the `npm i newman-reporter-<name>.<version>.tgz` command.

Once you're happy with your reporter, it can be published to `npm` using `npm publish`. This will then be made available for other people to download.

Scoped reporter package names like `@myorg/newman-reporter-<name>` are also supported. Working reporter examples can be found in [lib/reporters](lib/reporters).

[back to top](#table-of-contents)

## File uploads

Newman also supports file uploads for request form data. The files must be present in the
current working directory. Your collection must also contain the filename in
the "src" attribute of the request.

In this collection, `sample-file.txt` should be present in the current working directory.
```json
{
    "info": {
        "name": "file-upload"
    },
    "item": [
        {
            "request": {
                "url": "https://postman-echo.com/post",
                "method": "POST",
                "body": {
                    "mode": "formdata",
                    "formdata": [
                        {
                            "key": "file",
                            "type": "file",
                            "enabled": true,
                            "src": "sample-file.txt"
                        }
                    ]
                }
            }
        }
    ]
}
```

```console
$ ls
file-upload.postman_collection.json  sample-file.txt

$ newman run file-upload.postman_collection.json
```

[back to top](#table-of-contents)

## Using Newman with the Postman API

1 [Generate an API key](https://learning.postman.com/docs/developer/intro-api/#generating-a-postman-api-key)
2 Fetch a list of your collections from: `https://api.getpostman.com/collections?apikey=$apiKey`
3 Get the collection link via it's `uid`: `https://api.getpostman.com/collections/$uid?apikey=$apiKey`
4 Obtain the environment URI from: `https://api.getpostman.com/environments?apikey=$apiKey`
5 Using the collection and environment URIs acquired in steps 3 and 4, run the collection as follows:
```console
$ newman run "https://api.getpostman.com/collections/$uid?apikey=$apiKey" \
    --environment "https://api.getpostman.com/environments/$uid?apikey=$apiKey"
```

[back to top](#table-of-contents)

## Using Newman in Docker
To use Newman in Docker check our [docker documentation](https://learning.postman.com/docs/postman/collection-runs/newman-with-docker/).

## Using Socks Proxy

When using Newman as a library, you can pass a custom HTTP(S) agent which will be used for making the requests. Here's an example of how to setup socks proxy using a custom agent.

```js
const newman = require('newman');
const SocksProxyAgent = require('socks-proxy-agent');
const requestAgent = new SocksProxyAgent({ host: 'localhost', port: '1080' });

newman.run({
    collection: require('./sample-collection.json'),
    requestAgents: {
        http: requestAgent, // agent used for HTTP requests
        https: requestAgent, // agent used for HTTPS requests
    }
}, function (err) {
    if (err) { throw err; }
    console.log('collection run complete!');
});
```

[back to top](#table-of-contents)

## Migration Guide

- [Newman v5 to v6 Migration Guide](MIGRATION.md)
- [Newman v5.x Documentation](https://github.com/postmanlabs/newman/blob/release/5.x/README.md)


## Compatibility

### NodeJS

|      Newman       |    Node    |
|:-----------------:|:----------:|
|       v3.x        |  >= v4.x   |
|       v4.x        |  >= v6.x   |
|       v5.x        |  >= v10.x  |
|       v6.x        |  >= v16.x  |

The current Node version compatibility can also be seen from the `engines.node` property in [package.json](https://github.com/postmanlabs/newman/blob/develop/package.json)

### File Encoding

Newman attempts to detect file encoding for files that are provided as
command line input. However, it mostly relies on NodeJS and the underlying
operating system to do the heavy lifting. Currently, `ASCII`, `UTF-8`, `UTF-16LE`
and `ISO-8859-1` are the only ones that are detection assisted.

[back to top](#table-of-contents)

## Contributing
Please take a moment to read our [contributing guide](.github/CONTRIBUTING.md) to learn about our development process.
Open an [issue](https://github.com/postmanlabs/newman/issues) first to discuss potential changes/additions.

## Community Support


If you are interested in talking to the Postman team and fellow Newman users, you can find us on our [Postman Community Forum](https://community.postman.com). Feel free to drop by and say hello. You'll find us posting about upcoming features and beta releases, answering technical support questions, and contemplating world peace.

Sign in using your Postman account to participate in the discussions and don't forget to take advantage of the [search bar](https://community.postman.com/search?q=newman) - the answer to your question might already be waiting for you! Don’t want to log in? Then lurk on the sidelines and absorb all the knowledge.


## License
This software is licensed under Apache-2.0. Copyright Postdot Technologies, Inc. See the [LICENSE.md](LICENSE.md) file for more information.

[](https://postman.com)

---

## File: docker/images/ubuntu/README.md

# newman:ubuntu

This image runs newman on node v16 on Ubuntu 22.04

Build the image,

```terminal
docker build -t postman/newman:ubuntu --build-arg NEWMAN_VERSION="full semver version" .
```

Or get it from [docker hub](https://registry.hub.docker.com/u/postman/newman:ubuntu/)

```terminal
docker pull postman/newman:ubuntu
```

Then run it

```terminal
docker --volume="/home/postman/collections:/etc/newman" -t postman/newman:ubuntu run JSONBlobCoreAPI.json.postman_collection -r json --reporter-json-export newman-report.json
```
For newman-docker to be able to use collections and environment files saved on the host machine, and to save reports generated by newman, a directory containing the collection and environment needs to be mounted on to the docker instance on run time, preferably at `/etc/newman`, which is the default working directory. If you mount to a different location, then
  - You can either pass the full path to your collection and environment files to newman. For instance, if you mount to `/etc/newman`,

```terminal
docker --volume="/home/postman/collection:/etc/newman" -t postman/newman:ubuntu run JSONBlobCoreAPI.json.postman_collection -r json --reporter-json-export newman-report.json
```
  - You can change the working directory while running the image to the location you mounted to, using the `-w` or `--workdir` flag.

```terminal
docker run --volume="/home/postman/collections:/etc/newman" -t postman/newman:ubuntu run JSONBlobCoreAPI.json.postman_collection -r json --reporter-json-export newman-report.json
```

In case you don't need to save newman's report to the host, and your collection is available online and it does not require any environment, then you can forgo mounting your collections directory, and directly pass the collection url to newman

```terminal
docker run -t postman/newman:ubuntu run https://www.getpostman.com/collections/8a0c9bc08f062d12dcda
```

---

## File: docker/images/alpine/README.md

# newman:alpine

This image runs newman on node v16 on Alpine

Build the image:

```terminal
docker build -t postman/newman:alpine --build-arg NEWMAN_VERSION="full semver version" .
```

Or get it from [Docker Hub](https://registry.hub.docker.com/u/postman/newman/):

```terminal
docker pull postman/newman:alpine
```

Then run it:

```terminal
docker --volume="/home/postman/collections:/etc/newman" -t postman/newman:alpine run JSONBlobCoreAPI.json.postman_collection -r json --reporter-json-export newman-report.json
```
For newman-docker to be able to use collections and environment files saved on the host machine, and to save reports generated by newman, a directory containing the collection and environment needs to be mounted on to the docker instance on run time, preferably at `/etc/newman`, which is the default working directory. If you mount to a different location, then:
  - You can pass the full path to your collection and environment files to newman. For instance, if you mount to `/etc/newman`,

```terminal
docker --volume="/home/postman/collection:/etc/newman" -t postman/newman:alpine run JSONBlobCoreAPI.json.postman_collection" -r json --reporter-json-export newman-report.json
```
  - You can change the working directory while running the image to the location you mounted to, using the `-w` or `--workdir` flag.

```terminal
docker run --volume="/home/postman/collections:/etc/newman" -t postman/newman:alpine run JSONBlobCoreAPI.json.postman_collection -r json --reporter-json-export newman-report.json
```

In case you don't need to save newman's report to the host, and your collection is available online and does not require any environment, then you can forgo mounting your collections directory and directly pass the collection URL to newman:

```terminal
docker run -t postman/newman:alpine run https://www.getpostman.com/collections/8a0c9bc08f062d12dcda
```

---

## File: docker/README.md

# newman-docker

This repository contains docker images for Newman.

[Newman](https://github.com/postmanlabs/newman) is a command-line collection runner for
[Postman](https://postman.com). It allows you to effortlessly run and test a
<a href="https://learning.postman.com/docs/sending-requests/intro-to-collections" target="_blank">Postman Collections<a/> directly from the
command-line. It is built with extensibility in mind so that you can easily integrate it with your continuous
integration servers and build systems.

**New to Docker?** Docker allows you to package an application with all of its dependencies into a standardised unit for
software development. Visit
[https://www.docker.com/whatisdocker](https://www.docker.com/whatisdocker) to read more about
how docker can drastically simplify development and deployment.

## There are two available Docker images for Newman
### postman/newman:alpine (lightweight):
   * [DockerHub](https://hub.docker.com/r/postman/newman/)
   * [Documentation](https://github.com/postmanlabs/newman/tree/develop/docker/images/alpine)

### postman/newman:ubuntu:
   * [DockerHub](https://hub.docker.com/r/postman/newman/)
   * [Documentation](https://github.com/postmanlabs/newman/tree/develop/docker/images/ubuntu)

## Using the docker image

The docker image for Newman is available for download from our docker hub. You must have Docker installed in your
system. Docker has extensive <a href="https://docs.docker.com/installation/" target="_blank">installation guideline for
popular operating systems</a>. Choose your operating system and follow the instructions.

> Ensure you that you have docker installed and running in your system before proceeding with next steps. A quick test
> to see if docker is installed correctly is to execute the command `docker run hello-world` and it should run without
> errors.

**Step 1:**

Pull the <a href="https://registry.hub.docker.com/u/postman/newman:ubuntu/" target="_blank">newman docker
image</a> from docker hub:

```terminal
docker pull postman/newman:ubuntu
```

**Step 2:**

Run newman commands on the image:

```terminal
docker run -t postman/newman:ubuntu run https://www.getpostman.com/collections/8a0c9bc08f062d12dcda
```

### Build the docker image from this repository


**Step 1:**

Clone this repository:

```terminal
git clone https://github.com/postmanlabs/newman.git
```

**Step 2:**

Build the image:

```terminal
docker build -t postman/newman:ubuntu --build-arg NEWMAN_VERSION="full semver version" .;
```

**Step 3:**

Run a collection using the newman image:

```terminal
docker run -t postman/newman:ubuntu run https://www.getpostman.com/collections/8a0c9bc08f062d12dcda
```


## Running local collection files

This docker image is designed to pick files from the `/etc/newman` directory within the image. You may mount the
directory of your collection files into that location and provide the file references in standard newman parameters.


```terminal
# Mount host collections folder ~/collections, onto /etc/newman on the docker image, so that newman
# has access to collections
docker run -v ~/collections:/etc/newman -t postman/newman:ubuntu run "HTTPBinNewmanTestNoEnv.json.postman_collection"
```

You are not required to mount a volume if you do not need to save newman report to the host, and your collection is
available online, unless your collection requires an environment(as environments cannot be passed as URLs).

To know more about mounting volumes, visit
[docker documentation on shared data volumes](https://docs.docker.com/userguide/dockervolumes/).


## Examples

Run a local collection, pass an environment to it, and save the JSON report on the host.

```terminal
docker run -v ~/collections:/etc/newman -t postman/newman:ubuntu \
    run "HTTPBinNewmanTest.json.postman_collection" \
    --environment="HTTPBinNewmanTestEnv.json.postman_environment" \
    --reporters="json,cli" --reporter-json-export="newman-results.json"
```

Run a remote collection, pass it a local environment, and save JUnit XML test report on the host

```terminal
docker run -v ~/collections:/etc/newman -t postman/newman:ubuntu \
    run https://www.getpostman.com/collections/8a0c9bc08f062d12dcda \
    --environment="HTTPBinNewmanTestEnv.json.postman_environment" \
    --reporters="junit,cli" --reporter-junit-export="newman-report.xml"
```

Use a script to run a collection and do something, for example deploy the build, if all the tests pass

```bash
#/bin/bash

# stop on first error
set -e;

function onExit {
    if [ "$?" != "0" ]; then
        echo "Tests failed";
        # build failed, don't deploy
        exit 1;
    else
        echo "Tests passed";
        # deploy build
    fi
}

# call onExit when the script exits
trap onExit EXIT;

docker run --entrypoint -t postman/newman:ubuntu run https://www.getpostman.com/collections/8a0c9bc08f062d12dcda --suppress-exit-code;
```

## Using Newman Docker images with custom reporters
Newman Docker images can also be used with custom Newman reporters, as follows:
```console
docker run -v "<collection-directory>:/etc/newman" --entrypoint /bin/  -c "npm i newman-reporter-<reporter-name>; newman run sample-collection.json -r <reporter-name>"
```

In the above example,
* `<collection-directory>` is the source directory for collections. This directory will also be used to write Newman reports.
* `` is a combination of the image name (and optional tag). For instance, `postman/newman:ubuntu` or `postman/newman:alpine`
* `<reporter-name>` is the reporter that has to be installed and loaded for the `newman run ...`

### Alpine
Note that the entrypoint here is `/bin/sh`, and **not** `/bin/bash`
```console
docker run -v "~/collections:/etc/newman" --entrypoint /bin/sh postman/newman:alpine -c "npm i newman-reporter-html; newman run sample-collection.json -r html"
```

### Ubuntu
```console
docker run -v "~/collections:/etc/newman" --entrypoint /bin/bash postman/newman:ubuntu -c "npm i newman-reporter-html; newman run sample-collection.json -r html"
```

## Node version
All official Newman Docker images will be shipped with the current Node LTS (Long Term Support) version. To learn more
about the Node release schedule, see https://github.com/nodejs/Release#release-schedule. More details about individual
Docker images can be found in their individual READMEs in this folder.

[](https://postman.com)

## 2. Official Technical Reference & Guides (postmanlabs/postmanlabs.github.io)

Parallax.js
===========

Simple parallax scrolling effect inspired by [Spotify.com](http://spotify.com/) implemented as a jQuery plugin  
[http://pixelcog.com/parallax.js/](http://pixelcog.com/parallax.js/)

## Installation

Download and include `parallax.min.js` in your document after including jQuery.

	<script src="https://ajax.googleapis.com/ajax/libs/jquery/1.11.0/jquery.min.js"></script>
    <script src="/path/to/parallax.js"></script>

## Usage

### Via data attributes

To easily add a parallax effect behind an element, add `data-parallax="scroll"` to the element you want to use, and specify an image with `data-image-src="/path/to/image.jpg"`.

	

### Via JavaScript

To call the parallax plugin manually, simply select your target element with jQuery and do the following:

	$('.parallax-window').parallax({imageSrc: '/path/to/image.jpg'});

### Notes

What parallax.js will do is create a fixed-position element for each parallax image at the start of the document's body. This mirror element will sit behind the other elements and match the position and dimensions of its target object.

Due to the nature of this implementation, you must ensure that these parallax objects and any layers below them are transparent so that you can see the parallax effect underneath.  Also, if there is no other content in this element, you will need to ensure that it has some fixed dimensions otherwise you won't see anything.

	.parallax-window {
		min-height: 400px;
		background: transparent;
	}

## Options

Options can be passed in via data attributes of JavaScript.  For data attributes, append the option name to `data-`, as in `data-image-src=""`.

Note that when specifying these options as html data-attributes, you should convert "camelCased" variable names into "dash-separated" lower-case names (e.g. `zIndex` would be `data-z-index=""`).



| Name | type | default | description |
| --- | --- | --- | --- |
| imageSrc | path | null | You must provide a path to the image you wish to apply to the parallax effect. |
| naturalWidth | number | auto | You can provide the natural width and natural height of an image to speed up loading and reduce error when determining the correct aspect ratio of the image. |
| naturalHeight | number | auto |  |
| position | xPos yPos | center center | This is analogous to the background-position css property. Specify coordinates as top, bottom, right, left, center, or pixel values (e.g. -10px 0px). The parallax image will be positioned as close to these values as possible while still covering the target element. |
| positionX | xPos | center |  |
| positionY | yPos | center |  |
| speed | float | 0.2 | The speed at which the parallax effect runs. 0.0 means the image will appear fixed in place, and 1.0 the image will flow at the same speed as the page content. |
| zIndex | number | -100 | The z-index value of the fixed-position elements.  By default these will be behind everything else on the page. |
| bleed | number | 0 | You can optionally set the parallax mirror element to extend a few pixels above and below the mirrored element.  This can hide slow or stuttering scroll events in certain browsers. |
| iosFix | boolean | true | iOS devices are incompatable with this plugin. If true, this option will set the parallax image as a static, centered background image whenever it detects an iOS user agent. Disable this if you wish to implement your own graceful degradation. |
| androidFix | boolean | true | If true, this option will set the parallax image as a static, centered background image whenever it detects an Android user agent. Disable this if you wish to enable the parallax scrolling effect on Android devices. |



## Contributing

If you have a pull request you would like to submit, please ensure that you update the minified version of the library along with your code changes.  This project uses [uglifyjs](https://www.npmjs.com/package/uglify-js) to perform code compression.

Please use the following command:

	uglifyjs parallax.js --comments -m -c -o parallax.min.js


LICENSE
=======

The MIT License (MIT)

Copyright (c) 2015 PixelCog Inc.

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.