Install and run Newman

Newman is built on Node.js. To get started, first install Node.js, then install Newman. After installing Newman, you can run your Postman collections from the command line. Collections can be run as an exported JSON file or by passing the URL of the collection to Newman.

Install Newman

Before installing Newman, make sure you've installed Node.js v16 or later. Follow the steps to download Node.js for your continuous integration (CI) system. (Some CI systems have configurations that pre-install Node.js.)

If you're using an earlier version of Newman, learn more about Node.js version compatibility with Newman.

Install Newman globally so you can run it anywhere on your system. Use the following command:

npm install -g newman

Update Newman

If you've already installed Newman, you can upgrade to a later version. Learn more about upgrading to a later version of Newman.

Run a collection with Newman

To run a collection with Newman, first export the collection as a JSON file. Then run the collection from your file system with the following command:

newman run my-collection.json

Run a collection with a URL

You can run a collection by passing the URL of the collection to Newman. In the following example, substitute the <collection-id> with the ID of the collection you want to run:

newman run https://www.postman.com/collections/<collection-id>

You can find the collection ID in Postman. First, select Collections in the sidebar and select a collection. Then select the information icon in the right sidebar to view and copy the collection ID.

If your collection URL isn't publicly available, use the Postman API to run your collection with Newman.

Run a collection with an environment

If your collection uses environment variables, you must provide the environment used in your collection. Export the environment from Postman and include it with the -e flag. For example:

newman run my-collection.json -e dev-environment.json

Newman doesn't support OAuth 2.0 authentication grant types that require user interaction, such as an authorization code, to manually generate an access token. To learn more, see OAuth 2.0 overview.

Example collection run with failing tests

The following example shows the results of a collection run in Newman with failing tests.

In the output, test-scripts refers to post-response scripts. Newman supports the same libraries and objects as Postman for pre-request and post-response scripts.

You can export the run results, including all requests and tests, to a file using Newman's built-in reporters.

Customize a collection run

Newman provides a rich set of options for customizing a collection run. To learn more, see Customize a collection run using Newman command options.

Using Newman with CI/CD

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.

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.

Using Newman as a Node.js library

You can use Newman within your JavaScript projects as a Node.js module. The entire set of Newman CLI functionality is available to use programmatically. The following example runs a collection by reading a JSON collection stored in your file system:

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

// call newman.run to pass the `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 newman.run options, see API Reference on GitHub.