# Locust — Scalable Load Testing in Pure Python

> Locust is an open-source load testing tool where you define user behavior in plain Python code. Distributed, scalable, and with a real-time web UI for monitoring. No DSL to learn — just write Python.

## Install

Save the content below to `.claude/skills/` or append to your `CLAUDE.md`:

## Quick Use

```bash
pip install locust
```

```python
# locustfile.py
from locust import HttpUser, task, between

class TokrepoUser(HttpUser):
    wait_time = between(1, 3)
    host = "https://api.tokrepo.com"

    @task(3)
    def list_assets(self):
        self.client.get("/api/assets")

    @task(1)
    def view_asset(self):
        self.client.get("/api/assets/1")

    def on_start(self):
        # Login or setup
        pass
```

```bash
locust                       # Web UI at http://localhost:8089
locust --headless -u 100 -r 10 -t 5m --csv=results
locust --master              # Distributed: master
locust --worker --master-host=master-ip  # Workers
```

## Intro

Locust is an open-source load testing tool where you define user behavior in plain Python code. No XML, no DSL — just Python classes and decorators. Features a real-time web UI, distributed testing across multiple machines, and easy CI/CD integration.

- **Repo**: https://github.com/locustio/locust
- **Stars**: 27K+
- **Language**: Python
- **License**: MIT

## What Locust Does

- **Python test scripts** — define user behavior as classes
- **Web UI** — real-time charts, start/stop, user count control
- **Distributed** — master + workers for massive scale
- **Headless mode** — for CI/CD
- **CSV/JSON output** — export results
- **Custom clients** — test gRPC, WebSocket, MQTT, databases
- **Events** — hook into test lifecycle
- **Task weighting** — `@task(weight)` for traffic distribution

## Comparison

| Tool | Language | UI | Distributed |
|---|---|---|---|
| Locust | Python | Web UI | Master/worker |
| k6 | JavaScript | CLI | k6-operator |
| JMeter | Java/GUI | Desktop | Servers |
| Vegeta | Go | CLI | No |
| wrk | C | CLI | No |

## FAQ

**Q: How many concurrent users can it test?**
A: A single machine handles thousands of users (gevent coroutines); distributed setups easily reach tens of thousands. Not as efficient per-machine as k6, but Python makes scripting more flexible.

**Q: Compared to k6?**
A: Locust uses Python (more flexible, can directly call any Python library); k6 uses JS (Go runtime is more efficient). Pick based on team language preference.

## Sources

- Docs: https://docs.locust.io
- GitHub: https://github.com/locustio/locust
- License: MIT

---
Source: https://tokrepo.com/en/workflows/locust-scalable-load-testing-pure-python-42405496
Author: AI Open Source