Newman: run and test your collections from the command line

Joyce

June 21, 2018

If you don’t already know about Newman, then hold on to your hats! Newman is Postman’s open-source tool to run and test collections directly from the command line. Powered by the same runtime that powers the Postman native apps, see how the Newman CLI can streamline your API testing.

Good, better, and best

Maybe you’re a QA engineer who wants to occasionally run your Postman tests from the command line. Maybe you’re a DevOps engineer who wants to integrate Postman tests with your CI/CD build process. 

The Newman CLI can help you run and test your collection ONCE or EVERY time you make changes. Find the best option that works for you, and let Postman free up a little more of your time to spend on something else.

Once you install the dependencies, and get started with Newman, here are some good, better, and best practices to use Newman.

Good: run Newman with a local JSON file

This option is great to run and test a Postman collection in an ad hoc manner. If you don’t have a regular CI/CD process, and just want to run a collection, then this is the option for you.

In the Postman app, click on the ellipses (…) next to the collection and select “Export” to download a JSON file of the collection. Similarly, you can download a JSON file of an environment if you’re using one.

In the same directory where the JSON file is saved, use Newman to run the collection from the command line. 

$ newman run myCollection.json

Newman supports a variety of output formats, including a human-friendly console output, as well as outputting to a JSON or HTML file. For any Postman test that fails indicating the API response is not what you expected, you can then file a bug in your issue tracking platform.

Better: run Newman with the latest collection URL

What happens if the collection changes? You might be collaborating in a team workspace with other team members making updates to the collection.

Instead of manually exporting another collection file every time someone makes an update, use the Postman API to retrieve the latest version of the collection to save time and be rest assured that you’re working off the correct version. You can do the same to retrieve the latest version of an environment, if you’re using one.

You’ll need your Postman API key for this next step.

Use the Postman API to send a request to the GET All Collections endpoint. Identify your collection’s collection_uid. Copy and paste this value into the GET Single Collection endpoint. Update the URL by adding the apikey query string parameter along with the value of your own Postman API key. Copy and paste this entire URL to run in the terminal.

$ newman run https://api.getpostman.com/collections/myPostmanCollectionUid?apikey=myPostmanApiKey

Best: integrate with your CI/CD pipeline

Now, say you have a full-fledged Continuous Integration and Continuous Delivery (or CI/CD) pipeline, and you want to run these Postman tests every time you kick off the build process.

If you want to use Newman programmatically, integrating your Postman tests with your favorite continuous integration service is the same process with Jenkins, Travis CI, or any other code deployment pipeline tool.

You will set up your CI configuration to run a shell command upon kicking off your build. The command is a Newman script that runs your collection with the tests, returning a pass or fail exit code that’s logged in your CI system.

Want to see it for yourself? Check out this video walking through how to run and test collections from the command line with Newman.