Command line integration with Newman

Newman is a command line Collection Runner for Postman. It allows you to 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.

Newman maintains feature parity with Postman and allows you to run collections the way they are executed inside the collection runner in the Postman app.

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

File uploads

Newman also supports file uploads. For this to work correctly, upload the file in the relative location specified in the collection. For instance, review this collection:

{"variables":[],"info":{"name":"file-upload","_postman_id":"9dbfcf22-fdf4-f328-e440-95dbd8e4cfbb","description":"A set of `POST` requests to upload files as form data fields","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json"},"item":[{"name":"Form data upload","event":[{"listen":"test","script":{"type":"text/javascript","exec":["var response = JSON.parse(responseBody).files[\"sample-file.txt\"];","","tests[\"Status code is 200\"] = responseCode.code === 200;","tests[\"File was uploaded correctly\"] = /^data:application\\/octet-stream;base64/.test(response);",""]}}],"request":{"url":"https://echo.getpostman.com/post","method":"POST","header":[],"body":{"mode":"formdata","formdata":[{"key":"file","type":"file","enabled":true,"src":"sample-file.txt"}]},"description":"Uploads a file as a form data field to `https://echo.getpostman.com/post` via a `POST` request."},"response":[]}]}

The file sample-file.txt must be present in the same directory as the collection. Run this collection as usual.

$ newman run file-upload.postman_collection.json

Library

Newman has been built as a library from the ground up. It can be extended and used in various ways. You can use it as follows in your Node.js code:

Custom reporters

Custom reporters come in handy when one would want to generate collection run reports that cater to very specific use cases.
For instance, logging out the response body when a request (or it's tests) fail, and so on.

Building custom reporters

A custom reporter is a Node module with a name of the form newman-reporter-<name>. To create a custom reporter:

Navigate to a directory of your choice, and create a blank npm package with npm init.

Add an index.js file, that exports a function of the following form:

function(emitter, reporterOptions, collectionRunOptions){// emitter is is an event emitter that triggers the following events: https://github.com/postmanlabs/newman#newmanrunevents// reporterOptions is an object of the reporter specific options. See usage examples below for more details.// collectionRunOptions is an object of all the collection run options: https://github.com/postmanlabs/newman#newmanrunoptions-object--callback-function--run-eventemitter};

Scoped reporter package names like @myorg/newman-reporter-<name> are also supported. You can find working reporter examples in working reporter examples.

Using custom reporters

In order to use the custom reporter, it will have to be installed first. For instance, to use the Newman teamcity reporter:

Install the reporter package.

npm install newman-reporter-teamcity

Note that the name of the package is of the form newman-reporter-<name>, where <name> is the actual name of the reporter. The installation should be global if Newman is installed globally, local otherwise. Run npm install ... with the -g flag for a global installation.

To use local (non-published) reporters, run the command npm install <path/to/local-reporter-directory> instead.

Use the installed reporter, either via the CLI, or programmatically. Here, the newman-reporter prefix is not required while specifying the reporter name in the options.

Scoped reporter packages must be specified with the scope prefix. For instance, if your package name is @myorg/newman-reporter-name, you must specify the reporter with @myorg/name.