From a1bfb8d16d0558d60db671f64c45968941849945 Mon Sep 17 00:00:00 2001
From: Baiheng Xie <874256269@qq.com>
Date: Fri, 9 Jan 2026 23:15:38 +0800
Subject: [PATCH 1/2] feat: add locust support

---
 justfile            |  4 ++++
 pyproject.toml      |  5 ++---
 tests/locustfile.py | 40 ++++++++++++++++++++++++++++++++++++++++
 3 files changed, 46 insertions(+), 3 deletions(-)
 create mode 100644 tests/locustfile.py

diff --git a/justfile b/justfile
index d8069de..4cc9407 100644
--- a/justfile
+++ b/justfile
@@ -27,6 +27,10 @@ run port=PORT:
 @test:
     uv run --frozen pytest -xvs tests
 
+# Run locust
+@benchmark:
+    uv run locust -f tests/locustfile.py
+
 # Generate database migration
 @db-migrate message:
     uv run alembic revision --autogenerate -m "{{message}}"
diff --git a/pyproject.toml b/pyproject.toml
index a894097..2cdd8c4 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -21,6 +21,7 @@ dependencies = [
 [dependency-groups]
 dev = [
     "fakeredis>=2.32.1",
+    "locust>=2.32.5",
     "pytest>=8.3.3",
     "pytest-asyncio>=1.2.0",
     "pytest-cov>=6.1.1",
@@ -48,9 +49,7 @@ testpaths = ["tests"]
 python_files = ["test_*.py", "*_test.py"]
 python_classes = ["Test*"]
 python_functions = ["test_*"]
-markers = [
-    "integration: marks tests as integration tests",
-]
+markers = ["integration: marks tests as integration tests"]
 
 [[tool.uv.index]]
 name = "tsinghua"
diff --git a/tests/locustfile.py b/tests/locustfile.py
new file mode 100644
index 0000000..887688d
--- /dev/null
+++ b/tests/locustfile.py
@@ -0,0 +1,40 @@
+from locust import HttpUser, TaskSet, task, between
+import time
+
+
+class AuthAPITasks(TaskSet):
+    def on_start(self):
+        """Setup: register a user for this taskset"""
+        unique_id = f"{self.user.user_id}_{int(time.time())}"
+        self.email = f"loadtest_{unique_id}@example.com"
+        self.username = f"user_{unique_id}"
+        self.password = "TestPass123!"
+
+        self.client.post(
+            "/auth/register",
+            json={
+                "email": self.email,
+                "username": self.username,
+                "password": self.password,
+            },
+        )
+
+    @task(3)
+    def login(self):
+        self.client.post(
+            "/auth/jwt/login",
+            data={
+                "username": self.email,
+                "password": self.password,
+            },
+        )
+
+
+class WebsiteUser(HttpUser):
+    tasks = [AuthAPITasks]
+    wait_time = between(1, 3)
+    user_id = 0
+
+    def on_start(self):
+        WebsiteUser.user_id += 1
+        self.user_id = WebsiteUser.user_id

From fac994dfd6230ec2920aefb535aa9f86783d8b16 Mon Sep 17 00:00:00 2001
From: Baiheng Xie <874256269@qq.com>
Date: Wed, 28 Jan 2026 14:44:47 +0800
Subject: [PATCH 2/2] docs: add `locust` support

---
 README.md | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/README.md b/README.md
index 2fce887..80fb3f2 100644
--- a/README.md
+++ b/README.md
@@ -402,6 +402,12 @@ async def fetch_with_manual_retry():
                 return response.json()
 ```
 
+### Testing
+
+`pytest` is used as the testing framework.
+
+We use `locust` for integrated load testing. User behaviors are defined in `tests/locustfile.py`, you can use it to simulate concurrent users, and get QPS/response metrics for analysis.
+
 ## Development Setup
 
 - Python >= 3.12