Posted inDevelopment

Mastering Load Testing with Locust: Simulating Thousands of Users with Python Made Easy

Development tutorial - IT technology blog
Development tutorial - IT technology blog

Context: Why does your system “die” just as customers start arriving?

The feeling of a server “crashing” right during a campaign launch is every developer’s nightmare. Code that runs smoothly on local or staging with a few users means nothing. When real traffic spikes, 502 errors appear, databases freeze, and customers start leaving. That’s the price of ignoring Performance Testing.

A system might function correctly, but will it run fast when 1,000 or 10,000 people click “Buy Now” simultaneously? Previously, I used JMeter. It’s powerful, but its XML configuration files are extremely bulky and hard to customize. Locust is different. It allows you to write test scripts in pure Python. You can use any library, write loops, or handle logic just like coding a real feature.

In a web app project with five developers, I implemented Locust right from the development phase. The results were surprising. The team discovered a SQL query missing an index, which caused response times to jump from 50ms to 5 seconds when there were over 200 concurrent users. If we had waited until go-live to find this out, it would have been a disaster.

Installing Locust in a Python Environment

You only need Python 3.7 or higher installed. Installing Locust is incredibly quick via pip:

pip install locust

Once installed, check the version with the command:

locust -V

If the terminal returns version information (e.g., locust 2.15.1), you’re ready to go.

Building a Detailed Load Test Script with Python

With Locust, a test script is a Python file (usually locustfile.py). Here is a practical example for testing an e-commerce website.

import time
from locust import HttpUser, task, between

class WebsiteUser(HttpUser):
    # Simulate wait time between actions (1-5 seconds)
    wait_time = between(1, 5)

    @task(3)
    def view_homepage(self):
        """User views homepage"""
        self.client.get("/")

    @task(1)
    def view_product_detail(self):
        """User views product details"""
        self.client.get("/product/123", name="/product/[id]")

    @task(2)
    def post_comment(self):
        """User posts a comment"""
        self.client.post("/api/comment", json={
            "user": "test_user",
            "content": "Great product!"
        })

Source Code Breakdown:

  • HttpUser: Represents a “bot.” Each user will have their own separate session, just like a real user.
  • wait_time: Crucial. Real users need time to read content before clicking next; no one clicks 100 times per second.
  • @task(weight): The number in parentheses is the weight. In the example above, the probability of a user visiting the homepage is three times higher than posting a comment.
  • self.client: Usage is similar to the popular requests library for sending GET, POST, and PUT requests.

Running Tests and Reading Dashboard Metrics

To start the simulated “attack,” open your Terminal and type:

locust -f locustfile.py

Access http://localhost:8089 to enter the management interface. Here, you need to enter three parameters:

  • Number of users: Total number of users to simulate (e.g., 1000).
  • Spawn rate: The rate at which new users are created per second (e.g., 10).
  • Host: The URL of the system being tested.

Don’t Ignore These Critical Metrics:

As the charts start running, don’t just look at the number of requests. Focus on:

  1. RPS (Requests Per Second): The number of requests processed per second. If RPS plateaus while the number of users continues to increase, the system has hit its limit.
  2. Response Time (p95): This is a key metric. It indicates that 95% of users receive a response within this time. If p95 exceeds 2 seconds, customers will start to get frustrated.
  3. Failures: Error rate. If you see 5xx errors, check the logs immediately to see if the database connection pool is exhausted.

Real-world Experience: When to Run Distributed?

A personal computer can usually only simulate about 1,000 users. To test a system’s capacity for tens of thousands (e.g., 50,000 CCU), a single machine will hit CPU bottlenecks before the server does. The secret here is using Master-Worker mode.

You set up one Master machine for control and multiple Worker machines to fire requests. In a real-world stress test for a Fintech system, I used 20 Workers on AWS to simulate 100,000 visitors in 15 minutes. This allowed the team to discover that Redis was running out of memory due to over-aggressive caching—a bug that’s extremely hard to spot at a small scale.

# On the Master machine
locust -f locustfile.py --master

# On Worker machines
locust -f locustfile.py --worker --master-host=<IP_MASTER>

Locust not only gives you peace of mind when deploying but also helps you clearly understand your infrastructure limits. Don’t wait for customers to complain. “Crash” your own system in a controlled way to build it stronger.

Share:
Tags: