API testing using Postman, Newman and Teamcity

If you are building APIs and not familiar with Postman you are missing out

Most web projects currently follow a service oriented architecture and may include integrations with several different business systems. These integrations are normally not done point-to-point, but rather abstracted away through a middleware layer to promote:

  • Security

  • Reliability

  • Manage and monitor integrations centrally

  • Abstract and perform orchestration

  • A convenient way to queue tasks should you be worried about throttling load and retrying failed attempts.

We always use Postman to test our APIs - its an excellent productivity tool and also includes the ability to test API responses. I would highly recommend working through the material and adopting it in your toolchain: https://www.getpostman.com/docs/

Having a postman suite and test harness is amazing for quickly and easily testing code, however it’s still reliant on someone taking the time to actually execute the tests and review the results.


Enter Automation

It is standard procedure for our teams to use Teamcity to build and deploy code to QA/UAT and production servers. As such, it's a great opportunity to test deployments as they happen.

Postman has a CLI companion app called Newman to help with this exact situation.

For this example I have assumed:

  • You have a git repo already set up

  • You have Teamcity already set up

  • You have the repo attached to a Teamcity project and a VCS trigger that runs when you commit

  • You have the Node.js build runner for Teamcity installed

  • You have a postman test collection and environment and have exported them to json and checked in the files into your repo. The files are called "postman_collection.json” and “postman_environment.json” in our example.

  1. The first step to setup Teamcity is to install the Newman runner via NPM. For this, you create a new package.json file that describes your project and its dependencies. Now, check-in this file into your repo.


 "name": "API-Newman-Tests",
 "version": "1.0.0",
 "description": "NPM package install Postman/Newman so we can run tests from the CI server",
 "author": "Ettienne Gous",
 "dependencies": {
   "newman": "^3.8.3"

2. Setup a new step in your Build to run NPM install


3. At this stage, you have installed Newman locally however it has been installed inside of the node_modules directory and can’t be executed from the path the Teamcity build runner is in. The command below alters the PATH so Bewman can be executed from anywhere and then runs the test. To run Newman, you pass in the test collection, the environment file and some formatting settings.

SET PATH=%PATH%;./node_modules/.bin 
newman run postman_collection.json -e postman_environment.json -r junit 
--reporter-junit-export test-results.xml --disable-unicode --no-color 

4. Newman will execute and give an XML file as the output of the tests, the last step is to add a “Build Feature” to the configuration and collect the test results in Teamcity so you get structured and detailed results about which tests passed / failed.


5. That’s it! The next step will be to either set a schedule on this runner and automatically test your APIs at set intervals OR maybe run this test suite after your API code deployment completes.


Want to talk platform delivery?