How to Load Test REST APIs with Locust.io in Python

This article gives a brief introduction on how you can load test REST-based applications written in any programming language like Java, Node Js, or Python using an open-source tool called Locust.io. This article preassumes that you have a good understanding of REST APIs and python as a programming language.

To learn about REST APIs, you can browse through some online tutorials. To understand the capability of Locust as a tool for load test you can read its documents and implementations.

Steps to Load Test

  1. The first requirement is we should have REST API details that are exposed by the web service. Just to demonstrate we will consider sample API exposed over the public internet and you can find many such API lists over website mixed analytics. We will take the example of Nationalize.io for this blog.
  2. As we now have the API details, the focus is writing a load test client to perform the performance test on these APIs.
  3. I have already published the client code in the git repository.
    You can either download the file load_test_rest_api_by_locust.py or clone the repository using the below URLs under the repository
    performance-test/rest_api_based_services.
Dowload urlhttps://github.com/ManojSingh0302/performance-test/blob/master/rest_api_based_services/load_test_rest_api_by_locust.pyClone urlhttps://github.com/ManojSingh0302/performance-test.git

Source Code

Following is the source code of the same.

source code

4. Now as you have codes, we need to install few dependencies before we start execution. Open the repository in the editor of your choice and simply install it by running the below commands on the terminal.

Note: It is advised to create a virtual environment in python 3.7 and follow the below steps.

----- For creating Virtual environment -----
$ python -m virtualenv venv
$ source venv/bin/activate
----- For Installing dependencies -----
$ pip install -r requirement.txt
$ pip install -e .

5. Once all the dependencies are installed, we now need to load test the API server and to do this, we have the locust code inlocust/loat_test_rest_api_by_locust.py

6. Locust provides two modes of running a test, either you can run in web mode or headless mode. Let's first understand how to Run the locust in web mode

Locust in Web mode

Open a terminal and navigate to the path performance-test/rest_api_based_services run the following command for web mode from the command line.
$ locust -f load_test_rest_api_by_locust.py

web mode command

6.1 Now in the logs, we can observe that the Locust load test sever started on default port[8089] and we can access by URL http://localhost:8089/ in any browser.

6.2. Now to start the test select Number of total users to simulate along with the Hatch rate (users spawned/second) of your choice as shown below.

Note: initially select smaller number so that your system respond to the load, thereafter you can increase as per your case. Also, as these are public APIs which we are just using it for learning so I would recommend not to use more than total of 5 users.

6.3 Now Start Swarming and observe the statistics and charts, you can stop the locust at any given point by using the stop button as shown in the below image.

Statistics

In this section, all performance stats will be visible here.

Statistics

Charts

The below charts will show you how req/sec for success and failure response varies.

Charts

Failures

Failures during the load test if any will be listed here.

Failures

Exceptions

If during the load test there are any exceptions then that will be listed here.

Exceptions

Download Data

It also provides you the feature to download the statistics from the load test.

Download Data

Console Output

Data here is the same as what we saw under statistics on the web but this has more detailed info on response time percentiles.

Console Output

Locust in Headless Mode

To run locust from the command line, without web-UI, run the following command

locust -f load_test_rest_api_by_locust.py --headless -u <no-of-users> -r <hatch/second> -t <stop-time>

e.g. locust -f load_test_rest_api_by_locust.py --headless -u 10 -r 5 -t 3s

Where,

-u NUM_USERS, --users NUM_USERS
Number of concurrent Locust users. Only used together
with --headless
-r HATCH_RATE, --hatch-rate HATCH_RATE
The rate per second in which users are spawned.
Only used together with --headless
-t RUN_TIME, --run-time RUN_TIME
Stop after the specified amount of time.
e.g. (300s,20m, 3h, 1h30m, etc.)
Only used together with --headless

Running locust in Master-Slave Mode

In this case, we run these locust load test clients from the different virtual machines(VM). where one VM will be our master and you can declare n number of VMs as clients.

With Port

[Run as MASTER-  from <IP: 10.20.20.2 & PORT: 5557>]locust -f load_test_rest_api_by_locust.py --headless -u 10 -r 2-t 1m --master --master-bind-port=5557[Run as WORKER passing <IP and PORT> of MASTER] locust -f load_test_rest_api_by_locust.py --worker --master-host=10.20.20.2 --master-port=5557

Without Port

[MASTER]locust -f load_test_rest_api_by_locust.py --headless -u 10 -r 2 -t 1m --master[WORKER]locust -f load_test_rest_api_by_locust.py --worker --master-host=10.20.20.2

Note: To get the downloadable reports from the locust you can add the following command to the master. This will create CSV files on the mentioned path in the command. These CSV files are the same as what we saw under Download data in Web mode.

--csv=reports/locust/reportsfile

To just get a summary in the CSV file adds the below command instead.

--only-summary --csv=reports/locust/reportsfile

Hurray!! We have done it. :-)
I hope this blog was useful to you. Please leave comments or send me an email if you think I missed any important details or if you have any other questions or feedback about this topic.

References:

Computer Science Engineer working as software development engineer in test with a passion for Machine Learning, AI & Data Visualisations.