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:
- Basic knowledge of JavaScript
- Postman for Desktop installed on your system. You can download it here. This tutorial uses Version 10.13.0.
- A CircleCI account
- 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://adonis-app-919a44fbb6b1.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 and select Environments from the left menu bar. Your enviroments will be displayed here if you have any, otherwise, you will have a link to create a new one. Click Create Environment or use the plus icon.
Note: Your Postman UI may look slightly different than the screenshots in this tutorial, but the tools you need will available.
Next, enter a name for the environment. Enter the environment variable, api_url. Fill in the API base URL with https://adonis-app-919a44fbb6b1.herokuapp.com (without a trailing slash). The value in INITIAL VALUE is duplicated in CURRENT VALUE. Keep them indentical for this tutorial.
Click Save to add 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 Create Collection.
Fill in the name (Users) of your collection. You can also add a description for the collection to provide more insight. 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 menu icon beside the collection.
Click Add requests. Create a request for the {{api_url}}/user/get endpoint, and click Save. Users is the collection we created earlier.
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. Name it Fetch the list of users.
Postman returns an array of users. Click Save.
Create another request, this time for the {{api_url}}/user/create endpoint. This is a POST request and requires a username, email, and password.
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");
});
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.
Next, add tests for the POST request to the {{api_url}}/user/create endpoint. Tests for this endpoint are more complicated than the previous test. 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`);
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.
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:
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.
A file named User.postman_collection.json will be downloaded.
We also need to export the Postman environment we created for this tutorial. Click the environment tab from the sidebar and make sure that the my-remote-api-testing is selected. Click the menu icon and export 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.
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.
Creating a CI/CD 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@1.0.0
jobs:
build:
executor: newman/postman-newman-docker
steps:
- checkout
- newman/newman-run:
collection: ./User.postman_collection.json
environment: ./my-remote-api-testing.postman_environment.json
workflows: null
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 your project to GitHub.
Connecting the project to CircleCI
Now, log into your CircleCI account. If you signed up with your GitHub account, all your repositories will be available on your project’s dashboard.
Click Set Up Project next to your postman-api-testing project.
This will trigger the pipeline build and run it successfully.
To view the test results, click the build and expand the Test tab.
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 Adepoju is a LinkedIn Learning (Lynda.com) Author, Full-stack developer, technical writer, and tech content creator proficient in Web and Mobile technologies and DevOps with over 10 years experience developing scalable distributed applications. With over 40 articles written for CircleCI, Twilio, Auth0, and The New Stack blogs, and also on his personal Medium page, he loves to share his knowledge to as many developers as would benefit from it. You can also check out his video courses on Udemy.
