Postman Collection SDK

Postman Collections are organized in a hierarchical structure. At the top level is a Collection, which contains an information block and an array of items. These items can be either Items (the basic building block representing an HTTP request) or ItemGroups (folders used to containerize other Items or ItemGroups).

Hierarchy Summary:

• Collection: The root container. Contains information and items.
• ItemGroup (Folder): A container for Items or other ItemGroups.
• Item: Represents an HTTP request and its metadata. Can contain responses and events.
• Request: The actual HTTP definition (URL, method, headers, body, auth) usually contained within an Item.
• Events: Scripts associated with an Item that run at specific lifecycle stages (e.g., prerequest or test).

A Collection is the root object. It must include an information block with a required schema property pointing to the valid Postman schema URL. The item array holds the contents of the collection, such as folders or requests.

Required Schema URL: https://schema.getpostman.com/json/collection/v2.0.0/

{
    "information": {
        "name": "My Collection",
        "version": "v2.0.0",
        "description": "This is a demo collection.",
        "schema": "https://schema.getpostman.com/json/collection/v2.0.0/"
    },
    "item": []
}

You can install the Postman Collection SDK into your NodeJS project using npm. This will add the package to your package.json dependencies.

npm install postman-collection --save

An EventList is a specialized PropertyList used to manage events within a Postman collection or item. It supports hierarchical inheritance: if an ItemGroup contains a set of events, its child Items will inherit those events from their parent.

When retrieving listeners, EventList traverses up the parent chain to collect events, allowing you to define common tests or scripts at a high level (like a collection or folder) that automatically apply to all nested requests.

The Postman Collection SDK provides a suite of classes to programmatically interact with, manipulate, and validate Postman collections. You can import the main entrypoint to access all core collection components such as Collection, Item, Request, Variable, and Header.

const sdk = require('postman-collection');

// Accessing core classes
const Collection = sdk.Collection;
const Item = sdk.Item;
const Request = sdk.Request;

A Request defines the HTTP execution details. While an Item can use a simple string for a request, a full Request object allows for granular control over:

• method: The HTTP verb (e.g., GET, POST).
• url: The endpoint URL.
• header: An array of key/value pairs.
• body: The request payload (e.g., urlencoded, raw).
• auth: Authentication configuration (e.g., basic, bearer).

{
    "description": "This is a sample POST request",
    "url": "https://echo.getpostman.com/post",
    "method": "POST",
    "header": [
        {
            "key": "Content-Type",
            "value": "application/json"
        }
    ],
    "body": {
        "mode": "urlencoded",
        "urlencoded": [
            {
                "key": "my-body-variable",
                "value": "Something Awesome!"
            }
        ]
    }
}

Once mutations have been captured in a VariableScope, you can use the .applyOn() method on the mutations collection to replay those changes onto a different object. This is useful for mirroring the state of one scope onto another.

var environmentCopy = new VariableScope();

// applies the mutations captured on `environment` into `environmentCopy` making it a mirror
environment.mutations.applyOn(environmentCopy);

To track changes made to a VariableScope (such as an environment), you must explicitly call .enableTracking() on the instance. Once enabled, all subsequent set, unset, or clear operations are recorded in the mutations property of that scope.

var VariableScope = require('postman-collection').VariableScope,
    environment = new VariableScope();

// enables tracking mutations
environment.enableTracking();