Postman — your API test runner

First of all, a little disclaimer: This post was originally written and published on January 25th, 2016 and has been migrated to medium.

Many people do not like running or writing tests. It is time consuming, sometimes frustrating and quite a repetitive work.

But WHY? you may ask.

I thought so for a long time, until I discovered a neat little application that can brighten up your day. All I wanted was a tool that helps me send HTTP requests to APIs. I stumbled across many applications like “Advanced REST Client” or “DHC — REST/HTTP API Client”. All of them do a good job, some of you may like one of them more than Postman.

I worked with Postman for about half a year until I really discovered its full potential — automated integration tests. After I discovered this feature, I paid the small fee for Postman (like ten bucks for a lifetime licence, for sceptics: you can test the full version for 14 days) and started fooling around with the feature.

Basically you can use the Postman GUI to fully customize the requests that are sent. You are able to save those requests — and the corresponding configurations — into Postman collections. Those collections serve two purposes: Reuse your requests for convenience and automated runs. After a set of requests is complete — order matters! — you can export the Postman collection into a JSON file. With that JSON and Newman (the CLI part of Postman) you can use your favourite CI to run automated HTTP requests.

Everything jolly, but where are the tests? With the paid version of Postman, there are newly two tabs available in your application: “Pre-request script” and “Tests”. In pre-request scripts, you can set variables or load stuff you need, but actually all the magic happens in tests.

After the request is completed, you can run tests and therefore check your API for failures. There is a global dictionary “tests” which can be filled with your assertions. Those assertions must be boolean and executed synchronously. Such a test scenario can be:

tests[‘Status code is 200’] = responseCode.code === 200;
tests[‘Response has a body’] = !!responseBody;

There are many libraries in the postman sandbox which will simplify your code like:

• Lodash
• jQuery
• tv4 Validator

With the tv4 validator you can use JSON schemas to validate your responses and with lodash and jquery you have the power to run more complicated tests as you like.

I prepared a little demo setup for those who want to try Postman and Newman. You can find the code on GitHub. The API is pretty dumb, it just stores a collection of objects which can be modified when a user is logged in. I chose this specific setup, because of the second feature of Newman. You can run your collection for more than just one iteration. You can even start the tests with different data for every iteration. Newman is able to run the same set of requests with different data objects — stored in a CSV or JSON array — and thus be able to test different behaviours of an API. An example could be: Get a product, update it. This little setup can be iterated 20 times and therefore simulate a real API usage.

I’ll use Postman in every project I can. Not only because it’s useful during the development process but with the automated tests feature, we can ensure quality and a stable environment for our API. I’m very happy with Postman and I’m curious about the future of this application.

And last but not least a really good reason, why you should write integration tests as well as unit tests: