Postman collections: Making API testing great again!

Turning shaky code into future-proof software

Over the past years, we moved more and more towards web-oriented architectures, connecting to services in order to provide information. Along with the evolution of testing tools and development methodologies we can build crazily robust software. However, it happens that sometimes we will not build unit tests because of project constraints. Those reasons often go from time pressure on a project to laziness but I am not here to judge.

Still, when you build a web service there is a way to ensure it works properly after implementation without doing a huge refactoring. I do not endorse not build unit tests and consider myself an herald of test driven development. That being said I am here to offer a solution for those who wrote code far from the 100% test coverage. This solution is to build API tests which is extremely easy using Postman. At least once your API tests are built you can then refactor bit by bit your code so that unit tests can be added at a later stage.

Now you can see this post as the first one of my future-proof series where I will introduce you to Postman collections and how to build flexible tests with them.

Requirements

This document has been written assuming that you have a basic knowledge of Javascript, JSON and web requests. If you do not, please feel free to visit these to be up-to-date:

W3C Javascript tutorial (Beginner): https://www.w3schools.com/js/
W3C JSON introduction (Beginner): https://www.w3schools.com/js/js_json_intro.asp
HyperText Transport Protocol norm (Advanced but readable): https://www.ietf.org/rfc/rfc2616.txt

Using postman makes it way easier and pleasant. Download it if it’s not done yet and you can follow through some examples later.

Creating a scenario

Create a request

Let’s start with something simple, create a new tab on Postman. Then in the textfield containing the placeholder `Enter request URL` type “http://echo.jsontest.com/ping/pong“. When it’s done press “Send” and you should get something like the next screenshot.

Save your request in a new collection

Now that your request is created you can save it by pressing “Save” and postman will ask you if you want to create a new collection, enter the collection details and press “Save”. Sounds repetitive but it’s the proof that they remain consistent in terms of UX.

Congratulation you just created your first Postman collection! If it is not your first then you just wasted 5 minutes of your life that you will never get back and even more by reading this whole sentence. And if you did it properly you should see this in your “Collections” tab:

Before moving into the whole Collection Runner thing we will add a test in the first request and create a second request using the response of the first one.

Adding tests

So now you will click on the “Tests” tab and you can see on the right that there is some tests snippets to help you writing tests faster. Let’s select two of them “Status Code: Code is 200” and “Response body: JSON value check”. You should now see this:

As you may notice, Postman tests are simple Javascript with some utility methods and variables that allow you to write simple yet powerful tests. This enables you to write very complex tests verifying every bit of your response. Then you can add tests around the response time, the response code the type your receive, etc.

The status code test does not need to change as the expected response code is 200 here. You need to replace “Your test name” with “Test ping value is pong”, and `jsonData.value === 100` with `jsonData.ping === “pong”` now you should get this:

Now press “Save”, then “Send” and if you followed everything properly you should see the following:

Now you see you got the same response, and you can see “Tests (2/2)” which means that both tests passed. If you click on the Tests tab you will see the labels of the passed tests “Status code is 200” and “Test ping value is pong”:

Congratulations, you ran your first tests on Postman. If not, you wasted again some time of your life, yes it’s truly gone.

Adding a global variable for later use.

Now let’s add another request in our collection, but first we will set a global variable from the Ping pong request. Let’s go back to the “Tests” tab of the Ping pong request. In the snippets list on the right select “Set a global variable”.

From there you need to replace “variable_key” with “pingValue” and “variable_value” with jsonData.ping. Now if you press “Send” again the request is sent and the global variable is saved, click on the eye button to see it.

You can see the variable was set so now let’s move on to create the request we will use it in.

Duplicating a request and using global variables

Duplication is quite easy, all you have to do is go in your collection tab, click on the 3-dot button next to your Ping pong request and select duplicate.

Then you can rename your duplicated method “Ting pong”.

Now click on your “Ting pong” to see it in the builder, you can update the url from “http://echo.jsontest.com/ping/pong” to “http://echo.jsontest.com/ping/{{pingValue}}”. Putting pingValue between those brackets allows you to access any global or environment variable. It works as long as you try to access these values from request url, headers or body. To access a global variable from the pre-request script or the tests you use globals.variable_name. Here we will also update the test to retrieve pingValue, to do so you will replace “pong” with `globals.pingValue`.

Now if you run your request again all tests will pass again.

Now if you clear your globals, and try to run again the test for ping value will fail since it will send the string literal “%7B%7BpingValue%7D%7D”. This happened because you did not set any global or environment variable this time. So it will try to compare that with a variable that doesn’t exist which results in the test failing as you can see below.

However if you run again your Ping pong request, it will set the pingValue global variable therefore when you run the Ting pong request again, your test will pass again until you clear the variables.

The collection runner, finally

Now it is almost time to play with the collection runner. But first you need to know that the collections run requests based off request title alphabetic order so to ensure they run in the order you prefer I strongly advise you to use numbers for the ordering as below:

Yes you did not need this here since alphabet always places Ping pong before Ting pong. Same goes for collection folders on which I will not expand as they are really straightforward to use. If you want to have multiple scenarios in your collection that should not rely on each other you would be wise to group your requests in folders. Not only because it is much cleaner but also they can be ran individually if needed. On a 2 request collection it will not be an issue but the last one I created has 49 with 100s tests.

So now let’s go have a look at that collection runner, on your collection press on the arrow.

You will then see this, obviously the option you will select is “Run”.

The collection runner will then open after a couple seconds. You can simply press “Start Run”:

After the run you will see your collection run results.

Congratulations now you know how to write test scenarios using Postman.

Creating a new environment

Environments are pretty useful to write collections faster by using variables at any level. It can go from urls to tests values and so on. Using multiple environment is frequent for complex systems with multiple deployments and/or gateways.

Now we will create a simple environment and set the ping service url that we will use in both requests.

First of all, click on the gear icon then “Manage environments” > “Add”. Once you get there you can name your environment and setup the values you need.

Here we will name it “Postman tutorial environment” and add a key pongServiceUrl set to the value “http://echo.jsontest.com/” then press “Add”.