Testing APIs has come a long way from the time cURL was the only available tool. Postman improved the end-to-end testing experience by allowing developers to easily make requests from a user-friendly interface. You can use Postman as a full-featured collaboration platform for API development and testing.

In this tutorial, you will learn how to perform and automate tests against your APIs using Postman’s command-line utility, Newman.

Prerequisites

To complete this tutorial, a few things are required:

  1. Basic knowledge of Javascript
  2. Postman for Desktop installed on your system (you can download it here)
  3. A CircleCI account
  4. A GitHub account

We will be testing the API built and deployed in this post. It’s a simple Node.js API that consists of endpoints for creating and fetching user accounts. This API was deployed to the address https://my-adonis-api-app.herokuapp.com. You can find the source code here and deploy it following the steps in the post (linked above).

With everything we need installed and set up, it is time to start the tutorial.

Setting up a Postman environment

To set up an automated testing pipeline for your API tests, you will need to create an environment in Postman. Setting up the scope of the environment will help you avoid variables clashing globally or with other environments.

Open Postman desktop. Click the Manage Environments cog icon, which is in the top right corner of the interface. From the Manage Environments dialog, click Add.

Note: Your Postman UI may look slightly different than the screenshots in this tutorial, but the tools you need will be in the places specified.

In the Add Environment dialog, enter a name for the environment.

Enter the environment variable, api_url, as shown below. Fill in the API base URL with https://cci-gwp-adonis-api.herokuapp.com (without a trailing slash). The value in INITIAL VALUE is duplicated in CURRENT VALUE. Keep them indentical for this tutorial.

Create environment - Postman

Click Add to create the new environment. Select the new environment from the dropdown at the top right of the interface.

Creating a Postman Collection for API testing

Your next step is to create a Postman Collection for the user endpoints of the API we are testing. Postman Collections serve as containers for API requests. Postman Collections are normally used to group requests relating to a particular entity.

To create a new collection, click the Collections tab on the left sidebar of the interface. Then click New Collection as shown below.

Create collection button - Postman

From the New Collection dialog, fill in the name (Users) of your collection. You can also add a description for the collection to provide more insight.

Create Collection - Postman

Click Create to complete setting up the collection. Your new collection is listed on the left sidebar under the Collections tab.

Adding requests to the collection

Now you can add requests to your collection. Our API consists of two endpoints:

  • {{api_url}}/user/get (GET): Fetches a list of user profiles
  • {{api_url}}/user/create (POST): Creates a new user profile

To add a new request, click the flyout menu beside the collection as shown below.

Add Request - Postman

Click Add requests. Create a request for the {{api_url}}/user/get endpoint as shown below, and click Save to Users. Users is the collection we created earlier.

Add Request - Postman

A new request tab is listed. Enter the endpoint for the request in the address bar ({{api_url}}/user/get) using the api_url variable you created for the current environment. Select GET as the request method. Run the request as shown below.

Add Request - Postman

Postman returns an array of users is returned. Click Save.

Create another request for the {{api_url}}/user/create endpoint as shown below. This is a POST request and requires a username, email, and password.

Add Request - Postman

Make sure that you save this request.

Writing tests for API requests

Now that set up is complete, it is time for you to add some tests.

The left sidebar should show that the {{api_url}}/user/get request is selected. If it is not, click to select it. Click the Tests tab and enter:

pm.test("Request is successful with a status code of 200", function () {
  pm.response.to.have.status(200);
});

pm.test("Check that it returns an array", function () {
  var jsonData = pm.response.json();
  pm.expect(jsonData).to.be.an("array");
});

Add Test 1 - Postman

The Postman tests you just added are Chai assertions.

In the code above, the first test checks that the request completes with a success status code of 200. The second test checks to see that the data returned from the request is an array; in this case, the expected array of user profiles.

Save and run the request again. Details about the tests that have passed are listed on the Test Results tab.

Run Tests 1 - Postman

Next, add tests for the POST request to the {{api_url}}/user/create endpoint. Tests for this endpoint are more complicated than the previous tests. That is because the API does a duplicate check on the username and email request parameters. Using hard-coded parameters will cause the request to fail after the first try.

Luckily, you can set up one of Postman’s Pre-request Scripts. These scripts run before a request is fired. Use this script to dynamically generate random usernames and emails for the request.

Click the request to load it, then click the Pre-request Script tab. Add the following script:

let random = +new Date();

pm.globals.set("username", `${random}-user`);
pm.globals.set("email", `${random}-user@test.com`);

Pre-request scripts - Postman

In the script above, the current timestamp is used to randomly create usernames and emails for each request that fires. The random username and email are set as global variables for the request instance. Replace the username and email in the request body with the dynamic values shown below.

Dynamic parameters - Postman

Now, each request will use dynamic username and email parameters. Add the following to the Tests window for this request:

pm.test("User creation was successful", function () {
  pm.expect(pm.response.code).to.be.oneOf([200, 201, 202]);
});

pm.test("Confirm response message", function () {
  var jsonData = pm.response.json();
  pm.expect(jsonData.message).to.eql("User Successfully created");
});

In the code above, the first test asserts a successful response by checking the status codes 200, 201, and 202. These codes are used to indicate a successful POST request. The second test checks the message returned in the json response to make sure it matches the expected success message.

Run the requests and the tests will pass as shown below:

Test Results 2 - Postman

Setting up a test automation project

So far we have used the Postman GUI to make requests, and that is great, but the goal of this tutorial is automating testing and generating test results. That makes our next task setting up a project for test automation.

To get started, create a folder for the project at any location on your local machine:

mkdir postman-api-testing

Make sure you have saved your requests. Then click Export from the collection context menu.

Export Collection - Postman

A file named Users.postman_collection.json will be downloaded.

We also need to export the Postman environment we created for this tutorial. Click the Manage Environments icon and download your environment from the pop-up dialog. A file named My-Remote-API-Testing.postman_environment.json will be downloaded.

Note: If you use different filenames, be sure to stay consistent, or rename the files using the examples in the tutorial.

Put these two files at the root of your project folder.

Connecting the project to CircleCI

Begin by pushing your project to GitHub.

Now, go to the Add Projects page on the CircleCI dashboard to add the project.

Add Project - CircleCI

Click Set Up Project.

Add Config - CircleCI

On the setup page, click Use Existing Config to indicate that you are setting up a configuration file manually and not using the sample displayed. Next, you get a prompt to either download a configuration file for the pipeline, or to start building.

Build Prompt - CircleCI

Click Start Building. This build will fail because we have not set up our configuration file yet. We’ll do this in the next step.

Automating the testing process using the Newman orb

The final step in this tutorial is to write the test automation script. This script will use Postman’s CLI sibling, Newman, to run the collection using the exported environment. Luckily, CircleCI has an orb for Newman. Orbs are packages that abstract a lot of boilerplate code. Orbs provide developers with a friendly API for invoking common commands and for using tools like Newman, Heroku, and environments.

Because newman is a third-party orb, your CircleCI account must be set up to allow it. To change this setting, go to the Organization Settings of your CircleCI account. From the left sidebar, click Security. On the Security Setting page, select Yes to allow third-party orbs in your build.

Security Settings - CircleCI

Create a configuation file

Create a folder named .circleci at the root of the project and add a configuration file named config.yml inside the folder. In this file, enter the following code:

version: 2.1
orbs:
  newman: postman/newman@0.0.2
jobs:
  build:
    executor: newman/postman-newman-docker
    steps:
      - checkout
      - newman/newman-run:
          collection: ./Users.postman_collection.json
          environment: ./My-Remote-API-Testing.postman_environment.json

By calling the newman/newman-run command, the script above loads Postman’s Newman orb and runs the collection using the specified environment. It is just that simple.

Commit your changes and push to the remote repository to trigger the pipeline build.

Build Successful - CircleCI

To view the test results, click the build and expand the Test tab.

Test Results - CircleCI

As expected, Newman runs the collection, then generates a report detailing how the tests ran.

Awesome!

Conclusion

The manual testing process can quickly become a cumbersome, error-prone routine. The Postman GUI is already a must-have for every API developer’s toolkit. As we have shown in this tutorial, CircleCI automated pipelines and the newman orb can take your API testing even further.

Happy coding!


Fikayo is a fullstack developer and author with over a decade of experience developing web and mobile solutions. He is currently the Software Lead at Tech Specialist Consulting and develops courses for Packt and Udemy. He has a strong passion for teaching and hopes to become a full-time author.