Postman Sandbox API reference

Postman Sandbox API Reference (pm.*)

Global Type
require Function

require(moduleName:String) → *


The require function allows you to use the sandbox built-in library modules. The list of available libraries are listed below. The list links to their corresponding documentation.

      1. atob→ v2.0.3
      2. btoa→ v1.1.2
      3. chai→ v3.5.0
      4. cheerio→ v0.22.0
      5. crypto-js→ v3.1.9-1
      6. lodash→ v4.17.2
      7. postman-collection→ v1.2.0
      8. tv4→ v1.2.7
      9. uuid→ (the module loaded is a shim for original module)
      10. xml2js→ 0.4.17

A number of NodeJS modules are also available:

      1. path
      2. assert
      3. buffer
      4. util

In order to use a library, you would need to simply call the require function and pass the module name as a parameter and assign the return of the function to a variable.

var atob = require('atob'),
    _ = require('lodash'),
 
 
    arrayOfStrings,
    base64Strings;
 
 
arrayOfStrings =  = ['string1''string2'];
 
 
base64Strings = _.map(arrayOfStrings, atob);
 
 
console.log(base64Strings);


pm Object

pm:Object

The pm object encloses all information pertaining to the script being executed and allows one to access a copy of the request being sent or the response received. It also allows one to get and set environment and global variables.

pm.info Object

pm.info:Object


The pm.info object contains information pertaining to the script being executed. Useful information such as the request name, request Id, iteration count, etc are stored inside of this.

    • pm.info.eventName:String
      contains information whether the script being executed is a "prerequest" or a "test" script.
       
    • pm.info.iteration:Number
      is the value of the current iteration being run.
       
    • pm.info.iterationCount:Number
      is the total number of iterations that are scheduled to run.
    • pm.info.requestName:String
    • pm.info.requestId :String

pm.globals VariableScope

pm.globals:VariableScope


pm.globals.has Function

pm.globals.has(variableName:String) → Boolean


pm.globals.get Function

pm.globals.get(variableName:String) → *


pm.globals.set Function

pm.globals.set(variableName:String, variableValue:String)


pm.globals.unset Function

pm.globals.unset(variableName:String)


pm.globals.clear Function

pm.globals.clear()


pm.globals.variables Function

pm.globals.variables() → Object



pm.environment VariableScope

pm.environment:VariableScope


pm.environment.has Function

pm.environment.has(variableName:String) → Boolean


pm.environment.get Function

pm.environment.get(variableName:String) → *


pm.environment.set Function

pm.environment.set(variableName:String, variableValue:String)


pm.environment.unset Function

pm.environment.unset(variableName:String)


pm.environment.clear Function

pm.environment.clear()


pm.environment.variables Function

pm.environment.variables() → Object



pm.request Request

pm.request:Request


The request object inside pm is a representation of the request for which this script is being run. For a pre-request script, this is the request that is about to be sent and when in test script, this is the representation of the request that was sent.

Request contains information stored in the following structure:

    • pm.request.url:Url
    • pm.request.headers:HeaderList


TESTONLY

pm.data Object

pm.data:Object


The data object would contain data from the data file provided during a collection run

pm.response

Response

pm.response:Response


Inside the test scripts, the pm.response object contains all information pertaining to the response that was received.

The response details are stored in the following format

    • pm.response.code:Number
    • pm.response.reason:Function → String
    • pm.response.headers:HeaderList
    • pm.response.responseTime:Number
    • pm.response.text:Function → String
    • pm.response.json:Function → Object

pm.cookies

CookieList

pm.cookies:CookieList


The cookies object contain a list of cookies that are associated with the domain to which the request was made.

pm.cookies.has Function

pm.cookies.has(cookieName:String):Function → Boolean

Check whether a particular cookie (addressed by it's name,) exists for the requested domain or not.

pm.cookies.get Function

pm.cookies.get(cookieName:String):Function → String

Get the value of a particular cookie.

pm.cookies.toObject Function

pm.cookies.toObject:Function → Object

Get a copy of all cookies and their values in form of an object. The cookies returned are the ones defined for the requested domain and path.


pm.test

Function

pm.test(testName:String, specFunction:Function)


This function is used to write test specifications inside the sandbox. Writing tests inside this function allows one to name the test accurately as well as ensure that in case of any error inside this function, the rest of the script is not blocked.

The following code block is a sample test where we are checking to ensure that everything about a fictitious response is valid for us to proceed next.

pm.test("response should be okay to process", function () {
    pm.response.to.not.be.error;
    pm.response.to.have.jsonBody('');
    pm.response.to.not.have.jsonBody('error');
});

pm.expect

Function

pm.expect(assertion:*) → Assertion


pm.expect is a generic assertion function. Underlying this is the ChaiJS expect bdd library. Using this, it is easy to write tests where the syntax becomes readable and verbose.

Read more on the usage of pm.expect at http://chaijs.com/api/bdd/

This function is useful to deal with assertions of data from response or variables.

pm.test('environment to be production', function () {
    pm.expect(pm.environment.get('env')).to.equal('production');
});

Response Assertions API

Assertion

Type

Description

pm.response.to.have.status Function

pm.response.to.have.status(code:Number)
pm.response.to.have.status(reason:String)

pm.response.to.have.header Function

pm.response.to.have.header(key:String, optionalValue:String)

pm.response.to.have.body Function

pm.response.to.have.body()
pm.response.to.have.body(optionalValue:String)
pm.response.to.have.body(optionalValue:RegExp)

pm.response.to.have.jsonBody Function

pm.response.to.have.jsonBody()
pm.response.to.have.jsonBody(optionalExpectEqual:Object)
pm.response.to.have.jsonBody(optionalExpectPath:String)
 
pm.response.to.have.jsonBody(optionalExpectPath:String, optionalValue:*)  

pm.response.to.be.* Object

The properties inside pm.response.to.be object allows you to easily assert a set of pre-defined rules