Saturday, January 27, 2018

Test API Using Postman 101

Introduction

You can also read this post at DZone

Postman is one of the most efficient application to test RESTful api. Most developers write simple test and check the result of REST API. That is fine for few API, but if we have many api to test. It is better to automate these test cases. This post is an introduction to the automated testing using a simple api. There is command line version of Postman. It is called newman. I will also cover the procedure to test using newman.

The main topic of this post covers:

  • Environment
  • Simple Test Scripts
  • Setup newman
  • Test Collections

Environment And Collections

In general, you should create one testing collection for each functional area, which may have many testing case. Then, you should create environment for dev, test, sit, prod, etc, as each environment may have different configuration.

Simple Test Scripts

For the demonstration purpose, I created two test cases. The first is to get oauth2 token from my local server. The second is to validate the token. To validate the token, I will need to pass the token as query parameters. To copy and paste the token into the query parameters is not practical. In this case, I create and environment variable named: access-token-password in the first test case. And pass this variable to the second test case as the following:

https://localhost:8082/external/validate?access_token={{access-token-password}}
The syntax is self-explanatory.

The following are the details about the test script:

var jsonData = JSON.parse(responseBody);

postman.setGlobalVariable("access_token", jsonData.access_token);

postman.setEnvironmentVariable("access_token", jsonData.access_token, "OATH2");

postman.setEnvironmentVariable("access-token-password", jsonData.access_token, "OAUTH2");

tests["access_token is not null"] = jsonData.access_token !== null;

tests["token_type == bearer"] = jsonData.token_type === "bearer";

As you can see, the test script is in the form of javascript. And the meanings for each line are self-explanatory as well. I set the environment variable "access-token-password" for the environment of OAUTH2.

The following picture shows the collection, testing scripts, and the test case output

To run the the test for the collection, click the arrow, then run as show from the following picture:

From the above pictures, we see that we can run the test cases by one click and verify if all the test cases are passed. However, this kind of testing is still very much manual. We need to automated the whole procedures automatically. For this purpose, we can use the command line version of the Postman, namely, newman

Using newman

In order to use new man, we need to do three things:

  • Install newman
  • Export the collection
  • Export the environment variables

Install newman

npm install newman --global;

Export Test Collection

right click 3 dots beside the collection:
Then click Export --> Export. Save the file.

Export Environment Variables

client the tool picture on the top-right of the gui, find the collection, click the download button, as shown in the following picture:
In my cases, for the demo purpuse, I save the two files in the Download directory.
-rw-------@  1 gl17  staff   3.4K Jan 27 12:34 oauth2-demo.postman_collection.json
-rw-------@  1 gl17  staff   653B Jan 27 12:35 OAUTH2.postman_environment.json

Run Collection From Command Line

The following are the command lines:
gl17@GaryLiu17sMBP:~/Downloads$ newman run oauth2-demo.postman_collection.json  -e OAUTH2.postman_environment.json --insecure 
newman

oauth2-demo

→ username&password
  POST https://localhost:8082/external/access_token?grant_type=password&username=max&password=mule [200 OK, 374B, 402ms]
  ✓  access_token is not null
  ✓  token_type == bearer

→ https://localhost:8082/external/validate?access_token=3URNgv-o3Tu9pP9WNfEhewlrBba7CsUfwJM1nZYYq8n7SlhxWq5E13wMy2ZeOcFx2q4edPSgG7u61Hg3_rFSpQ
  GET https://localhost:8082/external/validate?access_token=raJ1KXUBR4GfbVXNBFHNcAnNUQgQ34wcZ_jo0KODNdUmX4N4Th279THfZNPkCEmKQs2mOng9zcX97DMJtIsl-A [200 OK, 171B, 5ms]
  ✓  client_id is not null
  ✓  access-token-password is not null
  ✓  Status code is 200

┌─────────────────────────┬──────────┬──────────┐
│                         │ executed │   failed │
├─────────────────────────┼──────────┼──────────┤
│              iterations │        1 │        0 │
├─────────────────────────┼──────────┼──────────┤
│                requests │        2 │        0 │
├─────────────────────────┼──────────┼──────────┤
│            test-scripts │        2 │        0 │
├─────────────────────────┼──────────┼──────────┤
│      prerequest-scripts │        0 │        0 │
├─────────────────────────┼──────────┼──────────┤
│              assertions │        5 │        0 │
├─────────────────────────┴──────────┴──────────┤
│ total run duration: 529ms                     │
├───────────────────────────────────────────────┤
│ total data received: 345B (approx)            │
├───────────────────────────────────────────────┤
│ average response time: 203ms                  │
└───────────────────────────────────────────────┘
gl17@GaryLiu17sMBP:~/Downloads$ 

That is it all. Pretty simple and straight forward.

Summary

In this post, I have covered the following topics:

  • Procedures to test RESTful API using postman and newman utilities.
  • Simple syntax on how to write test javascripts