Tutorials 03 December 2019

Load Testing Your API with Postman

Mostafa Moradian, Developer Advocate

In this article, I'll explain how to use Postman to create requests and organize them in collections using the beta API functionality which can import a OpenAPI schema file. I'll then explain how to run our postman-to-k6 script to generate a k6 script from the exported collection. Next I'll run the script using k6 to test the API.

Load Testing Postman Collections in k6

Postman Basics

Postman is definitely the tool to go with API testing if you're a visual person, since it gives you enough features with its easy-to-use graphical user interface. You just enter your URL, you hit Send and boom! It works! It also gives a nice request management feature called collections, which you can easily group your request into hierarchical structures, denoting whatever you want, from versioning to (micro-)services and endpoints grouping. Using the collections functionality, you can export your requests to a JSON file, which you then can share with other developers, testers and QA people.

There is a nice article on the Postman learning center, a.k.a. docs, where you can learn more about creating collections and sharing them.

To begin with, I'd like to give you an example of requests grouped into collections with some more features of Postman, mainly in order to demonstrate how to create and manage requests, collections and more in Postman. For the purpose of this example, I'll use our own hosted instance of httpbin.org and will use an OpenAPI Specification generated by the same tool.

To ease the creation of requests and collections, I'll try to use the API workflow of Postman, which basically let's you create your own API, either manually or by providing a schema/specification. I've imported the specification generated by httpbin.org into the API I've created in Postman, named httpbin. This specification is in Swagger 2.0 with some OpenAPI 3.0.0 extensions.

postman api import openapi feature

Using the Generate Collection button on the same page, I've generated a collection of requests and named it the httpbin.org collection. As you can see in the screenshot below, I have selected the GET request from the anything subcollection that contains a variable called {{baseUrl}}.

httpbin collection

Since the {{baseUrl}} is set to the current root path, hence /, and for the sake of our test, we should change it to a more meaningful value, using the Edit menu item on the dotted menu that appears while you hover over the collection.

postman collection edit variable

After updating the variable, we can hit the Send button on the GET request and see the response.

postman get request

To further illustrate the usage if Postman, I'll add a JSON body to the same request, which is {"firstname": "Mostafa"}. Then I will write a test script to see how I can find out if the returned result includes the same data as the original. As you can see in the screenshot below, I have used the Postman API, pm, to be able to test the response against my expectation. In the Test Results tab on the response section, you can see that our test has passed, in green.

postman test script

It is the time to export our collection of requests to a JSON file. For this, you should go to collection's menu, and select Export. Just choose the Collection v2.1 (recommended) option and hit the Export button. I'll name the file httpbin.json and will save it somewhere I can find it easily, well, obviously.

Postman-to-k6, Node.js and k6

Up until now, you've been introduced to some features of Postman and experienced some testing features of it. What if I tell you that you can use your Postman collections for load testing. You may wonder how! Well, it is as simple as Postman itself and it only takes a few steps with our tool, postman-to-k6, to convert your collections into scripts that can be run by k6. You can read more about its features in its release notes.

1. Install Node.js (if you haven't already done so):

For this, I highly recommend that you use something like nvm, which is a Node version manager that you can use to have multiple version of Node at the same time on your machine and be able to switch to any of them quickly.

2. Install postman-to-k6 module:

The postman-to-k6 tool is developed to help with converting your requests (inside your Postman collections) to k6 scripts, which are actually JavaScript code.

$ npm install -g postman-to-k6

3. Convert your exported Postman collection to k6 script:

Assuming your exported collection is named httpbin.json, you can run this command to convert it to a k6 script:

postman-to-k6 httpbin.json -i 1000 -o k6-script.js

If you need more fine-tuning of your test, adding data or having environment variables inside your code, just take a look at the Usage section of the postman-to-k6 README. For the sake of simplicity, I'll remove all the requests from the converted script and leave only the request that we have added body and test to. So, our script should look like below. As you see, I've specified the iterations count to be 1000 and I have manually added the virtual users (VU) count. The number of iterations is split between all VUs, meaning that each separate VU will run the default function, a.k.a. VU code, 10 times.

The exported script is a little bit different from normal k6 scripts, since it includes various abstractions to support different Postman functionality, but you can mix them with regular http requests from k6.

import "./libs/shim/core.js";
import "./libs/shim/urijs.js";
import "./libs/shim/expect.js";

export let options = { maxRedirects: 4, iterations: 1000, vus: 100 };

const Request = Symbol.for("request");
  collection: {
    baseUrl: "http://httpbin.test.loadimpact.com"

export default function() {
    name: "Returns anything passed in request data.",
    id: "bd426ad9-e158-477e-8485-8dc5ecf48aaf",
    method: "GET",
    address: "{{baseUrl}}/anything",
    data: '{"firstname": "Mostafa"}',
    headers: {
      "Content-Type": "application/json"
    post(response) {
      pm.test("", function() {
        var jsonData = pm.response.json();
        pm.expect(jsonData.json).to.eql({ firstname: "Mostafa" });

There is a lib directory beside the script that includes shims and libraries needed for the Postman scripts to work correctly. Here you can see the baseUrl variable that we changed in Postman and the test script.

4. Install k6:

k6 supports various platforms, including Windows, Linux, macOS and docker. In order to install it, just grab an Windows installer or a docker image and run it on your machine. With Linux, you can use APT or YUM, and with macOS, you can use Homebrew.

5. Run k6 with the generated script:

Now that you have your collections converted into a k6 script, you can invoke k6 like this:

$ k6 run k6-script.js

The result of running the script is shown in the following screenshot:

k6 output


In this article I've tried to give a quick introduction to Postman, postman-to-k6 and k6. All these tools combined can help you turn your API requests in Postman to be used by k6 to run load test on your API. Many of the Postman features are supported by the postman-to-k6 tool, which you can easily find on the GitHub repository of the project.

< Back to all posts