postman-collection
Version:
Enables developers to use a unified Postman Collection format Object across projects
1,197 lines (1,170 loc) • 109 kB
TypeScript
// Type definitions for postman-collection 5.1.1
// Project: https://github.com/postmanlabs/postman-collection
// Definitions by: PostmanLabs
// Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped
// TypeScript Version: 2.4
/// <reference types="node" />
declare module "postman-collection" {
/**
* @example
* Create a new CertificateList
* var CertificateList = require('postman-collection').CertificateList,
* certificateList = new CertificateList({}, [
* {
* name: 'my certificate for example.com',
* matches: ['https://example.com/*'],
* key: { src: '/path/to/key/file' },
* cert: { src: '/path/to/certificate/file' }
* },
* {
* name: 'my certificate for example2.com',
* matches: ['https://example2.com/*'],
* key: { src: '/path/to/key/file' },
* cert: { src: '/path/to/key/file' }
* }
* ]);
* @param parent - -
* @param list - The list of certificate representations
*/
export class CertificateList extends PropertyList {
constructor(parent: any, list: any[]);
/**
* Matches the given url against the member certificates' allowed matches
* and returns the certificate that can be used for the url.
* @param url - The url to find the certificate for
* @returns The matched certificate
*/
resolveOne(url: string): Certificate.definition;
/**
* Checks if the given object is a CertificateList
* @param obj - -
*/
static isCertificateList(obj: any): boolean;
}
export namespace Certificate {
/**
* The following is the object representation accepted as param for the Certificate constructor.
* Also the type of the object returned when Property.toJSON or Property.toObjectResolved is called on a
* Certificate instance.
* @example
* JSON definition of an example certificate object
* {
* "name": "My certificate for example.com",
* "matches": ["https://example.com/*"],
* "key": { "src": "/path/to/key" },
* "cert": { "src": "/User/path/to/certificate" },
* "passphrase": "iampassphrase"
* }
* @property [name] - A name for the certificate
* @property [matches] - A list of match patterns
* @property [key] - Object with path on the file system for private key file, as src
* @property [cert] - Object with path on the file system for certificate file, as src
* @property [passphrase] - The passphrase for the certificate key
*/
type definition = {
name?: string;
matches?: any[];
key?: any;
cert?: any;
passphrase?: string;
};
}
/**
* A Certificate definition that represents the ssl certificate
* to be used for an url.
* Properties can then use the `.toObjectResolved` function to procure an object representation of the property with
* all the variable references replaced by corresponding values.
* @example
* Create a new Certificate
*
* var Certificate = require('postman-collection').Certificate,
* certificate = new Certificate({
* name: 'Certificate for example.com',
* matches: ['example.com'],
* key: { src: '/User/path/to/certificate/key' },
* cert: { src: '/User/path/to/certificate' },
* passphrase: 'iampassphrase'
* });
* @param [options] - Object with matches, key, cert and passphrase
*/
export class Certificate extends Property {
constructor(options?: Certificate.definition);
/**
* Updates the certificate with the given properties.
* @param [options] - Object with matches, key, cert and passphrase
*/
update(options?: Certificate.definition): void;
/**
* Unique identifier
*/
id: string;
/**
* Name for user reference
*/
name: string;
/**
* List of match pattern
*/
matches: UrlMatchPatternList;
/**
* Private Key
*/
key: any;
/**
* Certificate
*/
cert: any;
/**
* PFX or PKCS12 Certificate
*/
pfx: any;
/**
* passphrase
*/
passphrase: any;
/**
* Checks if the certificate can be applied to a given url
* @param url - The url string for which the certificate is checked for match.
*/
canApplyTo(url: string | Url): void;
/**
* Allows the serialization of a Certificate
*
* This is overridden, in order to ensure that certificate contents are not accidentally serialized,
* which can be a security risk.
*/
toJSON(): void;
/**
* Checks if the given object is a Certificate
* @param obj - -
*/
static isCertificate(obj: any): boolean;
}
export namespace Collection {
/**
* 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.
* @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"
* }]
* }
* @property [info] - The meta information regarding the collection is provided as the `info` object.
* @property [info.id] - 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.
* @property [info.name] - 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.
* @property [info.version] - 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.
* @property [item] - 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.
* @property [variable] - 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.
* @property [auth] - Collection auth allows you to define an authentication,
* that *applies to all items* in the collection.
* @property [event] - Postman allows you to configure scripts to run when specific events
* occur.
* @property [version] - Version of the collection expressed in [semver](http://semver.org/)
* format.
*/
type definition = {
info?: {
id?: string;
name?: string;
version?: string;
};
item?: (Item.definition | ItemGroup.definition)[];
variable?: Variable.definition;
auth?: RequestAuth.definition;
event?: Event.definition[];
version?: string | Version.definition;
};
}
/**
* Create or load an instance of [Postman Collection](https://www.getpostman.com/docs/collections) 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.
* @example
* 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));
* @example
* 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));
* @param [definition] - 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/](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.
* @param [environments] - 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](https://www.getpostman.com/docs/environments).
*/
export class Collection extends ItemGroup {
constructor(definition?: Collection.definition, environments?: object[]);
/**
* 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](https://www.getpostman.com/docs/environments), but stored locally within a
* collection.
* @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'
* });
*/
variables: VariableList;
/**
* 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](http://semver.org/) format.
*/
version: Version;
/**
* Using this function, one can sync the values of collection variables from a reference object.
* @param obj - -
* @param [track] - -
*/
syncVariablesFrom(obj: any, track?: boolean): any;
/**
* Transfer the variables in this scope to an object
* @param [obj] - -
*/
syncVariablesTo(obj?: any): any;
/**
* Convert the collection to JSON compatible plain object
*/
toJSON(): any;
/**
* Check whether an object is an instance of ItemGroup.
* @param obj - -
*/
static isCollection(obj: any): boolean;
/**
* 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.
* @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)'
* }
* });
*/
events: EventList;
}
/**
* Contains a list of header elements
* @param parent - -
* @param cookies - -
*/
export class CookieList extends PropertyList {
constructor(parent: any, cookies: object[]);
/**
* Checks if the given object is a CookieList
* @param obj - -
*/
static isCookieList(obj: any): boolean;
}
export namespace Cookie {
/**
* The following is the object structure accepted as constructor parameter while calling `new Cookie(...)`. It is
* also the structure exported when Property.toJSON or Property.toObjectResolved is called on a
* Cookie instance.
* @example
* JSON definition of an example cookie
* {
* "key": "my-cookie-name",
* "expires": "1464769543832",
* // UNIX timestamp, in *milliseconds*
* "maxAge": "300",
* // In seconds. In this case, the Cookie is valid for 5 minutes
* "domain": "something.example.com",
* "path": "/",
* "secure": false,
* "httpOnly": true,
* "session": false,
* "value": "my-cookie-value",
* "extensions": [{
* "key": "Priority",
* "value": "HIGH"
* }]
* }
* @property [key] - The name of the cookie. Some call it the "name".
* @property [value] - The value stored in the Cookie
* @property [expires] - Expires sets an expiry date for when a cookie gets deleted. It should either be a
* date object or timestamp string of date.
* @property [maxAge] - Max-age sets the time in seconds for when a cookie will be deleted.
* @property [domain] - Indicates the domain(s) for which the cookie should be sent.
* @property [path] - Limits the scope of the cookie to a specified path, e.g: "/accounts"
* @property [secure] - A secure cookie will only be sent to the server when a request is made using SSL and
* the HTTPS protocol.
* The idea that the contents of the cookie are of high value and could be potentially damaging to transmit
* as clear text.
* @property [httpOnly] - The idea behind HTTP-only cookies is to instruct a browser that a cookie should never
* be accessible via JavaScript through the document.cookie property. This feature was designed as a security measure
* to help prevent cross-site scripting (XSS) attacks perpetrated by stealing cookies via JavaScript.
* @property [hostOnly] - Indicates that this cookie is only valid for the given domain (and not its parent or
* child domains.)
* @property [session] - Indicates whether this is a Session Cookie. (A transient cookie, which is deleted at
* the end of an HTTP session.)
* @property [extensions] - Any extra attributes that are extensions to the original Cookie specification can be
* specified here.
* @property [extensions[].key] - Name of the extension.
* @property [extensions[].value] - Value of the extension
*/
type definition = {
key?: string;
value?: string;
expires?: string;
maxAge?: number;
domain?: string;
path?: string;
secure?: boolean;
httpOnly?: boolean;
hostOnly?: boolean;
session?: boolean;
extensions?: {
key?: string;
value?: string;
};
};
}
/**
* A Postman Cookie definition that comprehensively represents an HTTP Cookie.
* @example
* Create a new Cookie
* var Cookie = require('postman-collection').Cookie,
* myCookie = new Cookie({
* name: 'my-cookie-name',
* expires: '1464769543832', // UNIX timestamp, in *milliseconds*
* maxAge: '300', // In seconds. In this case, the Cookie is valid for 5 minutes
* domain: 'something.example.com',
* path: '/',
* secure: false,
* httpOnly: true,
* session: false,
* value: 'my-cookie-value',
* extensions: [{
* key: 'Priority',
* value: 'HIGH'
* }]
* });
* @example
* Parse a Cookie Header
* var Cookie = require('postman-collection').Cookie,
* rawHeader = 'myCookie=myValue;Path=/;Expires=Sun, 04-Feb-2018 14:18:27 GMT;Secure;HttpOnly;Priority=HIGH'
* myCookie = new Cookie(rawHeader);
*
* console.log(myCookie.toJSON());
* @param [options] - Pass the initial definition of the Cookie.
*/
export class Cookie extends PropertyBase {
constructor(options?: Cookie.definition);
/**
* The name of the cookie.
*/
name: string;
/**
* Expires sets an expiry date for when a cookie gets deleted. It should either be a date object or
* timestamp string of date.
*/
expires: Date | string;
/**
* Max-age sets the time in seconds for when a cookie will be deleted.
*/
maxAge: number;
/**
* Indicates the domain(s) for which the cookie should be sent.
*/
domain: string;
path: string;
/**
* A secure cookie will only be sent to the server when a request is made using SSL and the HTTPS protocol.
* The idea that the contents of the cookie are of high value and could be potentially damaging to transmit
* as clear text.
*/
secure: boolean;
/**
* The idea behind HTTP-only cookies is to instruct a browser that a cookie should never be accessible via
* JavaScript through the document.cookie property. This feature was designed as a security measure to help
* prevent cross-site scripting (XSS) attacks perpetrated by stealing cookies via JavaScript.
*/
httpOnly: boolean;
hostOnly: boolean;
/**
* Indicates whether this is a Session Cookie.
*/
session: boolean;
value: string;
/**
* Any extra parameters that are not strictly a part of the Cookie spec go here.
*/
extensions: any[];
/**
* Get the value of this cookie.
*/
valueOf(): string;
/**
* Converts the Cookie to a single Set-Cookie header string.
*/
toString(): string;
/**
* Check whether an object is an instance of PostmanCookie.
* @param obj - -
*/
static isCookie(obj: any): boolean;
/**
* Stringifies an Array or PropertyList of Cookies into a single string.
* @param cookies - List of cookie definition object
*/
static unparse(cookies: Cookie[]): string;
/**
* Unparses a single Cookie.
* @param cookie - Cookie definition object
*/
static unparseSingle(cookie: Cookie): string;
/**
* Cookie header parser
* @param str - -
* @returns A plain cookie options object, use it to create a new Cookie
*/
static parse(str: string): any;
/**
* Converts the Cookie to a single Set-Cookie header string.
* @param cookie - Cookie definition object
*/
static stringify(cookie: Cookie): string;
}
export namespace Description {
type definition = {
content: string;
type: string;
};
}
/**
* This is one of the properties that are (if provided) processed by all other properties. Any property can have an
* instance of `Description` property assigned to it with the key name `description` and it should be treated as
* something that "describes" the property within which it belongs. Usually this property is used to generate
* documentation and other contextual information for a property in a Collection.
* @example
* Add a description to an instance of Collection
* var SDK = require('postman-collection'),
* Collection = SDK.Collection,
* Description = SDK.Description,
* mycollection;
*
* // create a blank collection
* myCollection = new Collection();
* myCollection.description = new Description({
* content: '<h1>Hello World</h1><p>I am a Collection</p>',
* type: 'text/html'
* });
*
* // alternatively, you could also use the `.describe` method of any property to set or update the description of the
* // property.
* myCollection.describe('Hey! This is a cool collection.');
* @param [definition] - The content of the description can be passed as a string when it
* is in `text/plain` format or otherwise be sent as part of an object adhering to the Description.definition
* structure having `content` and `type`.
*/
export class Description {
constructor(definition?: Description.definition | string);
/**
* Updates the content of this description property.
* @param content - -
* @param [type] - -
*/
update(content: string | Description.definition, type?: string): void;
/**
* The raw content of the description
*/
content: string;
/**
* The mime-type of the description.
*/
type: string;
/**
* Returns stringified Description.
*/
toString(): string;
/**
* Creates a JSON representation of the Description (as a plain Javascript object).
*/
toJSON(): any;
/**
* Checks whether a property is an instance of Description object.
* @param obj - -
*/
static isDescription(obj: any): boolean;
}
/**
* A type of PropertyList, EventList handles resolving events from parents. If an ItemGroup contains
* a set of events, each Item in that group will inherit those events from its parent, and so on.
* @param parent - -
* @param populate - -
*/
export class EventList extends PropertyList {
constructor(parent: any, populate: object[]);
/**
* Returns an array of listeners filtered by the listener name
* @param name - -
*/
listeners(name: string): Event[];
/**
* Returns all events with specific listeners only within this list. Refer to EventList.listeners for
* procuring all inherited events
* @param name - -
*/
listenersOwn(name: string): Event[];
/**
* Checks if the given object is an EventList.
* @param obj - -
*/
static isEventList(obj: any): boolean;
}
export namespace Event {
/**
* @example
* Constructing an event
* var Event = require('postman-collection').Event,
* rawEvent = {
* listen: 'test',
* script: 'tests["response code is 401"] = responseCode.code === 401'
* },
* myEvent;
* myEvent = new Event(rawEvent);
* @property listen - The event-name that this script will be called for. Usually either "test" or "prerequest"
* @property script - A Script instance that will be executed on this event. In case of a
* string, a new Script is created.
*/
type definition = {
listen: string;
script: Script | string;
};
}
/**
* A Postman event definition that refers to an event to be listened to and a script reference or definition to be
* executed.
* @param definition - Pass the initial definition of the event as the options parameter.
*/
export class Event extends Property {
constructor(definition: Event.definition);
/**
* Update an event.
* @param definition - -
*/
update(definition: Event.definition): void;
/**
* Name of the event that this instance is intended to listen to.
*/
listen: string;
/**
* The script that is to be executed when this event is triggered.
*/
script: Script;
/**
* Check whether an object is an instance of Event.
* @param obj - -
*/
static isEvent(obj: any): boolean;
}
export namespace FormParam {
/**
* @property key - The name ("key") of the form data parameter.
* @property value - The value of the parameter.
*/
type definition = {
key: string;
value: string;
};
}
/**
* Represents a Form Data parameter, which can exist in request body.
* @param options - Pass the initial definition of the form data parameter.
*/
export class FormParam {
constructor(options: FormParam.definition);
/**
* Converts the FormParameter to a single param string.
*/
toString(): string;
/**
* Returns the value of the form parameter (if any).
*/
valueOf(): any | string;
/**
* Convert the form-param to JSON compatible plain object.
*/
toJSON(): any;
/**
* Declare the list index key, so that property lists of form parameters work correctly
*/
static _postman_propertyIndexKey: string;
/**
* Form params can have multiple values, so set this to true.
*/
static _postman_propertyAllowsMultipleValues: boolean;
/**
* Parse a form data string into an array of objects, where each object contains a key and a value.
*/
static parse: any;
}
/**
* Contains a list of header elements
* @param parent - -
* @param headers - -
*/
export class HeaderList extends PropertyList {
constructor(parent: any, headers: Header[]);
/**
* Gets size of a list of headers excluding standard header prefix.
*/
contentSize(): number;
/**
* Checks if the given object is a HeaderList
* @param obj - -
*/
static isHeaderList(obj: any): boolean;
}
export namespace Header {
/**
* @example
* Create a header
* var Header = require('postman-collection').Header,
* header = new Header({
* key: 'Content-Type',
* value: 'application/xml'
* });
*
* console.log(header.toString()) // prints the string representation of the Header.
* @property key - The Header name (e.g: 'Content-Type')
* @property value - The value of the header.
*/
type definition = {
key: string;
value: string;
};
}
/**
* Represents an HTTP header, for requests or for responses.
* @example
* Parse a string of headers into an array of Header objects
* var Header = require('postman-collection').Header,
* headerString = 'Content-Type: application/json\nUser-Agent: MyClientLibrary/2.0\n';
*
* var rawHeaders = Header.parse(headerString);
* console.log(rawHeaders); // [{ 'Content-Type': 'application/json', 'User-Agent': 'MyClientLibrary/2.0' }]
*
* var headers = rawHeaders.map(function (h) {
* return new Header(h);
* });
*
* function assert(condition, message) {
* if (!condition) {
* message = message || "Assertion failed";
* if (typeof Error !== "undefined") {
* throw new Error(message);
* }
* throw message; //fallback
* }
* else {
* console.log("Assertion passed");
* }
* }
*
* assert(headerString.trim() === Header.unparse(headers).trim());
* @param options - Pass the header definition as an object or the value of the header.
* If the value is passed as a string, it should either be in `name:value` format or the second "name" parameter
* should be used to pass the name as string
* @param [name] - optional override the header name or use when the first parameter is the header value as
* string.
*/
export class Header extends Property {
constructor(options: Header.definition | string, name?: string);
/**
* Converts the header to a single header string.
*/
toString(): string;
/**
* Return the value of this header.
*/
valueOf(): string;
/**
* Assigns the given properties to the Header
* @param options - -
*/
update(options: any): void;
/**
* The header Key
*/
key: string;
/**
* The header value
*/
value: string;
/**
* Parses a multi line header string into an array of Header.definition.
* @param headerString - -
*/
static parse(headerString: string): any[];
/**
* Parses a single Header.
* @param header - -
*/
static parseSingle(header: string): any;
/**
* Stringifies an Array or PropertyList of Headers into a single string.
* @param headers - -
* @param [separator = '\r\n'] - Specify a string for separating each header
*/
static unparse(headers: any[] | PropertyList, separator?: string): string;
/**
* Unparses a single Header.
* @param header - -
*/
static unparseSingle(header: string): string;
/**
* Check whether an object is an instance of PostmanHeader.
* @param obj - -
*/
static isHeader(obj: any): boolean;
/**
* Create a new header instance
* @param [value] - Pass the header definition as an object or the value of the header.
* If the value is passed as a string, it should either be in `name:value` format or the second "name" parameter
* should be used to pass the name as string
* @param [name] - optional override the header name or use when the first parameter is the header value as
* string.
*/
static create(value?: Header.definition | string, name?: string): Header;
/**
* 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.
*/
disabled: boolean;
}
export namespace ItemGroup {
/**
* The following defines the object (or JSON) structure that one can pass to the ItemGroup while creating a new
* ItemGroup instance. This is also the object structure returned when `.toJSON()` is called on an ItemGroup instance.
* @example
* {
* "name": "Echo Get Requests",
* "id": "echo-get-requests",
* "item": [{
* "request": "https://postman-echo.com/get"
* }, {
* "request": "https://postman-echo.com/headers"
* }],
* "auth": {
* "type": "basic",
* "basic": {
* "username": "jean",
* "password": "{{somethingsecret}}"
* }
* },
* "event": [{
* "listen": "prerequest",
* "script": {
* "type": "text/javascript",
* "exec": "console.log(new Date())"
* }
* }]
* }
*/
type definition = {
item?: (ItemGroup.definition | Item.definition)[];
auth?: RequestAuth.definition;
event?: Event.definition[];
};
}
/**
* An ItemGroup represents a composite list of Item or ItemGroup. In terms of Postman App, ItemGroup
* represents a "Folder". This allows one to group Items into subsets that can have their own meaning. An
* ItemGroup also allows one to define a subset of common properties to be applied to each Item within it. For
* example, a `test` event defined on an ItemGroup is executed while testing any Item that belongs to that group.
* Similarly, ItemGroups can have a common {@RequestAuth} defined so that every Request, when processed,
* requires to be authenticated using the `auth` defined in the group.
*
* Essentially, Collection too is a special type of ItemGroup ;-).
* @example
* Add a new ItemGroup to a collection instance
* var Collection = require('postman-collection').Collection,
* ItemGroup = require('postman-collection').ItemGroup,
* myCollection;
*
* myCollection = new Collection(); // create an empty collection
* myCollection.items.add(new ItemGroup({ // add a folder called "blank folder"
* "name": "This is a blank folder"
* }));
* @param [definition] - While creating a new instance of ItemGroup, one can provide the
* initial configuration of the item group with the requests it contains, the authentication applied to all
* requests, events that the requests responds to, etc.
*/
export class ItemGroup extends Property {
constructor(definition?: ItemGroup.definition);
/**
* 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.
* @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);
*/
items: PropertyList;
/**
* 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.
* @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'
* });
*/
auth: RequestAuth;
/**
* Set of configurations used to alter the usual behavior of sending the request.
* @property disableBodyPruning - Disable body pruning for request methods like GET, HEAD etc.
*/
protocolProfileBehavior: {
disableBodyPruning: boolean;
};
/**
* Finds the first item with the given name or id in the current ItemGroup.
* @param idOrName - -
*/
oneDeep(idOrName: string): void;
/**
* Sets authentication method for all the items within this group
*/
authorizeRequestsUsing: any;
/**
* Check whether an object is an instance of ItemGroup.
* @param obj - -
*/
static isItemGroup(obj: any): boolean;
}
export namespace Item {
/**
* The following defines the object (or JSON) structure that one can pass to the Item while creating a new Item
* instance. This is also the object structure returned when `.toJSON()` is called on an Item instance.
* @example
* {
* "name": "Get Headers from Echo",
* "id": "my-request-1",
* "description": "Makes a GET call to echo service and returns the client headers that were sent",
*
* "request": {
* "url": "https://postman-echo.com/headers",
* "method": "GET"
* }
* }
* @property [request] - A request represents an HTTP request. If a string, the string is assumed to
* be the request URL and the method is assumed to be 'GET'.
* @property [responses] - Sample responses for this request can be stored along with the
* item definition.
* @property [events] - Postman allows you to configure scripts to run when specific events
* occur. These scripts are stored here, and can be referenced in the collection by their id.
*/
type definition = {
request?: Request.definition;
responses?: Response.definition[];
events?: Event.definition[];
};
}
/**
* A Postman Collection Item that holds your request definition, responses and other stuff. An Item essentially is
* a HTTP request definition along with the sample responses and test scripts clubbed together. One or more of these
* items can be grouped together and placed in an ItemGroup and as such forms a Collection of
* requests.
* @example
* Add a new Item to a folder in a collection instance
* var Collection = require('postman-collection').Collection,
* Item = require('postman-collection').Item,
* myCollection;
*
* myCollection = new Collection({
* "item": [{
* "id": "my-folder-1",
* "name": "The solo folder in this collection",
* "item": [] // blank array indicates this is a folder
* }]
* }); // create a collection with an empty folder
* // add a request to "my-folder-1" that sends a GET request
* myCollection.items.one("my-folder-1").items.add(new Item({
* "name": "Send a GET request",
* "id": "my-get-request",
* "request": {
* "url": "https://postman-echo.com/get",
* "method": "GET"
* }
* }));
* @param [definition] - While creating a new instance of Item, one can provide the initial
* configuration of the item with the the request it sends, the expected sample responses, tests, etc
*/
export class Item extends Property {
constructor(definition?: Item.definition);
/**
* The instance of the Request object inside an Item defines the HTTP request that is supposed to be
* sent. It further contains the request method, url, request body, etc.
*/
request: Request;
/**
* An Item also contains a list of sample responses that is expected when the request defined in the item is
* executed. The sample responses are useful in elaborating API usage and is also useful for other
* integrations that use the sample responses to do something - say a mock service.
*/
responses: PropertyList;
/**
* Events are a set of of Scripts that are executed when certain activities are triggered on an
* Item. For example, on defining an event that listens to the "test" event, would cause the associated
* script of the event to be executed when the test runs.
* @example
* Add a script to be executed on "prerequest" event
* var Collection = require('postman-collection').Collection,
* Item = require('postman-collection').Item,
* myCollection;
*
* myCollection = new Collection({
* "item": [{
* "name": "Send a GET request",
* "id": "my-get-request",
* "request": {
* "url": "https://postman-echo.com/get",
* "method": "GET"
* }
* }]
* }); // create a collection with one request
*
* // add a pre-request script to the event list
* myCollection.items.one('my-get-request').events.add({
* "listen": "prerequest",
* "script": {
* "type": "text/javascript",
* "exec": "console.log(new Date())"
* }
* });
*/
events: EventList;
/**
* Set of configurations used to alter the usual behavior of sending the request.
*/
protocolProfileBehavior: any;
/**
* Fetches applicable AuthType from the current item.
*/
getAuth(): RequestAuth;
/**
* Returns Events corresponding to a particular event name. If no name is given, returns all events. This
* is useful when you want to trigger all associated scripts for an event.
* @example
* Get all events for an item and evaluate their scripts
* 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()));
*
* // assuming the collection has a request called "my-request-1" in root, we get it's test events
* myCollection.items.one("my-request-1").getEvents("test").forEach(function (event) {
* event.script && eval(event.script.toSource());
* });
* @param name - one of the available event types such as `test`, `prerequest`, `postrequest`, etc.
*/
getEvents(name: string): Event[];
/**
* Sets authentication method for the request within this item
* @param type - -
* @param [options] - -
*/
authorizeRequestUsing(type: string | RequestAuth.definition, options?: VariableList): void;
/**
* Returns the path of the item
*/
getPath(): string[];
/**
* Check whether an object is an instance of PostmanItem.
* @param obj - -
*/
static isItem(obj: any): boolean;
}
export namespace MutationTracker {
/**
* A JSON representation of a mutation on an object. Here objects mean instances of postman-collection classes.
* This captures the instruction and the parameters of the instruction so that it can be replayed on a different object.
* Mutations can be any change on an object. For example setting a key or unsetting a key.
*
* For example, the mutation to set `name` on an object to 'Bruce Wayne' would look like ['name', 'Bruce Wayne']. Where
* the first item is the key path and second item is the value. To add a property `punchLine` to the object it would be
* the same as updating the property i.e. ['punchLine', 'I\'m Batman']. To remove a property `age` the mutation would
* look like ['age'].
*
* This format of representing changes is derived from
* http://json-delta.readthedocs.io/en/latest/philosophy.html.
*
* The `set` and `unset` are primitive instructions and can be derived from the mutation without explicitly stating the
* instruction. For more complex mutation the instruction would have to be explicitly stated.
*/
type mutation = any[];
/**
* A JSON representation of the MutationTracker.
* @property stream - contains the stream mutations tracked
* @property compacted - contains a compacted version of the mutations
* @property [autoCompact = false] - when set to true, all new mutations would be compacted immediately
*/
type definition = {
stream: any[];
compacted: any;
autoCompact?: boolean;
};
}
/**
* A MutationTracker allows to record mutations on any of object and store them. This stored mutations can be
* transported for reporting or to replay on similar objects.
* @param definition - serialized mutation tracker
*/
export class MutationTracker extends PropertyBase {
constructor(definition: MutationTracker.definition);
/**
* Track a mutation.
* @param instruction - the type of mutation
* @param payload - mutation parameters
*/
track(instruction: string, ...payload: any[]): void;
/**
* Compacts the recorded mutations removing duplicate mutations that apply on the same key path.
*/
compact(): void;
/**
* Returns the number of mutations tracked so far.
*/
count(): number;
/**
* Applies all the recorded mutations on a target object.
* @param target - Target to apply mutations. Must implement `applyMutation`.
*/
applyOn(target: any): void;
/**
* Check whether an object is an instance of MutationTracker.
* @param obj - -
*/
static isMutationTracker(obj: any): boolean;
}
export namespace PropertyBase {
type definition = {
description?: string | Description;
};
}
/**
* Base of all properties in Postman Collection. It defines the root for all standalone properties for postman
* collection.
* @param definition - -
*/
export class PropertyBase {
constructor(definition: PropertyBase.definition);
/**
* Invokes the given iter