new Item(definitionopt)
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.
Parameters:
Name | Type | Attributes | Description |
---|---|---|---|
definition |
Item.definition |
<optional> |
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 |
- Source:
Example
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"
}
}));
Extends
Members
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
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.
Type:
- Source:
Example
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())"
}
});
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:
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
- Source:
request :Request
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.
Type:
- Source:
responses :PropertyList.<Response>
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.
Type:
- Source:
Methods
(static) isItem(obj) → {Boolean}
Check whether an object is an instance of PostmanItem.
Parameters:
Name | Type | Description |
---|---|---|
obj |
* |
- Source:
Returns:
- Type
- Boolean
authorizeRequestUsing(type, optionsopt)
Sets authentication method for the request within this item
Parameters:
Name | Type | Attributes | Description |
---|---|---|---|
type |
String | RequestAuth.definition | ||
options |
VariableList |
<optional> |
- Source:
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 |
String |
<optional> |
"text/plain" | The type of the content. |
- Inherited From:
- Source:
Example
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
|
||||||||||
iterator |
function | The function to call for every parent in the ancestry chain. |
- Inherited From:
- Source:
- To Do:
-
- Cache the results
getAuth() → {RequestAuth}
Fetches applicable AuthType from the current item.
- Source:
- To Do:
-
- Deprecate this and use getAuthResolved instead
Returns:
- Type
- RequestAuth
getEvents(name) → {Array.<Event>}
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.
Parameters:
Name | Type | Description |
---|---|---|
name |
String | one of the available event types such as |
- Source:
- To Do:
-
- decide appropriate verb names based on the fact that it gets events for a specific listener name
Returns:
- Type
- Array.<Event>
Example
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());
});
meta() → {*}
Returns the meta keys associated with the property
- Inherited From:
- Source:
Returns:
- Type
- *
parent() → {*|undefined}
Returns the parent of item
- Inherited From:
- Source:
Returns:
- Type
- * | undefined
toJSON()
Returns the JSON representation of a property, which conforms to the way it is defined in a collection. You can use this method to get the instantaneous representation of any property, including a Collection.
- Inherited From:
- Source:
Type Definitions
definition
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.
Properties:
Name | Type | Attributes | Description |
---|---|---|---|
request |
Request.definition |
<optional> |
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'. |
responses |
Array.<Response.definition> |
<optional> |
Sample responses for this request can be stored along with the item definition. |
events |
Array.<Event.definition> |
<optional> |
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. |
- Source:
- To Do:
-
- add response and event to example
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"
}
}