Using Newman to Run Postman Collections

This is a brief introduction to how you can use the Newman library to make API testing automation a part of the continuous integration process. I will brief you on a few important things before on how we can set up API collections on Newman.

Newman

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

Getting Started

To get started with the Newman setup, you need to have a node js version greater than 10. My current system has v16.9.1. 

Installation

The easiest way to install Newman is using NPM. If nodejs is installed within the system, then it is most likely that you would have npm installed as well. To verify you have npm installed, run the command npm -v. To install Newman, run the command npm install -g newman . This helps running Newman from anywhere in the system. To install locally within the current project, make it a part of the package.json. To install using homebrew in mac, run the command brew install newman.

Here, we are also going to use the Newman-HTML-reporter library to consolidate the test results within an HTML file.

Project Set-Up

Let's start implementing the API tests by creating the project directory structure. Inside the root directory of the project, I have created two directories app and report. Inside app there are two directories collections and runner. Collections will contain the collection.json exported from the postman and the runner will have the Newman runner code. Let's start by creating the dependencies of the project by running the command npm init. Once created, create a JSON object as dependencies and include the following dependencies to be installed: 

"dependencies": {
    "newman": "^5.3.0",
    "newman-reporter-htmlextra": "^1.22.1"
  }

Next, run npm install. This will create the package-lock.json and will install the respective modules and dependencies in the node_modules directory within the project root folder. 

Exporting a Collection From Postman

To export a collection from the postman, click on export from collection to the collection folder in the app directory of the project.

Setting Up Runner

To set up the runner, you will need to create a file called runner.js in the runner directory within the app directory. In the runner.js, we will need to give the path where the collections are present and the path where the report will be created. A point to be noted is that, if we are using global variables in postman, then we will need to keep in mind that it will not be accessible outside the scope of the postman. So, to declare global variables, we will have to declare the globalVar object where we can define the respective global variables in key-value pairs.

The runner object that I have defined looks like this:

const newman = require('newman');
const path = require('path');

var basepath = path.resolve("../");

var reportpath = path.resolve("../../")+"/report";


newman.run({
    // Collection URL from a public link or the Postman API can also be used
    collection: basepath + '/collection/testapiproject.postman_collection.json',
    reporters: ['htmlextra'],
    iterationCount: 1,
    globalVar:[
        {"key": "application_id", "value": process.env.apikey}
    ],
    reporter: {
        htmlextra: {
            export: reportpath + '/apireport.html',
            // template: './template.hbs'
            logs: true,
            // showOnlyFails: true,
            // noSyntaxHighlighting: true,
            // testPaging: true,
            browserTitle: "API report stats",
            title: "API report stats"
            // titleSize: 4,
            // omitHeaders: true,
            // skipHeaders: "Authorization",
            // omitRequestBodies: true,
            // omitResponseBodies: true,
            // hideRequestBody: ["Login"],
            // hideResponseBody: ["Auth Request"],
            // showEnvironmentData: true,
            // skipEnvironmentVars: ["API_KEY"],
            // showGlobalData: true,
            // skipGlobalVars: ["API_TOKEN"],
            // skipSensitiveData: true,
            // showMarkdownLinks: true,
            // showFolderDescription: true,
            // timezone: "Australia/Sydney",
            // skipFolders: "folder name with space,folderWithoutSpace",
            // skipRequests: "request name with space,requestNameWithoutSpace"
        }
    }
});

Now, we have to set up the execution, which can be utilized to run the code on the go as a part of the continuous integration process. To do this, you can define the execution within the script object in the package.json. You can define the scripts as the following:

"scripts": {
    "apitest": "cd app/runner && node  runner.js"
  }

Execution

To run the script, execute npm run apitest. This will run the collection using Newman and create the HTML report within the report directory. 

Reports

The reports from Newman are quite descriptive and elaborate on their own. The reports pretty much look like the following:

To find out more about the implementation, please look into this Github link.