In Part 1: Automate getting an Identity Cloud Service Access Token in Postman I covered using a Pre-request script to automate getting an Access Token from Identity Cloud Service in order to successfully be authorized to send REST API requests. Then in Part 2: Using Postman Runner with Identity Cloud Service I built on this Pre-request script to enhance the script to get data from a CSV that would play a role in using Collection Runner, and in addition brought in how we could use the Tests script to grab data from the JSON response. Now in this article I am going to show you how we can use all of what we learned with Newman in order to execute a collection similar to Postman Runner from the command line.
Simply put, Newman is a tool to run a Postman Collection Runner from the command line. If you remember in Part 2: Using Postman Runner with Identity Cloud Service, we ran our Collection in Runner to execute all our requests in the Acme IDCS Collection. Using Newman, we can do the same thing, but from a command line. Why would you want to do all this work from a command line? Maybe you want to run several requests with thousands of users from a CSV file within a terminal on Linux vs doing it through a GUI on your Desktop. What about scheduling a cron job to kick of a lot of operations at some time you don't want to impact a group of users. You can decide what is best for you, but I want to provide the insight on Newman so you can decide what makes sense to use, Newman or Runner. Having options is always a good thing.
Newman can be installed on Windows, macOS, and Linux. There is a lot of information out there already for Windows and macOS that explain the requirements for installation, but for Linux it can be a little more challenging even though there are still various articles. Since I think the most value is to run Newman on Linux for Enterprise users, I am providing all the details on how to install Newman on Linux. Plus I even created a script to automate the install of Newman on Linux that determines if you are running RHEL6/OEL6 or RHEL7/OEL7.
Before installing Newman you are required to install Epel and Node.js, plus another package that helps with for reporting. Below is a summary of how to manually install all this in the exact order; this requires that you be root. I mentioned a script, so if you are interested in using a script please download install_newman.sh.zip. Just be sure to review it so you feel comfortable with what it is doing.
# Installing Newman on RHEL6/OEL6 or RHEL7/OEL7 # INSTALL AS ROOT # 1st - Determine OS If RHEL6/OEL6 then do this…. EPEL_RELEASE="https://dl.fedoraproject.org/pub/epel/epel-release-latest-6.noarch.rpm” If RHEL7/OEL7 then do this… EPEL_RELEASE="https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm" # 2nd - Install Epel cd /tmp yum install -y repolist wget $EPEL_RELEASE yum install -y epel-release-latest-6.noarch.rpm # 3rd - Install NodeJS (Note: curl command will evaluate system and take 30 seconds) curl -sL https://rpm.nodesource.com/setup | sudo bash - yum install -y npm --enablerepo=epel npm config set strict-ssl false npm install n -g n latest # 4th - Install Newman npm install -g newman # 5th - Check versions node -v <---- should return v10.9.0 npm -v <---- should return 1.3.6 newman -v <---- should return 4.1.0 # 6th - Install Reporters npm install -g newman-reporter-teamcity
Verify all the components listed above in step 5 have been installed by running the check version options for each component, node, npm, and newman. As long as you get a nice version output that matches or is newer we are good to go.
Now that we have Newman installed we need a Collection, Environment, and a CSV to kick things off. I am assuming you have the Acme IDCS Collection and Acme IDCS Environment along with the test_user.csv file from Part 2: Using Postman Runner with Identity Cloud Service and if not no big deal. We just need to export these from Postman by doing the following.
STEP 1 - From Postman select the Acme IDCS Collection and a little to the right of it you should suddenly see an Ellipsis appear, click on it and select Export, then save the Collection some place on your Desktop.
STEP 2 - Now similar to step 1 export your Postman Environment by selecting the Gear icon in the top right, then select the Environment you choose; i.e. Acme IDCS Environment, use the Export button and then Save the environment to the same location on your Desktop.
STEP 3 - Either use the test_user.csv file from our Acme IDCS Collection sample from Part 2: Using Postman Runner with Identity Cloud Service or your own, just make sure it has been modified to reflect actual users in your Identity Cloud Service tenant including all the values for "username","givenname", and "phonenumber". Note the "appRoles" column in this case will not be used in the Acme IDCS Collection because it has not been defined in the PATCH request, so you can ignore it. If you do want to try the appRoles example on your own feel free to, just make sure there is a custom schema defined as an array has been created in your tenant.
STEP 4 - Copy the three files, Collection, Environment, and CSV files to your Linux box that you installed Newman on.
OK, that is it, four simple steps. You are ready for launch.
Now for the fun part. Use the following command to run Newman which as you can see will use our Collection, Environment, and CSV file with some additional parameters that are for reporting and capturing a log. If the Postman Collection and Environment file names have spaces in them, be sure to enclose quotes around the file names. I guess optionally you could shorten the file names too. Either way we want to make sure Newman understands the file names because if there are any spaces in the names and we don't encapsulate the name with quotes it will get truncated and Newman may get confused.
As a note, the "-e" sets the environment, the "-d" tells us what data file or CSV to use, the "-n" is for number of iterations which is how many data rows to process, and the other parameter options for reports is to create a report that will hold all the requests created. I want to mention the "-n", which is the number of iterations is the number of data rows. For example the first row should be the headers, then the remaining rows is the data. For example if the CSV file has 1000 rows and row 1 is the headers, then "-n" would be 999.
newman run "Acme IDCS Collection.postman_collection.json" \ -e "Acme IDCS Environment.postman_environment.json" \ -d test_users.csv -n 5 \ --reporters cli,json \ --reporter-json-export report.json | \ tee report.log
Once you run the above command you should see something similar to the following graphic.
After Newman runs our collection you will be left with a couple reports you can review; reporter.json and report.log. The report.log contains the same output you saw on the terminal screen when you ran newman. This log file is helpful for troubleshooting because you can include console.log comments in the Pre-request and Tests scripts that are output, how this was added was mentioned in Part 2: Using Postman Runner with Identity Cloud Service; e.g. console.log("blah") mentioned in the last article. So if you keep that in mind you can add your own console logging to debug issues or just use it for keeping track of any exceptions you want to consider.
You may want to remove Newman...I understand, so sad. Well I won't keep you so here are the steps.
# Removing Newman on RHEL6/OEL6 or RHEL7/OEL7 # RUN AS ROOT # In reverse order # 1st - Remove the Reporters (You had your chance.) sudo npm uninstall newman-reporter-teamcity -g # 2nd - Remove Newman (R.I.P Newman) sudo npm uninstall newman -g # 3rd - Remove NodeJS (Bye Bye, it was good while it lasted.) sudo npm uninstall npm -g # 4th - Remove Epel (Poor Epel, she was so sweet.) sudo yum remove -y epel-release
If you run into issues removing anything you may need to search for answers because there could be a number of things that I can't include for troubleshooting within the scope of this article. Good luck.
This completes the final part 3 article and I hope it will be useful. You could take this a step further, for example break a large CSV file that maybe have hundreds or thousands of rows into separate smaller files, and then write a shell script that can iterate through the CSV files to run Newman along with individual CSV file names. Your options are only limited by your imagination. Good luck and I hope you enjoyed all three parts of this series.