July 10, 2016

Introduction to API Testing with Postman and Newman

Postmanhttps://www.getpostman.com/ ) is tool they use at work to test APIs... along with Swagger, Pact, and Java with Apache HTTPComponents. Postman comes in two versions ... as a Chrome app or a Mac app. They seem similiar, except the Mac app "is packaged with add-ons that make request capturing and cookie handling seamless" according to Postman's documentation.

What is an API?

"Application program interface (API) is a set of routines, protocols, and tools for building software applications. An API specifies how software components should interact and APIs are used when programming graphical user interface (GUI) components. A good API makes it easier to develop a program by providing all the building blocks. A programmer then puts the blocks together". - Webopedia

Need to get up to speed on APIs?

REST API Concept and Examples:

Brought to you by JelledTV's WebConcepts YouTube channel, "This video introduces the viewer to some API concepts by making example calls to Facebook's Graph API, Google Maps' API, Instagram's Media Search API, and Twitter's Status Update API.

If you want to find many other sites that use APIs, go to ProgrammableWeb.com.

... They also mention how to use this new tool that came out... Postmanhttps://www.getpostman.com/

Learn Tools From the Creators 

It's very important as a new automation developer to learn how to teach yourself the various toolsets you use day-to-day.

Don't wait for one-on-one instruction from a senior member of the automation team to show you all the ins-and-outs of a tool. Don't wait for the company to send you on an expensive training class.

We are living in a great time to be a software developer. The open-source movement that I first heard about as a Computer Science undergrad in the 1990s bore great fruit. If you are trying to learn a new tool, you can go right to the source... and find the source code the tool is built on, stored in GitHub: http://www.github.com/. Seminars, Webinars, and instructional YouTube videos usually can all be found on the Internet, available for free. And to the new creators of these tools we use: Documentation matters. Instructions on how to use the tool matter. You don't need another third-party website peddling courses telling you how to use a tool. You can get the information from the creators themselves.

... Okay, sorry for getting on my soap box. :) Back to the regularly scheduled blog.

Installing and Using Postman

Postman documentation is available at https://www.getpostman.com/docs/.
And yes, Postman Labs does have a GitHub site. https://github.com/postmanlabs.

Postman: Installation and Setup

How to use Postman API Response Viewer:

Working with APIs, the Java Way

Back in February, we talked about RESTful Testing, using as an example Stripe, a credit card processor.

RESTful Testing with Stripe:

Working with Apache HttpComponents, you could work with APIs, but it ain't pretty. You had to know Java. You had to know how to use GSON to convert the JSON file data into a Java object you could use. You needed a lot of exception handling. A quick-start tool, it was not.

Even if you know how to read a JSON file (JavaScript Notation), Postman does have a bit of a learning curve, but it does seem easier.

Let's continue using Stripe as the API Endpoint we are going to test against. I really love the documentation in the Stripe API Reference! https://stripe.com/docs/api

Testing APIs the Postman Way

Let's go to the Stripe API.

  • Go to the URL: https://api.stripe.com/v1/charges
  • When we see the Login popup, let's hit cancel. 
  • It should not allow you to log in.
  • It should throw an error that looks like:

  "error": {  
   "type": "invalid_request_error",  
   "message": "You did not provide an API key. 
   You need to provide your API key in the Authorization header, 
   using Bearer auth (e.g. 'Authorization: Bearer YOUR_SECRET_KEY'). 
   See https://stripe.com/docs/api#authentication for details, or we 
   can help at https://support.stripe.com/."  

If we do the same thing in Postman, entering into GET: https://api.stripe.com/v1/charges and hitting the SEND button without setting up any authorization, we should get the same result:

Note that the HTTP Status Code returned is "401 Unauthorized".

  • Request Name: Call the test something like: "accessStripeApiWithoutLoggingIn"
  • Create new Collection called: StripeAPI. 

Now, let's create a test to make sure that you cannot log into the API without proper authorization:
  • Select the "Tests" tab.
  • Under "Snippets" we can scroll down until we see a code snippet similar to what we are looking at. 
  • Select: Status code: Code is 200 (this means everything is okay). 
  • Alter the JavaScript pre-generated from "200" to "401" and SAVE.

Need  list of Status Codes? See https://en.wikipedia.org/wiki/List_of_HTTP_status_codes

The test code now reads:
 tests["Status code is 401"] = responseCode.code === 401;  

Now, when you go to the Runner (the Collection Runner) select START TEST, you can see everything is green! It passes. You ran your first API test!

We now have one test in a Collection called StripeAPI. Let's create a new folder called "Authentication" so we can group the test in something easily understandable.

Export and Downloading the API Test

Following Postman's documentation on Collections: http://www.getpostman.com/docs/collections

"Collections can be downloaded as a JSON file which you can share with others or shared through your Postman account. You can also share collections anonymously but it is strongly recommended to create a Postman account when uploading collections. This will let you update your existing collection, make it public or delete it later".

Let's Export the collection:
  • Under the Collections tab, next to StripeAPI, select the "..."
  • Select "Export", and chose to save it as Collections version 2. 

You can see a file called "StripeAPI.postman_collection" has been created. Let's save it under our root folder, in a directory called "api" and a subfolder called "stripe". /api/stripe/StripeAPI.postman_collection.

Opening StripeAPI.postman_collection, the file we just created, you can see that the entire test is a JSON file.
      "variables": [],  
      "info": {  
           "name": "StripeAPI",  
           "_postman_id": "7f318f47-9848-4333-057c-58fcaf7ae8d0",  
           "description": "",  
           "schema": "https://schema.getpostman.com/json/collection/v2.0.0/collection.json"  
      "item": [  
                "name": "Authentication",  
                "description": "",  
                "item": [  
                          "name": "accessStripeApiWithoutLoggingIn",  
                          "event": [  
                                    "listen": "test",  
                                    "script": {  
                                         "type": "text/javascript",  
                                         "exec": "tests[\"Status code is 401\"] 
                                                   = responseCode.code === 401;"  
                          "request": {  
                               "url": "https://api.stripe.com/v1/charges",  
                               "method": "GET",  
                               "header": [],  
                               "body": {  
                                    "mode": "formdata",  
                                    "formdata": []  
                               "description": ""  
                          "response": []  

We wrote our API test. We exported it as a file. How would we run it?

... Oh, hello Newman.

Yes, it is a Seinfeld reference. The postman that Jerry Seinfeld did not like was called "Newman".

Running the API Test

Newman GitHub Site: https://github.com/postmanlabs/newman

Let's walkthrough setting up an environment to run Postman's API tests.

Precondition: Node.js. Newman is built on Node.js, and we install Newman using Node.js's Package Manager called NPM, so Node.js will need to be installed.

What is Node.js?
"Node.js is an open-source, cross-platform runtime environment for developing server-side Web applications. Although Node.js is not a JavaScript framework,[3] many of its basic modules are written in JavaScript, and developers can write new modules in JavaScript. The runtime environment interprets JavaScript using Google's V8 JavaScript engine [...] Node.js was originally written in 2009 by Ryan Dahl. The initial release supported only Linux. [...] In 2011, a package manager was introduced for the Node.js environment called npm. The package manager makes it easier for programmers to publish and share source code of Node.js libraries and is designed to simplify installation, updating and uninstallation of libraries [...] In June 2011, Microsoft and Joyent implemented a native Windows version of Node.js. The first Node.js build supporting Windows was released in July 2011". - Wikipedia

Do you have Node on your system? Open a command prompt and type: node --version

The current version of Node is 4.4.7. If you have below version 4, go to https://nodejs.org/en/download/ and download install the Windows or Mac version that you need.

Once Node.js is installed, we need to install Newman by running in the Command Line:
 npm install -g newman  

Let's run Newman, execute the test, then store the results in an output file called "outputfile.txt".

  • Go to the directory where Newman was installed. Since I use Windows at home, newman was installed at C:\User\tmaher\AppData\Roaming\npm\. To use newman, I can either go to that directory or go into the Windows Environment Properties and add that to the Path variable.
  • Run on the Command Line: 
 newman -c C:\api\stripe\StripeAPI.postman_collection.json -o outputfile.json  

Success! The test ran from the command line. It went to the Stripe API, attempted to log in without authorization, just as expected!

Examining the output, we see one huge JSON file. What if I want to see what things look like at a glance?

 newman -c C:\api\stripe\StripeAPI.postman_collection.json – H Reports.html   

... Okay, that is more like it!

Where to Go From Here?

Use Newman in Docker!

Connect Newman with Jenkins:


Want to run your API test:
  • After every new code change is added to your project, such as with a smoke test?
  • Once an hour?
  • On a QA Environment resembling your production environment to test the release candidate? 
Couple Postman + Newman + Jenkins.

Add Node and Newman to Your Build Script

Want to run your tests from your Build.Gradle file? Take a look at the Gradle-Node-Pluginhttps://github.com/srs/gradle-node-plugin. "Releases of this plugin are hosted at Bintray and is part of the jCenter repository".

The site provides sample code for you to:

  • Configure the plugin:

 plugins {  
  id "com.moowork.node" version "0.13"  

  apply plugin: 'com.moowork.node'

  • Configure Node:

 node {  
  // Version of node to use.  
  version = '0.11.10'  
  // Version of npm to use.  
  npmVersion = '2.1.5'  
  // Base URL for fetching node distributions (change if you have a mirror).  
  distBaseUrl = 'https://nodejs.org/dist'  
  // If true, it will download node using above parameters.  
  // If false, it will try to use globally installed node.  
  download = true  
  // Set the work directory for unpacking node  
  workDir = file("${project.buildDir}/nodejs")  
  // Set the work directory where node_modules should be located  
  nodeModulesDir = file("${project.projectDir}")  

Feel free to take a look!

Happy Testing!

-T.J. Maher
Sr. QA Engineer,

// BSCS, MSE, and QA Engineer since Aug. 1996
// Automation developer for [ 1.5 ] years and still counting!
// Check out Adventures in Automation and Like us on Facebook!


Excelr Tuhin said...

keep up the good work. this is an Ossam post. This is to helpful, i have read here all post. i am impressed. thank you. this is our Data Science course in Mumbai
data science course in mumbai | https://www.excelr.com/data-science-course-training-in-mumbai

Martyn said...

Digital Marketing Training Institutes in Chennai
Digital Services Company in Chennai
SEO Agency in Chennai
SEO Specialist Chennai
CRO Agency in Chennai
PHP Development Services in Chennai
Website Design in Chennai
Ecommerce Development Chennai
Digital Technology Company

Rohini said...

After reading your article I was amazed. I know that you explain it very well. And I hope that other readers will also experience how I feel after reading your article.
data science courses

EXCELR said...

Attend online training from one of the best training institute Data Science

Course in Hyderabad

Gaurav said...

Really nice and interesting post. I was looking for this kind of information and enjoyed reading this one. Keep posting. Thanks for sharing.
cyber security course training in indore

360digitmg said...

Awesome blog. I enjoyed reading your articles. This is truly a great read for me. I have bookmarked it and I am looking forward to reading new articles. Keep up the good work!
360DigiTMG ai course in ECIL

Data Science Hyderabad said...

Great blog with valuable resource waiting for next update thank you.
Data Science Course in Hyderabad 360DigiTMG

Data Science said...

Great work found your blog very useful, information provided was excellent thanks for sharing.
Data Analytics Course Online 360DigiTMG

Business Analytics Course said...

Thank you for your message. I've been thinking about writing a very similar article for the last few weeks, I'll probably keep it short and to the point and link to this article instead if that's interesting. Thank you.

360DigiTMG Business Analytics Course in Bangalore

Data Analytics Course said...

Some really good points you wrote here ... Great things ... I think you raised some really interesting points. Keep up the good work.

360DigiTMG Data Analytics Course in Bangalore

hrithiksai said...

Very nice blogs!!! i have to learning for lot of information for this sites…Sharing for wonderful information.Thanks for sharing this valuable information to our vision. You have posted a trust worthy blog keep sharing, data sciecne course in hyderabad

abid said...

A good blog always comes-up with new and exciting information and while reading I have feel that this blog is really have all those quality that qualify a blog to be a one.
about us

Data Science Training said...

Excellent blog with great information found very valuable and knowledgeable thanks for sharing.
Data Science Training in Hyderabad

Data Science Institute In Banglore said...

This type of very helpful article. Very interesting to see this article.
Data Science Training Institute in Bangalore

Best Data Science Courses In Bangalore said...

Very wonderful article. I liked reading your article. Very wonderful share. Thanks ! .

Data Science Course In Bangalore With Placement

Ethical Hacking Course said...

Very informative article with valuable information found resourceful thanks for sharing waiting for next blog.
Ethical Hacking Course in Bangalore

Data Science said...

Great article with valuable information found very resourceful thanks for sharing.
typeerror nonetype object is not subscriptable

PMP Training said...

I am more curious to take an interest in some of them. I hope you will provide more information on these topics in your next articles. PMP Training in Hyderabad

DataScience Datascience said...

I have to search sites with relevant information ,This is a
wonderful blog,These type of blog keeps the users interest in
the website, i am impressed. thank you.
Data Science Course in Bangalore

My Safari Dubai said...

Leave the city behind & drive with us for a Thrilling drive over the Desert Dunes & Experience a lavish dinner with amazing shows in our Desert Camp.
desert safari dubai

DataScience Datascience said...

I have to search sites with relevant information ,This is a
wonderful blog,These type of blog keeps the users interest in
the website, i am impressed. thank you.
Data Science Training in Bangalore

PMP Institute said...

I have to search sites with relevant information ,This is a
wonderful blog,These type of blog keeps the users interest in
the website, i am impressed. thank you.
pmp training in bangalore

Tableau Course said...

Absolutely an extraordinary informative article. Hats off to you! The details which you have furnished is quite valuable. Learn best Tableau Course in Bangalore

360digitmg said...

I truly like you're composing style, incredible data, thankyou for posting.
data science training

PMP Training said...

I will very much appreciate the writer's choice for choosing this excellent article suitable for my topic. Here is a detailed description of the topic of the article that helped me the most. PMP Training in Hyderabad

prathyusha said...

Truly overall quite fascinating post. I was searching for this sort of data and delighted in perusing this one. Continue posting. Much obliged for sharing.business analytics course