Postman In The Pipeline: Newman Delivers

 It's not me, it's the songs. 
I'm just the postman, 
I deliver the songs....
 - Bob Dylan

Recently, I've had the chance to work on a project with some other awesome folks which has involved creating a BFF - A back end for front end service. This allows the app to access several API and aggregate calls into something the app can use, or lets the app send information to the BFF for several APIs to receive.

Part of the code coverage for the BFF was creating some simple tests with Postman around the business logic and interactions.

Learning About Postman

I did lots of reading. Lots of reading how others has done things (Danny Danton - big props for being a super help!). Eventually, I came down to a small set of tests which could give us some accuracy about our BFF pipeline and the APIs we were accessing with it.

Postman has a couple of options for this, global variables, environmental variables, and plain variables. One of the first problems I came across was gathering a variable out of an array and passing it to downstream tests, then how to handle when that variable wasn't available. Essentially error handling for Postman.

I contacted Danny Danton for his help, and based on the very small amount of information I could give him, he suggested a solution, which I managed to extrapolate into something that worked.

What we were both surprised about is that I managed to get if/else statements working in Postman! It was thought that if/else statements were no longer recognized in the last release of Postman.

Here is an example of what the end result was for handling empty array/variable issues.

Using Newman With Local Builds

Since we wanted an easy way for anyone to run the tests locally, we added Newman, so that tests could be run with the command line, and then later added to the pipeline.  Since Newman is an npm package, I worked with getting the tests to run locally using the command line before looking at adding the tests to the pipeline.

It's not as hard as it sounds and thankfully there is a ton of really good documentation around Newman.

Our command line call was pretty simple:

newman run collection.json -e environment.json

 

Adding Postman To The Pipeline

Once I had the Newman tests running, I paired with a developer on my project to see how GitLabs allowed for a Newman integration. The integration with GitLabs seemed fairly easy, but I wasn't sure how to get NPM running on a Gradle project. Newman doesn't support Gradle natively, which is unfortunate. Research was our friend in this instance.

There is one Gradle package for Newman. We didn't want to introduce Maven to the BFF to only run the Postman/Newman tests so we decided not to use it. Our next line of query led us to seeing if we could use NPM in a Gradle project, but all the solutions seemed a little too much of a hack.

Because we are using GitLabs, and it runs on containers, we are able to install Newman via NPM and run the tests every time the pipeline builds. This isn't ideal, but it's the cleanest way we could figure out to add Newman to the pipeline, but not to the application code itself.

All it took was a simple addition to the .gitlab-ci.yml file in the script section before the command line call. It looks something like this:

Integration Tests:
  stage: test:integration
  image: docker-image.registry.store.com/library/node:latest
  only:
    - master
  script:
    - npm install -g newman
    - newman run collection.json -e environment.json

UPDATE: Postman has a docker container with Newman already loaded! Check it out here!
(I'm not sure when it was added, but I found it today as I was looking through documentation. It might be easier than rolling up your own instance of Newman, but at least it's an option!)

What this does is create a docker container with newman so the tests can run, and then the docker container runs it's code against the master docker container that was created and deployed in the previous steps.

The end result is the Newman style report which can be recalled from the step whether it passes or fails. Additionally, this check serves as an additional validation of the code, besides the unit tests, which confirms that the BFF calls to the API are working correctly after the build and deploy of the code to the environment which was specified. This also serves on our project as a blocking step to the stage environment if it fails.

These were all team efforts and collaborations. Danny Dainton has some great fundamentals out there for Postman. I suggest checking it out if you are interested. I also want to thank my pairing partner for this endeavor, Avalon McRae.

I like this Newman's delivery better.