Run Postman Collections Using Docker
Postman is awesome, building and running your checks through the built-in collection runner is amazing but what I like to do, once I have a stable set of requests, is to export my Collection and Environment files from the application and run them in the command line using Newman.
I have nodejs installed on my local machine so it's easy for me to globally install
newman and crack on with running the checks but some folks won't have this and probably don't want to install
nodejs on their machine.
This is where using Docker comes in handy, you can use pre-defined Images that contain everything you need to run the checks, without the need to install lots of different dependencies onto your local machines. Docker is by no means a new technology but it is newish to me so I'm kind of 'learning by doing' and creating something that works but can be updated once my own Docker knowledge increases, you have to start somewhere :).
I've created an example based repository for anyone to get an idea of how to start using your Postman Collections, created in the within the application and run these using a Docker Image.
Postman has it's own official Docker Image on Dockerhub with instructions to get you set up and started. It's really simple to get your Postman collections running with the image, straight from the command line.
This is an example taken from Dockerhub using the
docker run -t postman/newman_alpine33 run https://www.getpostman.com/collections/8a0c9bc08f062d12dcda
This command will run a basic collection that sends a few requests to httpbin and performs some checks. This example is used to show you the collection running using the Docker Image and what the output is in the terminal.
What Have I Done Differently?
I could have used the
postman/newman_alpine33 Image and that would have run my collection fine but I wanted to extend this out slightly and add a custom HTML report which gets created following the collection run. Ooh Fancy...
By wanting to do this, I needed to create my own
postman/newman_alpine33 base Image
newman versions are getting a bit old now and the latest version of the
newman-reporter-html module requires
newman >= v4.0.0 and
nodejs >= v6.x - Both of which are not part of the official Image.
Dockerfile looks like this, I needed
nodejs so I have used a version (I could just take the latest but I haven't for now) of the
node base Image and then installed the two modules 'globally' via
npm. This file also creates a new
WORKDIR and specifies an
FROM node:10.11.0-alpine RUN npm install -g newman newman-reporter-html WORKDIR /etc/newman ENTRYPOINT ["newman"]
I also created a
docker-compose.yml file to help make running the collection easier, like I said before, I'm still learning Docker so this might not be needed but I'm going with it for now. For the example, I'm using a collection and environment file from my other All-Things-Postman repo.
version: "2" services: postman_checks: container_name: restful_booker_checks build: . image: postman_checks command: run Restful_Booker_Collection.json -e environments/Restful_Booker_Environment.json -r html,cli --reporter-html-export reports/Restful_Booker_Test_Run.html --reporter-html-template reports/templates/customTemplate.hbs volumes: - ./src:/etc/newman
This file contains a few default properties
services, these are required to make it a valid
docker-compose file, I've also then added a service name of
As well as these standard file properties, I have some additional ones that are specific to my collection run:
container_name- Gives the new container a friendly name or it will pick up the default random name
build- This is building from the root dir as this is where my
image- Same reason for using a
container_name, this just gives the
command- This is the important part, it's the command that tells
newmanwhere your files are located and what output you would like after the collection run
volumes- This is equally import as it provides a link from the local
./srcdir to the
/etc/newmandir in the container
Collection Run Output On The Command Line
The default output if you're using
newman locally or using the Docker Image, is on the CLI - This will give you a simple breakdown of what happened during the collection run.
Collection Run HTML Reports
The whole reason why I'm not using the Official Image is to get a custom HTML report from the collection run - For this I'm using the
newman-html-reporter module, in order to tell
newman to use this I've added a couple of arguments to the
command property in the
docker-compose.yml file. First, we need to tell it we want to use an additional reporter, this is done using the
-r cli,html flag. This alone would be enough to create the report and save the to the root directory but I wanted it to be placed in a particular directory. For this I've used the
--reporter-html-export flag and then specified a filename and a location
After the run, the new HTML report is added to the
The standard HTML output is fine but it looks a bit boring...so I wanted to jazz it up a little bit.
We can do this by telling
newman to also use a custom HTML template, this can be customised to suit your needs. You can literally Bootstrap all the things, if you like! :) The location of the template is referenced using the
--reporter-html-template flag and then passing this a filename.
I found this custom template from tegomass but I changed a few things, to make it look a bit better....in my opinion. :)
I've added a couple more custom template examples in the
./reports dir that I've found, which all look slightly different but it's good to know that you could create a really fancy looking one, if you wanted too. :)
An example of each of the awesome templates from the repo's listed above:
Custom Template 1
Custom Template 2
Custom Template 3
To apply one of the other templates, you just need to change the filename on the
--reporter-html-template flag, within the
Running The Collection
To run this collection from the command line, assuming you have Docker running on your flavour of OS, type the following:
This should pull the
node image and install all the components you need, before running through the checks.
Following the collection run, you will still have the
restful_booker_checks container created, if you wish to removed this, you can use the following command:
docker-compose rm -f
That's it really - quite basic but hopefully it makes sense and maybe you can use some of this to create your own Postman Docker collection runs.