Customize your collection runs using Newman's command line options. You can use options to set up a collection run, configure request delays and timeouts, specify SSL details, and more. After a run finishes, Newman exits with a status code that you can pass to your continuous integration (CI) tool.
To use options, add them to the newman run
command after you specify the collection file or URL:
newman run my-collection.json [options]
To view a list of available options for Newman, run the following command:
newman run -h
Option | Details |
---|---|
-h , --help | Output usage information. |
-v , --version | Output the version number. |
Option | Details |
---|---|
-e , --environment [file|URL] | Specify the file path or URL of environment variables. |
-g , --globals [file|URL] | Specify the file path or URL of global variables. |
-d , --iteration-data [file] | Specify the file path or URL of a data file (JSON or CSV) to use for iteration data. To learn more, see Data file example. |
-n , --iteration-count [number] | Specify the number of times for the collection to run. Use with the iteration data file. |
--folder [folderName] | Specify a folder to run requests from. You can specify more than one folder by using this option multiple times, specifying one folder for each time the option is used. |
--working-dir [path] | Set the path of the working directory to use while reading files with relative paths. Defaults to the current directory. |
--no-insecure-file-read | Prevents reading of files located outside of the working directory. |
--export-environment [path] | The path to the file where Newman will output the final environment variables file before completing a run. |
--export-globals [path] | The path to the file where Newman will output the final global variables file before completing a run. |
--export-collection [path] | The path to the file where Newman will output the final collection file before completing a run. |
--postman-api-key [api-key] | The Postman API key used to load resources using the Postman API. |
Option | Details |
---|---|
--delay-request [number] | Specify a delay (in milliseconds) between requests. |
--timeout [number] | Specify the time (in milliseconds) to wait for the entire collection run to complete execution. |
--timeout-request [number] | Specify the time (in milliseconds) to wait for requests to return a response. |
--timeout-script [number] | Specify the time (in milliseconds) to wait for scripts to complete execution. |
Option | Details |
---|---|
--ssl-client-cert [path] | The path to the public client certificate file. Use this option to make authenticated requests. |
--ssl-client-key [path] | Optionally, you can add the path to the private client key that verifies certificate ownership. |
--ssl-client-passphrase [passphrase] | Optionally, you can add a secret passphrase to protect the private client key. |
--ssl-client-cert-list [path] | The path to the configuration JSON file containing the SSL client certificate list. Use this option to set several SSL client certificates according to a URL or hostname. To learn more, see an example client certificate list. This option has a higher priority over the |
--ssl-extra-ca-certs [path] | The path to the file that has one or more trusted CA certificates in PEM format. You can use this option when you don't want to use the --insecure option. |
Option | Details |
---|---|
-r [reporter-name] , --reporters [reporter-name] | Generate a report about the current collection run. Specify one or more reporter names: cli (default when using Newman as a CLI), json , junit , progress , and emojitrain . Specify more than one reporter name as a comma-separated list, for example, -r cli,json . Learn more about using reporters with Newman. |
--bail [optionalModifiers] | Stops the collection run when a test script fails. Optionally, you can add modifiers to this option: |
--color [value] | Specify the color of the CLI output: on , off , or auto (default). |
--disable-unicode | Turn off Unicode text encoding. When supplied, all symbols in the output will be replaced by their plain text equivalents. |
-k , --insecure | Turn off SSL verification checks, and allow self-signed SSL certificates. |
-x , --suppress-exit-code | Specify whether to override the default exit code for the current run. Continue running tests even after a failure, but exit with code=0 . To learn more, see Exit status. |
--ignore-redirects | Turn off automatic following of 3XX redirect responses. |
--verbose | Show detailed information of the collection run and each request sent. |
--silent | Prevent Newman from showing CLI output. |
--cookie-jar [path] | Specify the file path for a JSON Cookie Jar. Uses tough-cookie to deserialize the file. |
--export-cookie-jar [path] | The path to the file where Newman will output the final cookie jar file before completing a run. Uses tough-cookie to serialize the file. |
--global-var "[global-variable-name]=[global-variable-value]" | Specifies global variables on the command line, in a key=value format. Multiple global variables can be added by using --global-var multiple times, for example, --global-var "color=blue" --global-var "pet=cat". |
--env-var "[environment-variable-name]=[environment-variable-value]" | Specifies environment variables in a key=value format on the command line. You can add multiple environment variables using --env-var multiple times, for example: --env-var "color=blue" --env-var "pet=cat" . |
By default, Newman exits with a status code of 0
if everything runs as expected without any exceptions. You can configure your continuous integration (CI) tool to pass or fail a build based on Newman's exit codes. To override the default exit code for the current run, use -x
or --suppress-exit-code
option.
Use the --bail
option to make Newman stop a run if it encounters a test case error with a status code of 1
. This status code can then be used by your CI tool or build system. For example:
newman run my-collection.json -e dev-environment.json --bail
To use a different set of data or variables for each iteration in a collection run, use the -d
option to specify a JSON or CSV file.
The following example shows a JSON data file for a run with two iterations, with each iteration using different values for a set of variables.
[{
"url": "http://127.0.0.1:5000",
"user_id": "1",
"id": "1",
"token_id": "123123",
},
{
"url": "http://postman-echo.com",
"user_id": "2",
"id": "2",
"token_id": "899899",
}]
To run the collection, use the -d
option and specify the data file. For example:
newman run my-collection.json -d data-file.json
The following example shows the same data formatted in a CSV file.
url, user_id, id, token_id
http://127.0.0.1:5000, 1, 1, 123123123
http://postman-echo.com, 2, 2, 899899
To learn more about formatting data files for collection runs, see Run collections using imported data.
Last modified: 2024/09/16