Postman Test API comes with a sandbox which makes it more easy and convenient to write tests and assertions for your requests. In this article, we are going to have a look at this API and see how we can utilize it to write tests and assertions for our requests.

This article expects that you have some basic knowledge of how to use Postman, and the environment variables. I recommend reading Test your REST API with Postman to learn the basics before proceeding with this article.

Postman Sandbox

Everything that you write in the pre-request and tests section is executed in the Postman Sandbox. Think of it as a JavaScript execution environment. It supports various different libraries, such as:

• Lodash
• cheerio
• CryptoJS

Environment and global variables can be fully utilized in the sandbox. This means that you can set, update and retrieve variables. Similar to Java method naming conventions, variables can be set and get using setters and getters.

// Sets an environment & global variable, the first argument is the name of the variable.
postman.setEnvironmentVariable("age", 24);
postman.setGlobalVariable("name", "viktor");

// Gets an environment & global variable.
postman.getEnvironmentVariable("age");
postman.getGlobalVariable("name");

// Clears an environment & global variable.
postman.clearEnvironmentVariable("age");
postman.clearGlobalVariable("name");

Postman Test API

When writing tests, you are probably looking to do some sort of assertions. Asserting that the correct HTTP status code was returned, or asserting that some variable was properly returned. Postman makes this very easy by providing a couple of functions for convenience, this is what can be referred to as the Postman TEST API.

To declare a test, use the following syntax.

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

pm.test(string, function) takes two arguments, the first one being a string that declares the name of the test to make it easier for you as a user to identify which tests passed and which didn’t. The second argument is a function which should include what you want to assert. In the case above, we assert that the response of the request is HTTP 200 OK.

We can also easy assert the data in the response body. To retrieve the response data as json you can do the following.

var json = pm.response.json();

Listed below are some examples of convenient functions for asserting on data.

• pm.response.to.be.ok;
• pm.response.to.be.redirection;
• pm.response.to.be.serverError;
• pm.response.to.be.json;
• pm.response.to.not.have.jsonBody("error");
• pm.expect(json.results).to.have.lengthOf(1);
• pm.expect(json.results[0].name).to.equal("viktor");
• pm.expect(pm.response.responseTime).to.be.below(100);
• pm.expect(pm.response.code).to.be.oneOf([201,202]);

Request and response properties

The Postman Sandbox environment gives you access to the request object while writing scripts. It is important to note though that the object request is read-only and updating variables will have no effect. The request object contains the following.

• data – a dictionary of form data for the request. request.data["name"]=="viktor"
• headers – similar to the data object, it is a dictionary where you can retrieve the values by providing the key.
• method – GET/POST/PUT and etc.
• url – URL for the request.

Then we also have response related properties, these are only available in the test script section.

• responseBody – a string that contains the response of the request. This data can be with JSON.parse and xml2json in order to work with the data.
• responseTime – the amount of time it for the response
• responseCode – code for the response, an object which consists of code, name and details.
• tests – an object that you can populate. The sandbox will treat each propery of the object as a boolean test.

Sending asynchronous request

Sometimes you want to be able to send requests during your tests as well, for example, you could want to make sure that request updated the database properly. To do this, you could add some assertions inside an asynchronous request. The Postman TEST API provides this functionality.

pm.sendRequest("https://staging-server:10000/api/person/viktor", function(err, resp) {
  var person = resp.json();
  pm.test("Person was updated correctly", function() {
    pm.expect(person.city).to.equal("stockholm");
  }
} 

Newman limitations

One of best things about Postman is that you can run your collections with environments in Newman. However, there are some limitations that you should be aware of. Some stuff only works in Postman as of now, this might of course change in the future though. Some functions around cookies only work in Postman. In order for the cookies function to work the Interceptor has to be enabled, which is why it doesn’t work in Newman.

• responseCookies – returns all the cookies in an array for the domain.
• postman.getResponseCookie(string) – gets a response cookie with a given name.

Final words

Hopefully, after reading this, you have a couple of more tools in your toolbox for testing your software. Postman is a great tool for making sure your software behaves the way you intended it to. Writing automated tests is very straightforward in Postman, and these tests can be used in Newman for integrating them into your CI environment. But, do not forget that it isn’t exclusive to testing only. It is a tool that can be used for development purposes as well, test-driven development and Postman go perfectly together. Start with writing assertions on a REST endpoint that you intend to create, plan ahead what you want the response to be like, and later make the tests go green by writing the necessary code.