newman
v4.0.0-alpha.1
Command-line companion utility for Postman
732.9K/weekUpdated 3 weeks agoApache-2.0Unpacked: 616.4 KB
Published by Postman Labs
npm install newman
_Manage all of your organization's APIs in Postman, with the industry's most complete API development environment._
newman _the cli companion for postman_  
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
2. Usage
1. Using Newman CLI
2. Using Newman as a Library
3. Using Reporters with Newman
3. Command Line Options
1. newman-options
2. newman-run
3. SSL
4. Configuring Proxy
4. API Reference
1. newman run
2. Run summary object
3. Events emitted during a collection run
5. Reporters
1. Configuring Reporters
2. CLI Reporter
3. JSON Reporter
4. JUnit Reporter
5. HTML Reporter
6. External Reporters
1. Using External Reporters
2. Creating Your Own Reporter
7. File Uploads
8. Using Newman with the Postman API
9. Using Newman in Docker
10. Using Socks Proxy
11. Migration Guide
12. Compatibility
13. Contributing
14. Community Support
15. License
Getting started
To run Newman, ensure that you have Node.js >= v16. Install Node.js via package manager.
$3
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 -g 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 flag.
#### Using Homebrew
Install Newman globally on your system using Homebrew.
`console`
$ brew install newman
Usage
$3
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 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),
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 section below.
$3
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 section below.
$3
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 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 and writing your own External Reporters refer to their corresponding sections below.
Command Line Options
$3
-
, --help
Show command line help, including a list of options, and sample use cases.-
, --version
Displays the current Newman version, taken from package.json
$3
-
, --environment
Specify an environment file path or URL. Environments provide a set of variables that one can use within collections.
Read More-
, --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.-
, --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-
, --iteration-count
Specifies the number of times the collection has to be run when used in conjunction with iteration data file.-
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.
-
Set the path of the working directory to use while reading files with relative paths. Default to current directory.-
Prevents reading of files situated outside of the working directory.-
The path to the file where Newman will output the final environment variables file before completing a run.-
The path to the file where Newman will output the final global variables file before completing a run.-
The path to the file where Newman will output the final collection file before completing a run.-
Specify the time (in milliseconds) to wait for the entire collection run to complete execution.-
Specify the time (in milliseconds) to wait for requests to return a response.-
Specify the time (in milliseconds) to wait for scripts to complete execution.-
, --insecure
Disables SSL verification checks and allows self-signed SSL certificates.-
Prevents newman from automatically following 3XX redirect responses.-
Specify the extent of delay between requests (milliseconds).-
Specify the file path for a JSON Cookie Jar. Uses 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 '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 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.-
Enable or Disable colored CLI output. The color value can be any of the three: , 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.-
Allows the specification of global variables via the command line, in a key=value format. Multiple CLI global variables
can be added by using multiple times, like so: --global-var "foo=bar" --global-var "alpha=beta".-
--env-var "
Allows the specification of environment variables via the command line, in a key=value format. Multiple CLI environment variables
can be added by using multiple times, like so: --env-var "foo=bar" --env-var "alpha=beta".-
--verbose
Show detailed information of collection run and each request sent.$3
#### 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
-
The path to the public client certificate file.-
The path to the private client key (optional).-
The secret passphrase used to protect the private client key (optional).
#### Using SSL client certificates configuration file (supports multiple certificates per run)
-
The path to the SSL client certificate list configuration file (JSON format). See 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-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$3
Newman can also be configured to work with proxy settings via the following environment variables:
*
/ http_proxy
* / https_proxy
* / no_proxyFor more details on using these variables, refer here.
API Reference
$3
The 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/. The value of this property could also be an instance of Collection Object from the Postman Collection SDK.
As string, one can provide a URL where the Collection JSON can be found (e.g. Postman Cloud API service) or path to a local JSON file.
_Required_
Type: object\|string PostmanCollection |
| 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: , 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: , 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
_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. 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 |$3
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
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.