How to write automated tests for APIs using Postman – Part 1

One of Postman’s most powerful features is its ability to run automated tests on your requests. To get you started quickly we are publishing a two-part tutorial series, where we’ll go from a simple test to writing complicated tests and running them inside the Collection Runner. This is the first tutorial in the series.

Test editor

When you open Postman, you should see the ‘Tests’ section in the request editor area.

To the right of the test editor, there is a list of snippets. You can click on any snippet title and the corresponding code snippet will be appended to the test editor. This makes writing simple tests extremely fast.

This list will be updated as Postman’s test capabilities improve. You’ll also be able to add custom snippets in a future version.

Writing a simple test

Let’s write a simple test to give you a feel of how everything fits together. We’re going to use a new demo API that we have set up – echo.getpostman.com, and which you can use while following this tutorial.

Postman tests are written in Javascript. Postman expects the special tests object to be populated with a description and the result of the test. Postman renders the results in the “Tests” tab as well as in the Collection runner, depending on the boolean values present in this dictionary.

For our first test, we’ll send a GET request to http://echo.getpostman.com/get to find out the status of the API. We’ll check if the status code is 200, and if the Content-Type header is “application/json”. Follow the steps below:

1. Set the URL to http://echo.getpostman.com/get
2. Scroll down in the snippets editor and click on the “Status code: Code is 200” snippet.
   
3. We do not need to make any changes in this case. Let’s send this request right away.
4. Switch to the “Tests” tab. We see that this test has passed as the correct status code is returned.

1. Just to see how things look when the API does not behave as expected, let’s change the status code in the test to 201 and send the request again.

1. In the tests tab, Postman tells us that the test has failed (expectedly).
2. Let’s add another test for the Content-Type header. We want to make sure that the Content-Type header exists and it is equal to “application/json”
3. responseHeaders is a dictionary available inside the Postman test sandbox which contains all the headers returned in the response. Select the “Response headers: Content-Type header check” snippet.
4. We’ll change this test a bit. We’ll assign the result of the responseHeaders.has() function to a variable contentTypeHeaderExists.
5. Remember that as Postman tests are just Javascript code, we can add conditionals like if to our code. We’ll first check if contentTypeHeaderExists is true. If yes, we’ll check if it’s equal to application/json.

Write the following snippet in the test editor:

var contentTypeHeaderExists = responseHeaders.hasOwnProperty("Content-Type");

tests["Has Content-Type"] = contentTypeHeaderExists;

if (contentTypeHeaderExists) {
    tests["Content-Type is application/json"] = 
      responseHeaders["Content-Type"].has("application/json");
}

This is how it should look like inside Postman:

1. Send the request.
   

Everything seems to be fine with this API as all our test cases have passed. In case, something breaks down, these tests will fail.

And that’s all it takes. Usually API testing requires a huge amount of boilerplate code. By giving you an integrated environment, Postman aims to make this process painless.

Even if you are new to programming, it’ll just take you a few minutes to write tests with Postman. In the next article, we’ll create a more elaborate test suite. Keep following this blog for updates. You can follow Postman on Twitter (@getpostman).

The “How to write automated test with Postman” series

1. Part 1 (this article)
2. Part 2
3. Part 3

Update: See how to write tests using the newer PM API (known as the pm.*API).