Install and run Newman

To get started using Newman, install Node.js, then Newman. Then you can run your collections.

Installing Newman

Newman is built on Node.js. To run Newman, make sure you have Node.js installed. Follow the steps to download Node for your CI's platform. (Some CI systems have configurations that pre-install Node.)

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

Install Newman from npm globally on your system, enabling you to run it from anywhere:

$ npm install -g newman

Updating Newman

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

Running Newman

The easiest way to run Newman is to run it with a collection. You can run any collection file from your file system.

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

You can export a collection to share as a file.

$ newman run mycollection.json

You can also pass a collection as a URL by sharing it.

If your collection uses environment variables, you must provide a set of environment variables used in your collection. Export the template from Postman and run them with the -e flag.

$ newman run https://www.postman.com/collections/cb208e7e64056f5294e5 -e dev_environment.json

Example collection with failing tests

→ Status Code Test
  GET https://postman-echo.com/status/404 [404 Not Found, 534B, 1551ms]
  1\. response code is 200

┌─────────────────────────┬──────────┬──────────┐
│                         │ executed │   failed │
├─────────────────────────┼──────────┼──────────┤
│              iterations │        1 │        0 │
├─────────────────────────┼──────────┼──────────┤
│                requests │        1 │        0 │
├─────────────────────────┼──────────┼──────────┤
│            test-scripts │        1 │        0 │
├─────────────────────────┼──────────┼──────────┤
│      prerequest-scripts │        0 │        0 │
├─────────────────────────┼──────────┼──────────┤
│              assertions │        1 │        1 │
├─────────────────────────┴──────────┴──────────┤
│ total run duration: 1917ms                    │
├───────────────────────────────────────────────┤
│ total data received: 14B (approx)             │
├───────────────────────────────────────────────┤
│ average response time: 1411ms                 │
└───────────────────────────────────────────────┘

  #  failure        detail

 1\.  AssertionFai…  response code is 200
                    at assertion:1 in test-script
                    inside "Status Code Test" of "Example Collection with
                    Failing Tests"

In your terminal, test-scripts refers to post-response scripts.

The results of all tests and requests can be exported into a file. You can learn more about Newman's built-in reporters.

Newman enables you to use all libraries and objects that Postman supports to run tests and pre-request scripts.

Options

Newman provides a rich set of options to customize a collection run. Learn more at Newman options.

By default, Newman exits with a status code of 0 if everything runs as expected with no exceptions. You can configure your continuous integration (CI) tools to respond to Newman's exit codes and correspondingly pass or fail a build. You can also use the --bail option to make Newman stop the run if it encounters a test case error with a status code of 1, which can then be picked up 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 also 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!');
});