Set up a CircleCI pipeline to run a Postman collection using the Newman orb

The software industry is increasingly moving towards an API-first world. Large software systems built today are composed of APIs. Postman has become the trusted tool of software developers and testers to design, test, and publish APIs. Over 6 million developers and 200K+ organisations use Postman worldwide at every stage of their API development lifecycle.

Workflows in Postman revolve around Collections. Collections are groups of HTTP requests that can have their own tests, response examples, and documentation. You can generate API documentation straight from a collection. The saved response examples form the basis of creating Mock Servers for APIs. You can collaborate on all of these with team workspaces.

Postman also has the ability to execute these collections. Running a collection triggers all the requests in the collection one by one. You can also write scripts to assert on response, control the execution order, and transfer data among requests in a single run. This is great when you want to test an API, perform end-to-end tests for API workflows, and/or do health checks of your APIs. You name it.

Executing collections in a CI environment

A very common use case for Postman is to run collections in CI pipelines. Teams run contract tests, end-to-end tests, security checks, or infrastructure checks on their services as part of their build or release pipelines. This is where the Newman command line collection runner becomes useful.

Newman is a Node.js application that can run a collection from the local filesystem or from a remote URL. Newman also comes with multiple reporting options. You can produce collection run reports as json, xml, or html outputs. When you integrate Newman with a CI environment, you can control your build stages based on whether your APIs perform as expected.

An orb to help simplify your collection runs

While Newman ships as a Docker container, setting up these build stages can be quite time consuming. With the Newman orb for CircleCI, we have built a readymade integration where you can trigger collection runs in your CircleCI pipelines with just a configuration.

The orb will take care of setting up Newman, executing the collection you mention in the configuration, and storing the reports of the run in the proper place.

Configuring the orb

The Newman orb exposes the newman/newman-run command that you can use in your CircleCI configuration. You can either have your collections exported as JSON from Postman and saved in your repository, or you can directly call the Postman API with your collection ID and API key and run Newman against the latest version of the collection.

Assuming you have your collection file exported to ./collection.json at the root of your repository, this is what your CircleCI config would look like:

version: 2.1
orbs:
  newman: postman/newman@0.0.2
jobs:
  newman-collection-run:
    executor: newman/postman-newman-docker
    steps:
      - checkout
      - newman/newman-run:
          collection: ./collection.json

The newman/newman-run command takes on a lot of arguments that are passed on to Newman. Here are some of the important parameters that you should know:

• collection: This is the only required parameter as shown in the example above. It takes a path to a collection’s JSON file or a URL whhere the collection can be accessed.
• environment: This needs either a path to an environment exported from Postman, or a URL to the environment.
• iteration-data: If you need to use external data from CSV files in your collection run, this argument takes the file path or URL to a CSV file.
• folder: The name or names of folders to run in the collection. Thiis is used when you want to scope your collection run to specific folders in the collection.

Beyond these, you can view the full set of accepted arguments on the orb’s documentation page.

In summary

Combining the power of CircleCI with Postman and the Postman API, you can build perfect workflows for your APIOps and API testing. We hope this orb helps you go further in your API automation journey.