Integrating with Jenkins

Postman contains a full-featured testing sandbox that lets you write and execute JavaScript based tests for your API. You can then hook up Postman with your build system using Newman, the command-line collection runner for Postman.

Newman allows you to run and test a Postman Collection. Newman and Jenkins are a perfect match. Let's review these topics to set up this operation.

Note: This walkthrough uses Ubuntu as a target OS, as in most cases your CI server will be running on a remote Linux machine.

Installation

  1. Install and start Jenkins. For more information, see the Jenkins documentation at https://www.jenkins.io.

  2. Install NodeJS and npm. Newman is written in NodeJS and the official copy is available through npm. Install nodejs and npm for Linux.

  3. Install Newman globally, to set up Newman as a command-line tool in Ubuntu.

    $ npm install -g newman

Run a collection in Postman

These instructions assume you already have a Postman Collection with some tests. Run the collection in Postman. Here's an example of the output in Postman’s collection runner.

collection runner

Some of the tests are failing intentionally in the screenshot to demonstrate the troubleshooting process.

Run a collection using Newman

Run this collection inside Newman, using the command below. If everything is set up nicely, you should see the output below.

terminal output from collection run

Set up Jenkins

After you have started Jenkins, it exposes an interface at http://localhost:8080. Click the New Item link on the left sidebar to create a new job.

jenkins interface

Select a “Freestyle Project” from the options. Name your project, and click OK.

new Jenkins job

Add a build step in the project. The build step executes a shell command.

execute shell command

Here is an example command:

$ newman run /path/to/jenkins_demo.postman_collection.json --suppress-exit-code 1

Note here that the Newman command parameter suppress-exit-code uses the value 1. This denotes that Newman is going to exit with this code that will tell Jenkins that everything did not go well.

Click Save to finish creating the project.

Jenkins build shell command

Troubleshooting

Run this build test manually by clicking on the Build Now link in the sidebar.

run build

Jenkins indicates that the build has failed with a red dot in the title. You can check why with the console output from Newman.

build failed message

Click the “Console Output” link in the sidebar to see what Newman returned.

console output

Fix these tests inside Postman and then try again.

collection runner view

You can move on once you see green pass icons for all your tests like the screenshot above.

console output for all tests pass

Jenkins indicates that the build succeeded with a blue ball.

Configure frequency of runs

To set up the frequency with which Jenkins runs Newman, click on “Configure project” in the main project window and then scroll down.=. The syntax for setting the frequency is H/(30) * * * *.

build triggers

Note: 30 can be replaced with another number.

Jenkins will now run Newman at your desired frequency and will tell you whether the build failed or succeeded. In a bigger setup, Newman will be part of your build process and probably not the entire process. You can set up notifications and customize Jenkins as per your needs.

You can use a wide variety of other configurations to make your collection more dynamic.

For more information about collection runs, see: