Reference Postman responses in scripts

The pm.response object provides access to the data returned in the response for the current request. This object is available in Post-response scripts for HTTP requests, and in After response scripts for gRPC and GraphQL requests.

pm.response

Use the pm.response methods in your scripts to access and manipulate responses. These methods are available only in scripts for HTTP requests.

pm.response.text():Function

Gets the response text string.

pm.response.json():Function

Gets the response JSON object, which you can use to get the properties received.

pm.response properties

The properties available on pm.response depend on the request type.

The following properties are available for more than one request type:

• pm.response.responseTime:Number - The time the response took to receive in milliseconds. It’s available for every request type. For gRPC requests with streaming methods, responseTime denotes the total duration for that request execution.

• pm.response.responseSize:Number - The size of the response received. It’s available for HTTP and GraphQL requests.

HTTP response properties

The following properties are available only in scripts for HTTP requests.

• pm.response.code:Number - The response status code.

• pm.response.status:String - The status text string.

• pm.response.headers:HeaderList - The list of response headers.

gRPC response properties

The following properties are available only in scripts for gRPC requests. Along with pm.response.responseTime, they’re the only pm.response properties a gRPC response provides.

• pm.response.statusCode:Number - The gRPC response status code. A status code of 0 indicates a successful response.

• pm.response.metadata - The list of metadata received with the response. An individual metadata item is a PropertyList object with the key and value properties.

• pm.response.trailers - The list of trailers received with the response. An individual trailer item is a PropertyList object with the key and value properties.

• pm.response.messages - The list of incoming messages. An individual message is a PropertyList object containing the following properties:

  • data - The contents of the received message.
  • timestamp - The time the message was received, represented as a Date object.

  For requests with unary and client streaming methods, pm.response.messages contains only one message at index 0, which can be accessed as pm.response.messages.idx(0).

GraphQL response properties

The following properties are available only in scripts for GraphQL requests.

• pm.response.data - The data the query returned. This is an object whose keys are the fields you requested.

• pm.response.errors - The list of errors returned with the response. This property isn’t present when the query returns no errors. Each error contains a message property, and can also contain the following properties:

  • locations - The line and column in the query where the error occurred.
  • path - The path to the response field the error applies to.
  • extensions - Any extra error details the server provides.

• pm.response.transport.http - The HTTP details for the response, since Postman sends GraphQL requests over HTTP. This object contains the following properties:

  • statusCode - The HTTP response status code.
  • headers - The list of response headers.

Validate response data with a JSON Schema

The jsonSchema method enables you to write a test assertion that validates the response data with a JSON Schema. Postman uses version 6.12.5 of the Ajv JSON Schema validator to validate response data with a JSON Schema.

To write your test assertion, use the pm.response object and Chai Assertion Library BDD syntax to access the data returned in the response.

The jsonSchema method accepts a JSON Schema as an object in the first argument. It also accepts an object of optional Ajv options in the second argument:

pm.response.<bdd-syntax>.jsonSchema(schema, options);

You can define a JSON Schema in Postman, such as in the Scripts tab of a request. Then you can write a test that validates the properties in your response data against the defined JSON Schema.

Examples

In this example, the JSON Schema requires the response data to contain an alpha property that’s a Boolean data type. If the response data is missing this property or it’s a different data type, the test fails. This example uses BDD syntax to.have to express the assertion:

const schema = {
  "type": "object",
  "properties": {
    "alpha": {
      "type": "boolean"
    }
  },
  "required": ["alpha"]
};
pm.test('Response is valid', function() {
  pm.response.to.have.jsonSchema(schema);
});