Locust Project Guidelines for AI Agents

Locust is a developer-friendly, open-source load testing framework. This guide helps AI agents understand Locust's structure, conventions, and development practices. This file in itself was initially generated by Copilot.

For full API and usage docs, see https://docs.locust.io/en/stable/llms-full.txt (or the lighter index at https://docs.locust.io/en/stable/llms.txt).

Code Style & Formatting

• Language: Python 3.11+
• Line length: 120 characters (enforced by ruff)
• Linter: ruff (handles linting, import sorting, and upgrades)
• Type checking: mypy with ignore_missing_imports = true
• Import order: Locust imports come first (for gevent monkey patching), then stdlib, third-party, and local imports
• Ignored rules: E402, E501, E713, E731, E741, UP031, PERF203 (see pyproject.toml for details)

Run checks locally:

uv run ruff check locust/
uv run mypy locust/

Architecture

Core Components

• locust/: Main package
  • user/: User classes (HttpUser, User)
  • runners.py: Test execution and distributed coordination
  • stats.py: Request/response statistics
  • web.py, webui/: Web UI (Flask-based)
  • clients.py: HTTP client implementations
  • rpc/: Remote procedure calls for distributed testing
  • contrib/: Optional protocol/database clients
• locust/test/: Unit and integration tests (pytest)
• examples/: Example locustfiles demonstrating various patterns
• docs/: Sphinx documentation (.rst format)

Key Patterns

• Event-driven: Uses gevent for concurrency; events for messaging (event.py)
• Pluggable: Can test multiple protocols (HTTP, gRPC, MQTT, MQTT, etc.)

Build and Test

Setup Development Environment

# Install uv (build system)
# Clone and enter the repo
uv sync                    # Install dependencies with hatch groups

Running Tests

uv run pytest locust/test                 # Run all tests
uv run pytest locust/test/test_main.py    # Run specific test file
hatch test                                # Test across multiple Python versions

Running Linting and Type Checks

uv run pre-commit run --all-files  # Auto-fix formatting issues
uv run ruff check locust/          # Check linting rules
uv run mypy locust/                # Type checking

Building and Installing Locally

uv run locust               # Run your modified code

Documentation

• Format: reStructuredText (.rst) in docs/
• Generate locally: make build_docs
• Contributing docs: Add documentation for new features if they are user-facing
• Examples: Add example scripts in examples/

See docs/developing-locust.rst for detailed contribution instructions.

Conventions

File Organization

• Community contributed User classes: Go in locust/contrib/ (e.g., grpc/, mqtt/)
• Core User classes: HttpUser and FastHttpUser
• Tests: Mirror source structure in locust/test/

Naming and Patterns

• User classes: Inherit from User or HttpUser; define @task methods for test scenarios
• Statistics: Custom stats reporters hook into stats_* events
• Events: Use event.request, event.test_start, event.test_stop, etc.
• Load shapes: Implement LoadShape for custom load profiles

Testing Conventions

• Pytest: All tests use pytest (not unittest)
• Test discovery: Files named test_*.py or *_test.py
• Mocking: Use pytest fixtures; mock external services
• Example files: May be excluded from strict linting (see pyproject.toml)

Gevent and Concurrency

• Monkey patching: Always import from locust import ... before other imports
• Greenlets: Users run in separate greenlets; use normal blocking code
• Async patterns: Use gevent for concurrency, not asyncio

Key Dependencies

• gevent: Green threads for concurrency
• Flask: Web UI backend
• requests: HTTP client (with geventhttpclient option)
• msgpack: Message serialization for distributed testing
• pyzmq: Distributed communication
• pytest: Test framework
• ruff: Code quality and formatting

Distributed Testing

• Master-worker architecture: locust/runners.py, locust/rpc/
• Coordination: Uses ZMQ for inter-process communication
• Event propagation: Custom events sync across distributed nodes
• Refer to docs/running-distributed.rst for patterns

Common Tasks

Adding a New Protocol Client

1. Create a module in locust/contrib/<protocol>/
2. Implement a user class inheriting from User
3. Add tests in locust/test/test_<protocol>.py
4. Document in docs/testing-other-systems.rst
5. Add example in examples/<protocol>/

Adding a Feature to Core

1. Modify relevant file (e.g., locust/runners.py for test execution)
2. Add comprehensive tests
3. Update documentation in docs/
4. Run full test suite: uv run pytest locust/test

Debugging

• Run with -v (verbose) or --loglevel=DEBUG for debug output
• See docs/running-in-debugger.rst for IDE debugging

Python Version Support

• Minimum: Python 3.11
• Tested versions: 3.11, 3.12, 3.13, 3.14, 3.15 (via hatch environments)
• Use modern Python syntax; avoid deprecated patterns

Pre-commit and CI/CD

• If installed, pre-commit automatically runs ruff and mypy checks before commits
• See .pre-commit-config.yaml for hook configuration
• GitHub Actions runs full test suite on PRs

Links

• Official Documentation
• GitHub Repository
• Contributing Guide
• Writing Locustfiles