Integrating with Jenkins

Postman contains a full-featured testing sandbox that enables you to write and execute JavaScript based tests for your API. You can then integrate Postman with your CI/CD build system using Newman, the command-line collection runner for Postman.

The following example shows how to set up a Jenkins build that uses Newman to run a collection. If the collection passes all tests, the Jenkins build will be marked as successful. This uses a Jenkins install running locally, but you'll typically be running it on a build server for production use.

Contents

Installation

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

  2. Install Node.js and Newman in Jenkins:

    1. Go to your Jenkins server (it's at http://localhost:8080 by default if you are running it locally) and log in.
    2. Go to Manage Jenkins > Manage Plugins and install the NodeJS plugin.
    3. Go to Manage Jenkins > Global Tool Configuration and under NodeJS, select Add NodeJS.
    4. Enter a name for the Node.js installation.
    5. In Global npm packages to install, enter newman.
    6. Select Save.

Create a Postman collection

For this example, you'll need a Postman collection that contains a few requests with tests. For this example, you can import a sample "Hello World" collection into your workspace by selecting the Run in Postman button below.

Run in Postman

To demonstrate the troubleshooting process, edit a request and intentionally break one of the tests. For example, change the final test so that it looks for the text "Hello, Everyone!" instead of "Hello, World!"

After you've created the collection, export it as a JSON file.

Set up Jenkins

  1. With Jenkins running, go to http://localhost:8080 and log in.

  2. On the Dashboard page, select New Item on the left sidebar to create a new job.

  3. Select a Freestyle project from the options. Name your project, and select OK.

    new Jenkins job

  4. In General > Build, add a build step in the project, and choose Execute Shell. The build step executes a shell command. Enter a shell command to run, such as newman run ~/Desktop/jenkins_demo_postman_collection.json.

  5. In Build Environment > Build Environment, select Provide Node & npm bin/ folder to PATH and choose the NodeJS install you configured with Newman.

  6. Select Save to finish creating the project.

Troubleshooting

  1. Run this build test manually by selecting Build Now in the sidebar.

    run build

    Jenkins indicates that the build has failed with a red cross next to the build in the build history. This is because of the intentionally failed tests in the collection.

  2. Select the build in the history list, then select Console Output to see what Newman returned.

  3. Fix these tests inside your collection. Export it and then try again.

Jenkins indicates that the build succeeded with a green checkmark.

Configure frequency of runs

To set the frequency with which Jenkins runs Newman:

  1. Open the build window.

  2. Select Configure.

  3. Navigate to Build Triggers and select Build periodically.

  4. Enter a schedule. The syntax for setting the frequency to every 30 minutes is H/(30) * * * *.

    Select the help icon next to Schedule to see information on how to specify the build frequency.

  5. Select Save.

Jenkins will now run Newman at your desired frequency and will tell you if the build failed or succeeded.

In a real-world build environment, Newman will be part of your production environment. 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:

Last modified: 2022/01/18