API Testing with Postman: Part 3

In the last couple of posts, we discussed how to set up and execute various commands of the Postman API testing tool.

In this part, we’ll discuss the Newman CLI tool, which is helpful for developers and testers when running API calls/collection in the command line.

For basic execution, please refer to Part 1 and Part 2 of this blog series.

Introduction to Newman

Newman is a command line collection runner for the Postman API testing tool. It gives you the provision to run and test a Postman collection directly from the command line. It is built with extensibility in mind, so 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 just the way they are executed inside the collection runner in the Postman app.

Pre-requisites

1. Node.js version higher than v4
2. NPM

In order to run Newman, ensure that you have Node.js version higher than v4. A copy of the Node.js installable can be downloaded from: https://nodejs.org/en/download/package-manager.

The easiest way to install Newman is using NPM. If you have Node.js installed, it is most likely that you have NPM installed as well.

Here is the command:

$ npm install newman --global

The newman run command allows you to specify a collection to be run. You can easily export your Postman Collection as a JSON file from the Postman app and run it using Newman.

$ newman run examples/sample-collection.json

If your collection file is available as a URL (such as from your cloud API service), Newman can fetch your file and run it as well.

$ newman run https://www.getpostman.com/collections/631643-f695cab7-6878-eb55-7943-ad88e1ccfd65-JsLv

In order to run Newman with the combination of environment and collection:

newman run --environment “environment name.json” collections/”postmanscenario.json”

This should be the output if all calls are passed:

The results of all tests and requests can be exported into a file and later imported into Postman for further analysis. Use the JSON reporter and a filename to save the runner output into a file.

$ newman run mycollection.json --reporters cli,json --reporter-json-export outputfile.json

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 the response body when a request (or its tests) fail, and so on.

Building custom reporters

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

In order to create a custom reporter, please follow these steps:

1. Navigate to a directory of your choice, and create a blank npm package with npm init.
2. 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 };
3. Publish your reporter using npm publish, or use your reporter locally.
    

Scoped reporter package names like @myorg/newman-reporter-<name> are also supported.