Skip to main content

pm Object API

tip

Global Methods

pm

pm:Object

The pm object provides access to request details and returns results during the execution of interfaces or test suites. Additionally, it allows you to manage the environment and global variables.

pm.info:Object

The pm.info object contains information related to the execution of interfaces (or test suites).

pm.info.eventName:String

The type of script being executed, either pre-script (pre_script) or post-script (test).

pm.info.iteration:Number

The current iteration, valid for loops in automated tests. For single interface tests, it remains 0.

pm.info.iterationCount:Number

The total number of rounds needed for this execution, only valid for loops in automated tests, and always 1 for single interface tests.

pm.info.requestId:String

The unique ID of the current interface case.

pm.variables

Temporary variables. Variables of different types have different priorities, and the order of priority for different types of variables is: Temporary variables < Environment variables < Global variables.

pm.variables.has(variableName:String):functionBoolean: Check if a certain temporary variable exists.
pm.variables.get(variableName:String):function*: Get a single temporary variable.
pm.variables.set(variableName:String, variableValue:String):functionvoid: Set a single temporary variable.
pm.variables.replaceIn(variableName:String):function: Replace the included dynamic variables in the string with their actual values, such as {{variable_name}}.
pm.variables.toObject():functionObject: Get all temporary variables in the form of an object.

pm.iterationData

Test data variables are managed separately。 It's currently not supported to set them directly in the script. However, you can access test data variables within the script as follows.

pm.iterationData.has(variableName:String):functionBoolean: Check if a certain test data variable exists.
pm.iterationData.get(variableName:String):function*: Get a single test data variable.
pm.iterationData.replaceIn(variableName:String):function: Replace the included dynamic variables in the string with their actual values, such as {{variable_name}}.
pm.iterationData.toObject():functionObject: Get all test data variables in the form of an object.

pm.environment

pm.environment.getName():String: Get the current environment name.
pm.environment.getPreUrl():String: Get the current environment pre-URL.
pm.environment.getCollection():String: Get the current environment variable collection.
pm.environment.has(variableName:String):functionBoolean: Check if a certain environment variable exists.
pm.environment.get(variableName:String):function*: Get a single environment variable.
pm.environment.set(variableName:String, variableValue:String):function: Set a single environment variable.
pm.environment.replaceIn(variableName:String):function: Replace the included dynamic variables in the string with their actual values, such as {{variable_name}}.
pm.environment.toObject():functionObject: Get all variables in the current environment in the form of an object.
pm.environment.unset(variableName:String):function: Unset a single environment variable.
pm.environment.clear():function: Clear all variables in the current environment.

pm.globals

pm.globals.has(variableName:String):functionBoolean: Check if a certain global variable exists.
pm.globals.get(variableName:String):function*: Get a single global variable.
pm.globals.set(variableName:String, variableValue:String):function: Set a single global variable.
pm.globals.replaceIn(variableName:String):function: Replace the included dynamic variables in the string with their actual values, such as {{variable_name}}.
pm.globals.toObject():functionObject: Get all global variables in the form of an object.
pm.globals.unset(variableName:String):function: Unset a single global variable.
pm.globals.clear():function: Clear all global variables in the current environment.

pm.test

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

This method is used to assert whether a result meets expectations.

The following example asserts that the returned response is valid:

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");
});

Test Script Examples

Hello World! The First Test Script

To write your first test script, open a request in EchoAPI and then select the "Post-response Script" tab. Enter the following JavaScript code:

pm.test("Status code is 200", function () {
pm.response.to.have.status(200);
});

This test verifies the response code returned by the API. If the response code is 200, the test will pass; otherwise, it will fail. After sending the request, check the Assertions and Validations tab in the response area.

image.png

Build your test assertions in various ways to suit your logic and preferences for the output of results. The following code is another method to achieve the same test as the above code using the expect syntax:

pm.test("Status code is 200", () => {
pm.expect(pm.response.code).to.eql(200);
});

What is pm.expect?

pm.expect(assertion:*):Function → Assertion

The above example uses pm.expect, an assertion library for testing. For a complete overview of assertion syntax options, please refer to the Chai Assertion Library Documentation.

Using Multiple Assertions

Your test can include multiple assertions within a single test. Use this to group related assertions together:

pm.test("The response has all properties", () => {
//parse the response JSON and test three properties
const responseJson = pm.response.json;
pm.expect(responseJson.type).to.eql('vip');
pm.expect(responseJson.name).to.be.a('string');
pm.expect(responseJson.id).to.have.lengthOf(1);
});

If any of the included assertions fail, the entire test will fail. All assertions must pass for the test to pass.

Parsing Response Body Data

To make assertions about your response, you first need to parse the data into a JavaScript object that your assertions can use.

To parse JSON data, use the following syntax:

const responseJson = pm.response.json;

To parse XML, use the following:

const responseJson = xml2Json(pm.response.text());

To parse CSV, use the CSV parsing utility:

const responseJson = csv2array(pm.response.text());

Handling Unparsed Responses

If the response body cannot be parsed into JavaScript because its format is not JSON, XML, HTML, CSV, or any other supported format, you can still make assertions about the data.

Test if the response body contains a string:

pm.test("Body contains string",() => {
pm.expect(pm.response.text()).to.include("customer_id");
});

This does not specify the location of the string, as it checks the entire response body. Test if the response matches a string (usually effective only for short responses):

pm.test("Body is string", function () {
pm.response.to.have.body("whole-body-text");
});

Making Assertions on HTTP Responses

Your tests can check various aspects of the request response, including body, status codes, headers, cookies, response times, and so on.

Testing the Response Body

Check for specific values in the response body:

pm.test("Person is Jane", () => {
const responseJson = pm.response.json;
pm.expect(responseJson.name).to.eql("Jane");
pm.expect(responseJson.age).to.eql(23);
});

Testing Status Codes

Test the response status code:

pm.test("Status code is 201", () => {
pm.response.to.have.status(201);
});

If you want to test whether the status code is one of a group, include them all in an array and use oneOf:

pm.test("Successful POST request", () => {
pm.expect(pm.response.code).to.be.oneOf([201,202]);
});

Check the status code text:

pm.test("Status code name has string", () => {
pm.response.to.have.status("Created");
});

Testing Headers

Check if a response header exists:

pm.test("Content-Type header is present", () => {
pm.response.to.have.header("Content-Type");
});

Test for a response header with a specific value:

pm.test("Content-Type header is application/json", () => {
pm.expect(pm.response.headers['Content-Type']).to.eql('application/json');
});

Testing Cookies

Test if a cookie exists in the response:

pm.test("Cookie JSESSIONID is present", () => {
pm.expect(pm.response.cookies['cookie-test1']).to.not.be.undefined;
});

Test a specific cookie value:

pm.test("Cookie isLoggedIn has value 1", () => {
pm.expect(pm.response.cookies['cookie-test1']).to.eql('0');
});

Testing Response Time

Check if the response time falls within a specified range:

pm.test("Response time is less than 200ms", () => {
pm.expect(pm.response.responseTime).to.be.below(200);
});

pm.response.to.be.*

pm.response.to.be is a series of built-in rules for quick assertions.

pm.response.to.be.info

Check if the status code is 1XX

pm.response.to.be.success

Check if the status code is 2XX

pm.response.to.be.redirection

Check if the status code is 3XX

pm.response.to.be.clientError

Check if the status code is 4XX

pm.response.to.be.serverError

Check if the status code is 5XX

pm.response.to.be.error

Check if the status code is 4XX or 5XX

pm.response.to.be.ok

Check if the status code is 200

pm.response.to.be.accepted

Check if the status code is 202

pm.response.to.be.badRequest

Check if the status code is 400

pm.response.to.be.unauthorized

Check if the status code is 401

pm.response.to.be.forbidden

Check if the status code is 403

pm.response.to.be.notFound

Check if the status code is 404

pm.response.to.be.rateLimited

Check if the status code is 429