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.)

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, click Collections in the sidebar and select a collection. Then click Info in the right sidebar to view and copy the collection ID.

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

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.

Customize a collection run

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

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:

1
const newman = require('newman'); // require Newman in your project
2
3
// call newman.run to pass the `options` object and wait for callback
4
newman.run({
5
    collection: require('./sample-collection.json'),
6
    reporters: 'cli'
7
}, function (err) {
8
    if (err) { throw err; }
9
    console.log('collection run complete!');
10
});