Newman — running Postman collections in node.js

Maybe this is easy, maybe not. Maybe this will save someone’s time. However, a while ago, I was trying to figure out how to include all existing Postman collections (about 8) to a CI pipeline. Here is an easy recipe for how to do it. Of course, before everything, you should export all collections, which you would like to run, using the built-in Postman export.

Assuming all collections are ready to use, and there are also environments in use, this setup should help you to achieve the goal. The setup will contain only three simple packages:

• path — module provides utilities for working with file and directory paths,
• async — the module will make our code a bit more asynchronous,
• newman — this will do the job — it is a command line collection runner.

The first thing you need to do, is to initiate the node project — as this is the easiest way to create all necessary files. So:

1. Create a directory in which you would like to keep all files (start the project), open the command line there, and type the following command (which will create a package.json file with basic properties):
   npm init -y
2. Then can start installing dependencies:
   npm i path
   npm i asyn
   npm i newman

This should make your package.json file look like:

Here we can see or set up the basic information about the project: scripts which will help us to execute tests (easier) and dependencies — the stuff which we installed in the step before with its versions.

Now we can start the whole fun. We need to create the file (js file) in which the whole code will be stored. It could be the main script (‘index.js’) or we can rename it to e.g. ‘newman-runner.js’. To shortage the story, I’ll put here ‘ready-to-use’ code, which can be copied and run (after a small tune).

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

const PARALLEL_RUN_COUNT = 1;

const collections = [   
    'collections/first.postman_collection.json', 
    'collections/second.postman_collection.json',
    'collections/third.postman_collection.json'
]

const environments = [
    'environments/ci.postman_environment.json',
    'environments/stg.postman_environment.json'
];

const environment = environments[0];
const collectionToRun = [];

for (let index = 0; index < collections.length; index++) {
    collectionToRun[index] = {
        collection: path.join(__dirname, collections[index]), 
        environment: path.join(__dirname, environment), 
        reporters: ['cli','htmlextra','junit'],
        bail: newman
    };
};

parallelCollectionRun = function (done) {
    for (let index=0; index < collectionToRun.length; index++){
        newman.run(collectionToRun[index], 
            function (err) {
                if (err) { throw err; }
                console.log(collections[index]+' collection run complete!');
            });
    }
    done;
};

let commands = [];
for (let index = 0; index < PARALLEL_RUN_COUNT; index++) {
    commands.push(parallelCollectionRun);
};

async.parallel(
    commands,
    (err, results) => {
        err && console.error(err);
        results.forEach(function (result) {
            var failures = result.run.failures;
            console.info(failures.length ? JSON.stringify(failures.failures, null, 2) :
                `${result.collection.name} ran successfully.`);
    });
});

Now, let’s walk through the file and have a closer look at the content. Starting from the top:

• We have three imports, which will be used below.
• We defined PARALLEL_RUN_COUNT — easy and save option is ‘1’ — to not overload the host (on which the tests will be run).
• Below we have declaration of the collections (including the catalogue in which collections are stored) — the main level is where we have package.json file. So, if we have there also collections (without any additional directory), then in the declaration we have collections name only.
• Similar declaration of existing environments.
• Then we declare two additional variables — first, in which we store the environment which will be used (during test execution), and the second empty list in which we’ll store the objects (which will be used for the test execution).
• And here we have the fist ‘for’ loop statement — this code is creating an array of objects in ‘collectionToRun’, with each object representing a collection to be run. Each object has properties like collection, environment, reporters, and bail, and these properties are populated based on the values in the collections array and the environment variable, among others. I’m sure, that collection and environment are pretty understandable, the reporters can be used as it is, or we can remove unnecessary one.
• Below, there is a function declaration — which runs a series of Postman collections in parallel, and for each collection run, it logs a message to the console upon completion. If any of the runs encounter an error, it throws that error as an exception, which could potentially halt the script. The done callback, when invoked correctly, would signal the end of all collection runs.
• Then we’re preparing a list of functions that can be executed later in parallel. This will be stored in the commands (list) variable.
• And the last part — the execution — this code is running multiple tasks in parallel using the async.parallel function, checking for any errors, and then processing the results of each task. If a task has failures, it logs information about those failures; otherwise, it logs a success message for that task.

To execute the script, you just need to type the following command (assuming the file with the code is named newman-runner.js):

‘node newman-runner.js’

I hope, I explained it clearly. However, I’m aware that some explanations maybe confusing or could be written even more clearer. As here, I don’t want to go too deep into the code, but more about the easy-to-use.

The above recipe is a ready-to-use solution to use in the CI/CD pipeline. The only things which needs to be tailored are the collections names (with the directories — if are lower level than package.json) and the environments. So, have fun and experiment. ;)