Locust 源码贡献与开发指南：从开发环境搭建、测试调试到 Web UI 前端开发

Locust 源码贡献与开发指南：从开发环境搭建、测试调试到 Web UI 前端开发

【免费下载链接】locustWrite scalable load tests in plain Python 🚗💨项目地址: https://gitcode.com/gh_mirrors/lo/locust

本文是一份面向想要为 Locust 贡献代码的开发者的完整实战指南，覆盖在本地克隆仓库后用uv搭建可编辑开发环境、用hatch/pytest运行跨版本测试、借助run_single_user单用户调试 locustfile、用ruff保证代码风格，以及基于 React + TypeScript + Vite 修改 Locust Web UI 的完整流程。读完本文，你将具备从改一行 Python 代码到构建文档、编译前端并最终提交 Pull Request 的完整闭环能力。

一、开发环境搭建：用uv完成可编辑安装

Locust 当前使用uv作为包管理与构建工具（见 pyproject.toml 中的[build-system]，构建后端为hatchling+hatch-vcs）。标准的开发流程是：先在 GitHub 上 Fork 仓库，再克隆到本地并完成可编辑安装。

# 克隆你自己的 fork $ git clone git://github.com/<YourName>/locust.git # 安装 uv 构建系统（见 uv 官方安装文档） # [可选] 创建并激活虚拟环境 $ uv venv $ . .venv/bin/activate # 对 "locust" 包执行可编辑安装，同时安装开发与测试依赖 $ uv sync

安装完成后，uv --directory locust run locust将直接运行你自己修改过的代码，无需在改动后重新安装；如果你把项目装进了虚拟环境，也可以直接调用locust命令。

值得说明的是uv sync默认安装的依赖分组由 pyproject.toml 中的[tool.uv]配置决定：

[tool.uv] default-groups = ["build", "test", "lint"]

也就是说，默认会一次性装上构建（hatch、hatch-vcs）、测试（cryptography、pyquery、retry等）和代码质量（pre-commit、ruff、mypy、typos）三组依赖；文档构建（docs组）与发布（release组）依赖则不在默认范围内，需要时用uv sync --all-groups补齐。

另外，仓库根目录的 Makefile 提供了等价的快捷目标：make install内部会先执行check-uv校验uv二进制是否存在，再运行uv sync。这也是理解 Locust 构建约束的一个线索：构建 Python 包与构建前端分别强依赖uv与yarn。

提交前的两个好习惯

• pre-commit：安装 pre-commit 后，每次提交前会自动执行 lint 与格式检查/修复。
• 测试与文档：打开 Pull Request 之前务必保证全部测试通过；如果新增了功能，请同步在docs/*.rst中补充文档（这也是本次开发指南文档自身所在的目录）。
• 免环境开发：如果没有本地开发环境，可以在 fork 页面上点击Code→Create codespace on，用 GitHub Codespaces 直接开始编码与测试。

二、运行测试：hatch跨版本矩阵与pytest精确定位

Locust 使用hatch自动化地跨多个 Python 版本运行测试。所有测试：

$ hatch test

针对特定 Python 版本：

$ hatch test -py=3.14

当前仓库支持的 Python 版本矩阵可以在 pyproject.toml 的[[tool.hatch.envs.test.matrix]]中看到：3.11、3.12、3.13、3.14、3.15。hatch-test环境（本地开发默认环境）除了运行pytest之外，还会执行一个针对examples/debugging_advanced.py的冒烟脚本，验证高级调试示例能正常跑完：

[tool.hatch.envs.hatch-test.scripts] run = [ "pytest{env:HATCH_TEST_ARGS:} {args}", "bash -ec 'PYTHONUNBUFFERED=1 python3 examples/debugging_advanced.py | grep done'", ]

CI 环境的test:all脚本则等价于全量单测加上述冒烟测试的组合。如果需要更精细的控制，可以直接调用pytest：

# 全部测试 $ pytest locust/test # 单个测试 $ pytest locust/test/test_main.py::DistributedIntegrationTests::test_distributed_tags

测试代码集中在 locust/test 目录，包含覆盖运行器（test_runners.py）、统计（test_stats.py）、HTTP 客户端（test_http.py）、Web UI（test_web.py）、命令行解析（test_parser.py）、分发（test_dispatch.py）等模块的完整测试套件。新增功能时，在对应模块旁补一个test_*.py测试用例是项目约定俗成的做法。也可以在项目根目录执行make test达到与pytest -vv locust/test相同的效果。

三、调试你的 locustfile：run_single_user与打印 HTTP 通信

完整的调试主题参见文档 运行调试指南，这里提炼其核心思路：调试器与 gevent 这类复杂应用结合时常常出现各种干扰，Locust 为此专门提供了run_single_user方法（源码实现位于 locust/debug.py），它创建一个最小化的Environment，正常触发init与test_start事件，然后只启动一个User 实例供你逐步调试：

# 文件开头加上 debug 支持 from locust import HttpUser, task from locust.debug import run_single_user class MyUser(HttpUser): @task def t(self): self.client.get("/") host = "http://example.com" if __name__ == "__main__": run_single_user(MyUser)

调用run_single_user时它会注册一个 request 事件监听器（PrintListener，同样位于 locust/debug.py），把每个请求以表格形式打印到 stdout：

type name resp_ms exception GET /hello 38 ConnectionRefusedError(61, 'Connection refused') GET /hello 4 ConnectionRefusedError(61, 'Connection refused')

run_single_user还接受include_length、include_time、include_context、include_payload四个开关，分别控制是否额外打印响应长度、时间戳、请求上下文与请求体，以及一个loglevel参数（默认"WARNING"，传None可完全关闭日志以免干扰输出）。从源码注释可以看到两个重要细节：

• 它不会触发test_stop或quit事件（退出调试器时不会调用）；
• 它会把调用者脚本的文件名自动识别为 locustfile（通过inspect.stack()获取），方便测试代码里查找文件名。

多个 User 连续调试可参考 examples/debugging_advanced.py；基础的完整可运行示例见 examples/debugging.py。在 VS Code 中调试时，请确保调试器设置里开启了 gevent 支持（"gevent": true），并可以参考仓库自带的 .vscode/launch.json（调试单文件/场景）与 .vscode/launch_locust.json（调试完整 Locust 运行时，含 ramp up 与命令行解析）。如果出现sys.settrace() should not be used when the debugger is being used的警告，可以安全忽略。

排查 HTTP 请求失败的详细通信日志

当请求在 Locust 中失败、但在浏览器或其他应用中正常时，可以打开底层 HTTP 库的调试输出：

# 放在 locustfile 顶部（或目标请求之前），适用于 HttpUser（基于 python-requests） import logging from http.client import HTTPConnection HTTPConnection.debuglevel = 1 logging.basicConfig() logging.getLogger().setLevel(logging.DEBUG) requests_log = logging.getLogger("requests.packages.urllib3") requests_log.setLevel(logging.DEBUG) requests_log.propagate = True

对于FastHttpUser（基于 geventhttpclient），则只需在请求时传入debug_stream：

import sys class MyUser(FastHttpUser): @task def t(self): self.client.get("http://example.com/", debug_stream=sys.stderr)

输出会包含完整的请求头与响应头（状态行、Content-Encoding、Content-Type 等），足以定位绝大多数协议层问题。注意：这些手段在完整压测时同样可用，但会产生大量输出。

四、格式与静态检查：ruff、mypy与typos

Locust 使用ruff统一负责格式化与 lint，构建（CI）在代码不合规时会直接失败。VS Code 用户可以在保存时自动运行，其他编辑器则手动执行：

$ ruff check --fix <file_or_folder_to_be_formatted> $ ruff format <file_or_folder_to_be_formatted>

也可以对整个项目做一次完整校验（hatch run lint:format），输出类似：

$ hatch run lint:format ruff: commands[0]> ruff check . ruff: commands[1]> ruff format --check 104 files already formatted ruff: OK (1.41=setup[1.39]+cmd[0.01,0.01] seconds) congratulations :) (1.47 seconds)

相关的完整配置在 pyproject.toml 的[tool.ruff]中：目标 Python 为py311，行宽 120，lint.select覆盖E/F/W/UP/I001/FURB/PERF等规则组。一个值得注意的细节是 isort 的 section 顺序被定制为把locust放在首位，注释说明这是为了保证 locustfile 中import locust先于其他第三方库执行，从而让 gevent monkey patch 成功生效：

[tool.ruff.lint.isort] section-order = ["future", "locust", "standard-library", "third-party", "first-party", "local-folder"]

hatch run lint环境还包含另外两个检查脚本：types（运行mypy locust/，类型检查配置见[tool.mypy]）与spelling（运行typos .，拼写检查规则见仓库根目录的 _typos.toml）。提交前跑一遍hatch run lint:all即可覆盖全部代码质量检查。

五、构建文档：Sphinx 工作流

文档源码位于仓库的 docs 目录（RST 格式）。构建本地文档前，先补齐文档构建依赖：

$ uv sync --all-groups

然后构建：

$ make build_docs

make build_docs实际执行的是两步：先uv sync --all-groups安装全部依赖分组（包括docs组里的sphinx==7.4.7、sphinx-rtd-theme==3.1.0以及为部分 contrib 模块所需的pymilvus、psycopg、pymongo、qdrant-client等），再用uv run sphinx-build -b html docs/ docs/_build/生成 HTML。构建完成后打开docs/_build/index.html即可本地预览，或运行：

$ make serve_docs

该命令会在本机 80 端口起一个静态文件服务（uv run python -m http.server 80 -d docs/_build），浏览器访问http://localhost即可查看。

有意思的是，docs/conf.py 展示了文档构建的两个自动化细节：构建时会执行locust --help并把输出写入cli-help-output.txt嵌入文档；同时调用get_parser()（来自 locust/argument_parser.py）自动生成命令行选项/环境变量/配置文件键的三方对照表（config-options.rst）。这意味着命令行新增参数后，文档中的参数表是自动同步的，这也提醒贡献者：新增 CLI 参数时无需手工维护该表。此外 docs/_ext/llms_txt.py 是项目为构建 LLM 可读文档（llms.txt）而自研的 Sphinx 扩展，说明该项目在文档的可检索性上做了额外投入。

六、修改 Web UI：React + TypeScript + Vite 前端开发

Locust 的 Web UI 是使用 React 和 TypeScript 构建的单页应用，源码位于 locust/webui/src，构建工具为 Vite（配置见 locust/webui/vite.config.ts 与 vite.report.config.ts）。

6.1 环境准备：Node（nvm）与 Yarn

前端构建依赖 Node 与 Yarn：

1. 安装 Node：推荐用 nvm 安装，便于在版本间切换。先运行 nvm 官方安装命令，然后用nvm --version验证安装成功。

2. 选择 Node 版本：以 locust/webui/package.json 中engines声明的版本为准，当前要求node >=22.12.0：

   $ nvm install {version} $ nvm alias default {version}

3. 安装 Yarn：建议从 Yarn 官网单独安装（避免通过 Node 附带安装），用yarn --version验证。

4. 安装前端依赖：

   $ cd locust/webui $ yarn

仓库根目录的make frontend_build则封装了yarn webui:install && yarn webui:build两步，方便不进入子目录直接构建。

6.2 三种开发模式：watch / dev / build

# 开发模式一：边跑 Locust 边看效果 $ yarn watch

yarn watch会把静态文件输出到dist目录，Vite 自动监听文件变化并增量重建（实际是并行运行watch:ui与watch:report两个构建任务），刷新页面即可看到改动。

# 开发模式二：不启动 Locust，仅开发前端 $ yarn dev

某些场景（通常是调整样式时）并不需要后端运行，yarn dev会启动 Vite 开发服务器（默认端口 4000，打开dev.html）供你单独预览。

# 编译 Web UI 产物 $ yarn build

yarn build会先执行yarn clean（rimraf dist），再并行执行build:ui（主应用，入口为index.html与auth.html）和build:report（HTML 报告单文件，使用viteSingleFile插件打包成单一 HTML）。对应地，也可以用make frontend_build在仓库根目录完成整个前端构建。

6.3 质量门槛：lint / format / type-check

$ yarn lint # 检测 ESLint 失败项（eslint './src/**/*.{ts,tsx}'） $ yarn lint --fix # 自动修复可修复的问题 $ yarn format # Prettier 修复格式化问题（'**/**/*.{ts,tsx}'） $ yarn type-check # tsc 类型检查

Web UI 项目使用 TypeScript 严格类型检查，并且内置了 vitest 测试框架（yarn test运行vitest），测试用例与组件同目录存放于tests/子目录或*.test.tsx文件中，例如 DataTable.test.tsx、SwarmForm.test.tsx。修改前端组件时，为关键逻辑补充测试是保持项目质量的重要一环。前端的主要模块包括：统计表格（StatsTable）、失败/异常表（FailuresTable/ExceptionsTable）、图表（LineChart/SwarmCharts）、用户数/比率（SwarmRatios）、日志查看器（LogViewer）、Redux 状态（redux/slice）与主题系统（styles/theme.ts）等，改动前可以先浏览这些目录把握整体结构。

七、提交 PR 前的检查清单

综合全文，向 Locust 提交代码前的标准自检流程如下：

1. 测试：hatch test全量通过；涉及 Python 多版本时用hatch test -py=<版本>抽查；必要时用pytest locust/test/test_xxx.py::ClassName::test_method精确定位单个用例。
2. 调试：locustfile 相关问题先用run_single_user单步调试，HTTP 层问题用debuglevel/debug_stream抓取原始报文。
3. 代码质量：hatch run lint:format（ruff 检查 + 格式校验）、hatch run lint:types（mypy）、hatch run lint:spelling（typos）全部通过；提交前若安装了 pre-commit，这些检查会自动执行。
4. 文档：新增/变更功能同步更新 docs 下的.rst文档，并本地执行make build_docs验证文档可正常构建。
5. Web UI：修改前端后运行yarn lint、yarn format、yarn type-check与yarn test，最后yarn build（或make frontend_build）确认产物可编译。
6. 提交：推送分支后在 GitHub 上对上游仓库发起 Pull Request。

完成以上步骤，你的改动就具备了进入 Locust 主干的基本条件。整个流程围绕 pyproject.toml（Python 侧构建/测试/lint/docs 配置）、Makefile（项目级快捷入口）、locust/webui/package.json（前端脚本与依赖）三条主线展开，理解这三份配置文件，就等于掌握了 Locust 贡献开发的全部入口。

【免费下载链接】locustWrite scalable load tests in plain Python 🚗💨项目地址: https://gitcode.com/gh_mirrors/lo/locust