Collection

Collection

new Collection(definitionopt, environmentsopt)

Create or load an instance of Postman Collection as a JavaScript object that can be manipulated easily.

A collection lets you group individual requests together. These requests can be further organized into folders to accurately mirror your API. Requests can also store sample responses when saved in a collection. You can add metadata like name and description too so that all the information that a developer needs to use your API is available easily.

Parameters:
Name Type Attributes Description
definition Collection.definition <optional>

Pass the initial definition of the collection (name, id, etc) as the definition parameter. The definition object is structured exactly as the collection format as defined in https://www.schema.getpostman.com/. This parameter is optional. That implies that you can create an empty instance of collection and add requests and other properties in order to build a new collection.
environments Array.<Object> <optional>

The collection instance constructor accepts the second parameter as an array of environment objects. Environments objects store variable definitions that are inherited by Collection#variables. These environment variables are usually the ones that are exported from the Postman App to use them with different collections. Refer to Postman documentation on environment variables.
Source:
Examples

Load a Collection JSON file from disk

var fs = require('fs'), // needed to read JSON file from disk
    pretty = function (obj) { // function to neatly log the collection object to console
        return require('util').inspect(obj, {colors: true});
    },
    Collection = require('postman-collection').Collection,
    myCollection;

// Load a collection to memory from a JSON file on disk (say, sample-collection.json)
myCollection = new Collection(JSON.stringify(fs.readFileSync('sample-collection.json').toString()));

// log items at root level of the collection
console.log(pretty(myCollection));

Create a blank collection and write to file

var fs = require('fs'),
    Collection = require('postman-collection').Collection,
    mycollection;

myCollection = new Collection({
    info: {
        name: "my Collection"
    }
});

// log the collection to console to see its contents
fs.writeFileSync('myCollection.postman_collection', JSON.stringify(myCollection, null, 2));

Extends

Members

auth :RequestAuth

One can define the default authentication method required for every item that belongs to this list. Individual Requests can override this in their own definitions. More on how to define an authentication method is outlined in the RequestAuth property.

Type:
Inherited From:
Source:
Example

Define an entire ItemGroup (folder) or Collection to follow Basic Auth

var fs = require('fs'),
    Collection = require('postman-collection').Collection,
    RequestAuth = require('postman-collection').RequestAuth,
    mycollection;

// Create a collection having two requests
myCollection = new Collection();
myCollection.items.add([
    { name: 'GET Request', request: 'https://postman-echo.com/get?auth=basic' },
    { name: 'PUT Request', request: 'https://postman-echo.com/put?auth=basic' }
]);

// Add basic auth to the Collection, to be applied on all requests.
myCollection.auth = new RequestAuth({
    type: 'basic',
    username: 'postman',
    password: 'password'
});

authorizeRequestsUsing

Sets authentication method for all the items within this group

Inherited From:
Source:

disabled :Boolean

This (optional) flag denotes whether this property is disabled or not. Usually, this is helpful when a property is part of a PropertyList. For example, in a PropertyList of Headers, the ones that are disabled can be filtered out and not processed.

Type:
  • Boolean
Inherited From:
Source:

events :EventList

In this list, one can define the Scripts to be executed when an event is triggered. Events are triggered before certain actions are taken on a Collection, Request, etc. For example, executing a request causes the prerequest and the test events to be triggered.

Type:
Source:
Example

Executing a common test script for all requests in a collection

var fs = require('fs'), // needed to read JSON file from disk
    Collection = require('postman-collection').Collection,
    myCollection;

// Load a collection to memory from a JSON file on disk (say, sample-collection.json)
myCollection = new Collection(JSON.stringify(fs.readFileSync('sample-collection.json').toString()));

// Add an event listener to the collection that listens to the `test` event.
myCollection.events.add({
    listen: 'test',
    script: {
        exec: 'tests["Status code is 200"] = (responseCode.code === 200)'
    }
});

id :String

The id of the property is a unique string that identifies this property and can be used to refer to this property from relevant other places. It is a good practice to define the id or let the system auto generate a UUID if one is not defined for properties that require an id.

Type:
  • String
Inherited From:
Source:

items :PropertyList.<(Item|ItemGroup)>

This is a PropertyList that holds the list of Items or ItemGroups belonging to a Collection or to an ItemGroup. Operation on an individual item in this list can be performed using various functions available to a PropertyList.

Type:
Inherited From:
Source:
Example

Fetch empty ItemGroups in a list loaded from a file

var fs = require('fs'), // needed to read JSON file from disk
    Collection = require('postman-collection').Collection,
    myCollection,
    emptyGroups;
// Load a collection to memory from a JSON file on disk (say, sample-collection.json)
myCollection = new Collection(JSON.stringify(fs.readFileSync('sample-collection.json').toString()));

// Filter items in Collection root that is an empty ItemGroup
emptyGroups = myCollection.items.filter(function (item) {
    return item && item.items && (item.items.count() === 0);
});

// Log the emptyGroups array to check it's contents
console.log(emptyGroups);

name :String

A property can have a distinctive and human-readable name. This is to be used to display the name of the property within Postman, Newman or other runtimes that consume collection. In certain cases, the absence of name might cause the runtime to use the id as a fallback.

Type:
  • String
Inherited From:
Source:

protocolProfileBehavior :Object

Set of configurations used to alter the usual behavior of sending the request.

Type:
  • Object
Properties:
Name Type Description
disableBodyPruning Boolean

Disable body pruning for request methods like GET, HEAD etc.
Inherited From:
Source:

variables :VariableList

The variables property holds a list of variables that are associated with a Collection. These variables are stored within a collection so that they can be re-used and replaced in rest of the collection. For example, if one has a variable named port with value 8080, then one can write a request Url as http://localhost:{{port}}/my/endpoint and that will be replaced to form http://localhost:8080/my/endpoint. Collection Variables are like environment variables, but stored locally within a collection.

Type:
Source:
Example

Creating a collection with variables

var fs = require('fs'),
    Collection = require('postman-collection').Collection,
    mycollection;

// Create a new empty collection.
myCollection = new Collection();

// Add a variable to the collection
myCollection.variables.add({
    id: 'apiBaseUrl',
    value: 'http://timeapi.org',
    type: 'string'
});

//Add a request that uses the variable that we just added.
myCollection.items.add({
    id: 'utc-time-now',
    name: 'Get the current time in UTC',
    request: '{{apiBaseUrl}}/utc/now'
});

version :Version

The version key in collection is used to express the version of the collection. It is useful in either tracking development iteration of an API server or the version of an API itself. It can also be used to represent the number of iterations of the collection as it is updated through its lifetime.

Version is expressed in semver format.

Type:
Source:
See:

Methods

(static) isCollection(obj) → {Boolean}

Check whether an object is an instance of ItemGroup.

Parameters:
Name Type Description
obj *
Source:
Returns:
Type
Boolean

describe(content, typeopt)

This function allows to describe the property for the purpose of detailed identification or documentation generation. This function sets or updates the description child-property of this property.

Parameters:
Name Type Attributes Default Description
content String

The content of the description can be provided here as a string. Note that it is expected that if the content is formatted in any other way than simple text, it should be specified in the subsequent type parameter.
type String <optional>
 "text/plain"

The type of the content.
Inherited From:
Source:
Example

Add a description to an instance of Collection

 var Collection = require('postman-collection').Collection,
    mycollection;

// create a blank collection
myCollection = new Collection();
myCollection.describe('Hey! This is a cool collection.');

console.log(myCollection.description.toString()); // read the description

findInParents(property, customizeropt) → {*|undefined}

Tries to find the given property locally, and then proceeds to lookup in each parent, going up the chain as necessary. Lookup will continue until customizer returns a truthy value. If used without a customizer, the lookup will stop at the first parent that contains the property.

Parameters:
Name Type Attributes Description
property String
customizer function <optional>
Inherited From:
Source:
Returns:
Type
* | undefined

forEachParent(options, iterator)

Invokes the given iterator for every parent in the parent chain of the given element.

Parameters:
Name Type Description
options Object

A set of options for the parent chain traversal.

Properties
Name Type Attributes Default Description
withRoot Boolean <optional>
<nullable>
 false

Set to true to include the collection object as well.
iterator function

The function to call for every parent in the ancestry chain.
Inherited From:
Source:
To Do:
  • Cache the results

meta() → {*}

Returns the meta keys associated with the property

Inherited From:
Source:
Returns:
Type
*

oneDeep(idOrName)

Finds the first item with the given name or id in the current ItemGroup.

Parameters:
Name Type Description
idOrName String
Inherited From:
Source:

parent() → {*|undefined}

Returns the parent of item

Inherited From:
Source:
Returns:
Type
* | undefined

syncVariablesFrom(obj, trackopt) → {Object}

Using this function, one can sync the values of collection variables from a reference object.

Parameters:
Name Type Attributes Description
obj Object
track Boolean <optional>
Source:
Returns:
Type
Object

syncVariablesTo(objopt) → {Object}

Transfer the variables in this scope to an object

Parameters:
Name Type Attributes Description
obj Object <optional>
Source:
Returns:
Type
Object

toJSON() → {Object}

Convert the collection to JSON compatible plain object

Overrides:
Source:
Returns:
Type
Object

Type Definitions

definition

The following is the object structure accepted as constructor parameter while calling new Collection(...). It is also the structure exported when Property#toJSON or Property#toObjectResolved is called on a collection instance.

Properties:
Name Type Attributes Description
info Object <optional>

The meta information regarding the collection is provided as the info object.

Properties
Name Type Attributes Description
id String <optional>

Every collection is identified by the unique value of this property. It is recommended that you maintain the same id since changing the id usually implies that is a different collection than it was originally.
name String <optional>

A collection's friendly name is defined by this property. You would want to set this field to a value that would allow you to easily identify this collection among a bunch of other collections.
version String <optional>

Postman allows you to version your collections as they grow, and this field holds the version number. While optional, it is recommended that you use this field to its fullest extent.
item Array.<(Item.definition|ItemGroup.definition)> <optional>

Items are the basic unit for a Postman collection. You can think of them as corresponding to a single API endpoint. Each Item has one request and may have multiple API responses associated with it.
variable Variable.definition <optional>

Collection variables allow you to define a set of variables, that are a part of the collection, as opposed to environments, which are separate entities.
auth RequestAuth.definition <optional>

Collection auth allows you to define an authentication, that applies to all items in the collection.
event Array.<Event.definition> <optional>

Postman allows you to configure scripts to run when specific events occur.
version String | Version.definition <optional>

Version of the collection expressed in semver format.
Source:
See:
  • {ItemGroup.definition} - Since `Collection` inherits ItemGroup, the properties supported by ItemGroup are applicable as well.
Example

JSON definition of an example collection

{
    "info": {
        "name": "My Postman Collection",
        "version": "1.0.0"
    }
    "item": [{
        "request": "{{base-url}}/get"
    }],
    "variables": [{
        "id": "base-url",
        "value": "https://postman-echo.com"
    }]
}