AGENTS.md · locustio/locust

Sections

1. Code Style & Formatting
2. Architecture
3. Build and Test
4. Documentation
5. Conventions
6. Key Dependencies
7. Distributed Testing
8. Common Tasks
9. Python Version Support
10. Pre-commit and CI/CD
11. Links

First lines (shown under the repo's MIT license)

# 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:
```bash
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
```bash
# Install uv (build system)
# Clone and enter the repo
uv sync                    # Install dependencies with hatch groups
```

### Running Tests
```bash
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
```bash
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
```bash
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](https://docs.locust.io/)
- [GitHub Repository](https://github.com/locustio/locust)
- [Contributing Guide](docs/developing-locust.rst)
- [Writing Locustfiles](docs/writing-a-locustfile.rst)