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]构建后端为hatchlinghatch-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 -py3.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 PYTHONUNBUFFERED1 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 UItest_web.py、命令行解析test_parser.py、分发test_dispatch.py等模块的完整测试套件。新增功能时在对应模块旁补一个test_*.py测试用例是项目约定俗成的做法。也可以在项目根目录执行make test达到与pytest -vv locust/test相同的效果。三、调试你的 locustfilerun_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把每个请求以表格形式打印到 stdouttype 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_streamimport sys class MyUser(FastHttpUser): task def t(self): self.client.get(http://example.com/, debug_streamsys.stderr)输出会包含完整的请求头与响应头状态行、Content-Encoding、Content-Type 等足以定位绝大多数协议层问题。注意这些手段在完整压测时同样可用但会产生大量输出。四、格式与静态检查ruff、mypy与typosLocust 使用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.41setup[1.39]cmd[0.01,0.01] seconds) congratulations :) (1.47 seconds)相关的完整配置在 pyproject.toml 的[tool.ruff]中目标 Python 为py311行宽 120lint.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_docsmake build_docs实际执行的是两步先uv sync --all-groups安装全部依赖分组包括docs组里的sphinx7.4.7、sphinx-rtd-theme3.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 UIReact TypeScript Vite 前端开发Locust 的 Web UI 是使用 React 和 TypeScript 构建的单页应用源码位于 locust/webui/src构建工具为 Vite配置见 locust/webui/vite.config.ts 与 vite.report.config.ts。6.1 环境准备Nodenvm与 Yarn前端构建依赖 Node 与 Yarn安装 Node推荐用 nvm 安装便于在版本间切换。先运行 nvm 官方安装命令然后用nvm --version验证安装成功。选择 Node 版本以 locust/webui/package.json 中engines声明的版本为准当前要求node 22.12.0$ nvm install {version} $ nvm alias default {version}安装 Yarn建议从 Yarn 官网单独安装避免通过 Node 附带安装用yarn --version验证。安装前端依赖$ cd locust/webui $ yarn仓库根目录的make frontend_build则封装了yarn webui:install yarn webui:build两步方便不进入子目录直接构建。6.2 三种开发模式watch / dev / build# 开发模式一边跑 Locust 边看效果 $ yarn watchyarn watch会把静态文件输出到dist目录Vite 自动监听文件变化并增量重建实际是并行运行watch:ui与watch:report两个构建任务刷新页面即可看到改动。# 开发模式二不启动 Locust仅开发前端 $ yarn dev某些场景通常是调整样式时并不需要后端运行yarn dev会启动 Vite 开发服务器默认端口 4000打开dev.html供你单独预览。# 编译 Web UI 产物 $ yarn buildyarn build会先执行yarn cleanrimraf dist再并行执行build:ui主应用入口为index.html与auth.html和build:reportHTML 报告单文件使用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 提交代码前的标准自检流程如下测试hatch test全量通过涉及 Python 多版本时用hatch test -py版本抽查必要时用pytest locust/test/test_xxx.py::ClassName::test_method精确定位单个用例。调试locustfile 相关问题先用run_single_user单步调试HTTP 层问题用debuglevel/debug_stream抓取原始报文。代码质量hatch run lint:formatruff 检查 格式校验、hatch run lint:typesmypy、hatch run lint:spellingtypos全部通过提交前若安装了 pre-commit这些检查会自动执行。文档新增/变更功能同步更新 docs 下的.rst文档并本地执行make build_docs验证文档可正常构建。Web UI修改前端后运行yarn lint、yarn format、yarn type-check与yarn test最后yarn build或make frontend_build确认产物可编译。提交推送分支后在 GitHub 上对上游仓库发起 Pull Request。完成以上步骤你的改动就具备了进入 Locust 主干的基本条件。整个流程围绕 pyproject.tomlPython 侧构建/测试/lint/docs 配置、Makefile项目级快捷入口、locust/webui/package.json前端脚本与依赖三条主线展开理解这三份配置文件就等于掌握了 Locust 贡献开发的全部入口。【免费下载链接】locustWrite scalable load tests in plain Python 项目地址: https://gitcode.com/gh_mirrors/lo/locust创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考