API development is one of our day to day activities and we are constantly trying to evolve just as the API is evolving. Starting on a freshly new created API or development on an already existent version, we accompany this process by keeping it tested in our continuous integration. Hereby we assure ourselves the API meets our quality standards and is easily shippable/deployable. In various projects dependencies to third party API’s are present and just as our own version we would like them to be tested.
Not every third party API comes fully (unit) tested. Yet we want to know at a certain input what the exact output is. A tool that helps us a great deal is Postman, www.getpostman.com. Postman is a powerful HTTP client, installed as a Chrome app, to help test web services easily and efficiently. Postman lets you craft simple as well as complex HTTP requests quickly. It also saves requests for future use so that you never have to repeat your keystrokes ever again. This tool isn’t specific for testing any third party API but is also extensively used in testing our existing API’s.
Postman has a feature to save requests for future use, so if we could save them on a central spot others can benefit from these tests. It would be even better if these can be added to our continuous integration. This is where Newman kicks in.
Newman is a command-line collection runner for Postman. It allows you to effortlessly run and test a Postman collection directly from the command-line. It is built with extensibility in mind so that you can easily integrate it with your continuous integration servers and build systems.
Newman is built on Node.js and just by following the getting started you can be up and running in just a matter of seconds. At this point it’s easily to create a collection file needed as input parameter for Newman. It can be done by manually creating the file in you favorite editor or just by using Postman and export the collection.
Underneath an example of a login via Basic Auth on a third party API separated in a collection file and an environment file. Beneficial to this setup is that it’s easy to differentiate between various environments e.g. development or acceptance.
thirdparty-api-collection.json
thirdparty-api-environment.json
Used command
newman -c thirdparty-api-collection.json -e thirdparty-api-environment.json
Output
Iteration 1 of 1 200 1858ms Login
As you can see from the gists, the key value pairs from the environment are used for replacements in the collection file thus allowing us to be flexible in the environment to test.
Newman, by default exits with a status code of 0 if everything runs well i.e. without any exceptions. Continuous integration tools respond to these exit codes and correspondingly pass or fail a build. You can use -s flag to tell Newman to halt on a test case error with a status code of 1 which can then be picked up by a CI tool or build system.
Awesome, so by adding a test case like
"tests": "tests[\"Status code is '\"+responseCode.code+\"' where we expect 200\"] = responseCode.code === 200;"
at line https://gist.github.com/mstalfoort/d84d6782adcfb8f860db#file-thirdparty-api-collection-json-L18 and appending the “-s” to our command we see the following output
Iteration 1 of 1
200 1858ms Login
✔ Status code is '200' where we expect 200
Thus, we our now able to automatically test our (third party) API’s, accompany it in our continuous integration and halt on error if needed.
