0
# Locust
1

2
A developer-friendly load testing framework that enables you to write test scenarios in plain Python code. Locust supports distributed testing, provides a web-based UI for monitoring, and can test HTTP services and other protocols including databases and WebSockets.
3

4
## Package Information
5

6
- **Package Name**: locust
7
- **Language**: Python
8
- **Installation**: `pip install locust`
9
- **Python Requirement**: >=3.10
10

11
## Core Imports
12

13
```python
14
import locust
15
```
16

17
Common imports for load testing:
18

19
```python
20
from locust import HttpUser, task, between
21
from locust import User, TaskSet, events
22
```
23

24
## Basic Usage
25

26
```python
27
from locust import HttpUser, task, between
28

29
class WebsiteUser(HttpUser):
30
    wait_time = between(1, 5)  # Wait 1-5 seconds between tasks
31
    
32
    @task
33
    def index_page(self):
34
        self.client.get("/")
35
    
36
    @task(3)  # This task is 3x more likely to run
37
    def view_item(self):
38
        item_id = random.randint(1, 10000)
39
        self.client.get(f"/item?id={item_id}", name="/item")
40
    
41
    def on_start(self):
42
        """Called when user starts"""
43
        self.client.post("/login", json={
44
            "username": "testuser",
45
            "password": "secret"
46
        })
47
```
48

49
Run the test:
50

51
```bash
52
locust -f locustfile.py --host=http://mywebsite.com
53
```
54

55
## Architecture
56

57
Locust uses an event-driven architecture built on gevent for handling thousands of concurrent users efficiently:
58

59
- **Users**: Define behavior patterns and represent individual virtual users
60
- **TaskSets**: Organize related tasks and enable complex user flow modeling  
61
- **Tasks**: Individual actions that users perform, decorated with `@task`
62
- **Events System**: Extensible hooks for custom metrics, logging, and integrations
63
- **Runners**: Orchestrate test execution (local, master/worker distributed setups)
64
- **Web UI**: Real-time monitoring dashboard for test progress and results
65

66
This design enables flexible test scenarios from simple HTTP load tests to complex multi-protocol distributed testing with custom metrics and reporting.
67

68
## Capabilities
69

70
### User Classes
71

72
Foundation classes for defining virtual user behavior including HTTP users, generic users, and high-performance FastHTTP users. Users define the core behavior patterns that drive load testing scenarios.
73

74
```python { .api }
75
class User:
76
    def __init__(self, environment): ...
77

78
class HttpUser(User):
79
    client: HttpSession
80

81
class FastHttpUser(User):
82
    client: FastHttpSession
83
```
84

85
[User Classes](./user-classes.md)
86

87
### TaskSets and Task Management
88

89
System for organizing and controlling task execution including sequential, random, and Markov chain-based task selection. TaskSets enable complex user behavior modeling and task flow control.
90

91
```python { .api }
92
class TaskSet:
93
    def __init__(self, parent): ...
94

95
class SequentialTaskSet(TaskSet): ...
96
class MarkovTaskSet(TaskSet): ...
97

98
def task(weight=1): ...
99
def tag(*tags): ...
100
```
101

102
[TaskSets and Tasks](./tasksets.md)
103

104
### Wait Time Functions
105

106
Functions for controlling timing between task executions including random intervals, constant delays, pacing, and throughput control. These functions enable realistic user behavior simulation.
107

108
```python { .api }
109
def between(min_wait, max_wait): ...
110
def constant(wait_time): ...
111
def constant_pacing(wait_time): ...
112
def constant_throughput(task_runs_per_second): ...
113
```
114

115
[Wait Time Functions](./wait-time.md)
116

117
### Events System
118

119
Comprehensive event system for extending Locust with custom functionality including request hooks, lifecycle events, and distributed testing coordination.
120

121
```python { .api }
122
events: Events  # Global events instance
123

124
class Events:
125
    request: EventHook
126
    user_error: EventHook
127
    test_start: EventHook
128
    test_stop: EventHook
129
    # ... 15+ additional events
130
```
131

132
[Events System](./events.md)
133

134
### Protocol Extensions
135

136
Built-in support for testing non-HTTP protocols including MongoDB, PostgreSQL, WebSocket/SocketIO, and other systems through the contrib module ecosystem.
137

138
```python { .api }
139
class MongoDBUser(User): ...
140
class PostgresUser(User): ...
141
class SocketIOUser(User): ...
142
```
143

144
[Protocol Extensions](./contrib.md)
145

146
### Load Test Shaping
147

148
Custom load test patterns and shapes for advanced testing scenarios including ramp-up patterns, step functions, and complex load profiles over time.
149

150
```python { .api }
151
class LoadTestShape:
152
    def tick(self): ...  # Returns (user_count, spawn_rate) or None
153
```
154

155
[Load Test Shaping](./load-shapes.md)
156

157
### Exception Handling
158

159
Comprehensive exception system for controlling test flow including task interruption, user stopping, response validation, and RPC communication errors.
160

161
```python { .api }
162
class LocustError(Exception): ...
163
class InterruptTaskSet(Exception): ...
164
class StopUser(Exception): ...
165
class ResponseError(Exception): ...
166
```
167

168
[Exception Handling](./exceptions.md)
169

170
### Debugging and Utilities
171

172
Tools for debugging test scenarios including single-user execution, task ratio inspection, and development-time testing utilities.
173

174
```python { .api }
175
def run_single_user(user_class, **options): ...
176
def print_task_ratio(user_classes): ...
177
```
178

179
[Debugging and Utilities](./debugging.md)
180

181
## Types
182

183
### Core Types
184

185
```python { .api }
186
from typing import Callable, Dict, List, Optional, Union, Any
187
from gevent.greenlet import Greenlet
188

189
# User and TaskSet configuration
190
TaskFunction = Callable[[], None]
191
TaskDict = Dict[TaskFunction, int]
192
TaskList = List[Union[TaskFunction, tuple]]
193
WaitTimeFunction = Callable[[], float]
194

195
# Event system types  
196
EventHandler = Callable[..., None]
197
ResponseContextManager = Any  # Context manager for response validation
198
```