Load testing is a crucial part of ensuring that our APIs can handle real-world traffic without slowing down or failing. While tools like JMeter and Gatling are popular, Locust offers a Python-based, easy-to-use alternative for simulating user traffic. Whether you're preparing for a product launch or want to understand your system's breaking points, this guide will show you how to set up and run your first Locust test in under 10 minutes—no complex configurations required.

Setting Up Locust

Getting started with Locust is straightforward, especially if you're already familiar with Python. You'll need Python 3.6 or newer installed on your system before proceeding.

The simplest way to install Locust is via pip:

                
pip install locust
                

To verify your installation, run:

                
locust --version
                

You should see the current version number displayed in your terminal.

Project Structure

While Locust can be used with minimal setup, it's helpful to organize our testing files. Here's a recommended project structure:

For our basic example, we'll focus on creating just the api_tests.py file. This file will contain the test scenarios we want to run against our API.

Each Locust test file needs to define at least one "user class" that inherits from Locust's HttpUser class. This class will contain tasks that simulate user behavior, which we'll cover in the next section.

Our First Locust Test

Now that we've set up Locust, let's create our first test file. We'll build a simple test that simulates users interacting with a RESTful API. I'll explain each part of the code as we go.

Understanding the Basic Structure

A Locust test file consists of one or more user classes that define the behavior of simulated users. Each user class contains tasks that represent actions users take against your application.

Let's start by creating our user class:

                
from locust import HttpUser, task, between

class APIUser(HttpUser):
    wait_time = between(1, 5)
    
    host = "https://jsonplaceholder.typicode.com"
                

Here, we're:

• Importing the necessary Locust classes
• Creating an APIUser class that inherits from HttpUser
• Setting a wait_time that makes our simulated users pause between 1-5 seconds between tasks, which creates more realistic behavior
• Defining a host which serves as the base URL for all requests

Adding Tasks

Now let's add tasks to our user class. Tasks are methods decorated with @task that define what actions our simulated users will perform:

                
@task(3)
def get_posts(self):
    with self.client.get("/posts", name="Get all posts") as response:
        if response.status_code != 200:
            print(f"Failed to get posts: {response.status_code}")
                

This task:

• Is decorated with @task(3), meaning it has a weight of 3 (will be called 3 times more often than a task with weight 1)
• Makes a GET request to the /posts endpoint
• Uses the name parameter to give this request a human-readable name in the Locust reports
• Checks if the response is successful and logs errors if not

Let's add two more tasks to create a realistic user flow:

                
@task(1)
def create_post(self):
    payload = {
        "title": "Locust Test Post",
        "body": "This is a test post created during load testing",
        "userId": 1
    }
                        
    with self.client.post("/posts", json=payload, name="Create post") as response:
        if response.status_code != 201:
            print(f"Failed to create post: {response.status_code}")
                    
@task(2)
def get_single_post(self):
    post_id = 1
    with self.client.get(f"/posts/{post_id}", name="Get single post") as response:
        if response.status_code != 200:
            print(f"Failed to get post {post_id}: {response.status_code}")
                

These tasks:

• Create a new post via a POST request with a JSON payload
• Fetch a single post by ID
• Have different weights (1 and 2), so the GET operations will occur more frequently than POST operations, which is typical in real-world API usage

This test file demonstrates several important Locust concepts:

• Realistic user behavior: By using weighted tasks and wait times, we're simulating more realistic user patterns than simple constant load.
• Multiple request types: We're testing both GET and POST requests to ensure different API operations are covered.
• Error handling: Basic error detection is included by checking response codes.
• Clean organization: The code is well-structured and commented for easy understanding.
• Real API testing: We're using JSONPlaceholder, a free test API that anyone reading the blog can use to follow along without setting up their own API.

Running the Test

Once we've created our Locust test file, we're ready to execute our load test. Let's walk through the process step by step.

Starting Locust

To run our test, we open a terminal, navigate to our project directory, and execute the following command:

                
locust -f locustfiles/api_tests.py
                

If your file is named differently or in another location, adjust the path accordingly. You should see an output similar to this one:

Accessing the Web Interface

By default, Locust starts a web interface that allows us to control our tests and view results in real-time. Open your browser and navigate to:

                
http://localhost:8089
                

You'll be greeted with Locust's clean, user-friendly dashboard.

×

Locust Dashboard

Configuring Our Test

On the main page, we'll need to set three key parameters:

• Number of users: Think of this as the crowd we're simulating. How many people do we want to hit the website at the same time? For our initial test, let's aim for a manageable 10 to 50 users.
• Spawn rate: This controls how quickly we bring that crowd in. It's like the rate at which people are entering a store. We want to start with a gentle pace, so let's set it to 5 to 10 users per second to begin with. This way, we avoid overwhelming the system right away.
• Host: We've already configured the target website in our test file, but if we need to test a different environment or override the existing setting, we can specify the hostname here.

Starting the Test

Once we've entered these values, we click the "START" button to begin our test. We'll immediately see Locust's dashboard transition to show real-time statistics.

×

Locust Statistics Page

Understanding the Dashboard

The dashboard is divided into several key sections:

• Statistics: Shows request counts, response times, and failure rates for each endpoint
• Charts: Displays response times and requests per second over time
• Failures: Lists any failed requests with details about what went wrong
• Exceptions: Shows any Python exceptions that occurred during the test
• Current Ratio: Visualizes the proportion of requests going to each endpoint, helping you understand traffic distribution
• Download Data: Allows you to export test results for further analysis or reporting
• Logs: Provides a chronological record of test events, warnings, and errors during execution
• Locust Cloud: Offers an entry point to Locust's cloud capabilities for distributed load testing

Controlling the Test

While the test is running, we have several options:

• Edit: allows us to modify the running load test's parameters without completely stopping it
• Stop: immediately stops the test
• Reset: resets all the statistics collected during the current load test

Example Test Run

For example, if we run our test with 20 users and a spawn rate of 5, we might see:

• The "Get all posts" endpoint handling about 10-15 requests per second
• The "Create post" endpoint processing around 3-5 requests per second
• The "Get single post" endpoint handling about 6-10 requests per second
• Response times generally staying under 200ms for GET requests and around 300-500ms for POST requests

These patterns reflect our task weights (3:2:1) and provide valuable insight into how our API performs under this level of load.

Remember, Locust load tests run continuously until you manually stop them via the 'Stop' button in the web UI. This allows for flexible testing durations, crucial for long-term monitoring and simulating traffic spikes. For precise, automated test lengths, leverage the --run-time command-line option, perfect for CI/CD integrations.

Understanding the Results

After running our Locust test, the real value comes from understanding what the results mean for our API's performance. Let's explore the key metrics and graphs available in the Locust UI.

Key Metrics Explained

1. Requests Per Second (RPS)

RPS measures how many requests our system can handle per second, which is a fundamental indicator of our API's throughput.

• What's good? Higher is generally better, but what's "good" depends on your specific requirements.
• Warning signs: Watch for sudden drops in RPS during constant load, which may indicate your system is becoming overwhelmed.
• Example: If your API shows 50 RPS with 100 concurrent users but drops to 30 RPS when you increase to 150 users, you've likely found a bottleneck.

2. Response Times

Response time metrics show how quickly our API responds to requests. Locust provides several values:

• Average: The mean response time across all requests to an endpoint
• Median (50%): The middle value when all response times are ordered
• 90% / 95% / 99%: The response time that 90%/95%/99% of requests fall below
• Max: The slowest recorded response

Pro tip: Focus on median and 95% values rather than average or max, as they better represent typical user experience and aren't skewed by outliers.

3. Failure Rate

The percentage of requests that resulted in errors (non-success HTTP status codes).

• What's good? Ideally zero, but <1% might be acceptable depending on your SLAs.
• Warning signs: Any non-zero value deserves investigation, especially if it increases over time.

Interpreting the Graphs

1. Total Requests Per Second Chart

Shows the combined RPS across all endpoints.

×

Total Requests Per Second Chart Example

What to look for:

• Plateaus: The point where adding more users doesn't increase throughput indicates your system's maximum capacity

2. Response Times Chart

This graph shows the evolution of response times during our test.

×

Response Times Chart Example

What to look for:

• Stable horizontal lines: Indicate consistent performance
• Gradual upward slope: May suggest memory leaks or resource exhaustion
• Sudden spikes: Could indicate periodic processes (like garbage collection) or external dependencies slowing down
• Step patterns: Often appear when you increase the number of users

3. Number of Users Chart

This Graph shows the number of active simulated users over time during our test.

×

Number of Users Chart Example

What to look for:

• Ramp-up phase: The chart typically shows a diagonal line as users are gradually spawned according to your specified spawn rate. For example, if you set 100 total users with a spawn rate of 10 users per second, you'll see a diagonal line that takes 10 seconds to reach the target.
• Steady state: After all users are spawned, the line should become horizontal, indicating your test is running with the full user load.
• Step patterns: If you manually add or remove users during the test, you'll see step-like patterns that visualize these changes.
• Unexpected drops: If the line suddenly drops before you stop the test, it could indicate that Locust encountered errors or that your system under test is failing.

Conclusion

Locust offers a refreshing approach to load testing that balances simplicity with power. With just a few lines of Python code, we can create realistic simulations of user behavior and gain valuable insights into our API's performance under load. Whether we're validating a new microservice or troubleshooting performance issues in an existing application, Locust provides the tools we need without the complexity of traditional load testing platforms.

For your convenience, the complete code example from this tutorial can be found on our GitHub page, ready to clone and run. We encourage you to experiment with the parameters, add more complex test scenarios, and discover how Locust can fit into your testing workflow.

Remember that consistent load testing throughout your development cycle is the key to catching performance issues before they impact your users. Happy testing!