Hermes WebUI 怎么用 scripts/test.sh 在本地运行完整 pytest 测试套件

Hermes WebUI 怎么用 scripts/test.sh 在本地运行完整 pytest 测试套件

【免费下载链接】hermes-webuiHermes WebUI: The best way to use Hermes Agent from the web or from your phone!项目地址: https://gitcode.com/GitHub_Trending/he/hermes-webui

给 Hermes WebUI 提交改动前，需要在本地把项目的 pytest 测试套件跑一遍做验证。CONTRIBUTING.md 把这一步列为 Local Verification 的必做项，AGENTS.md 进一步要求：本地跑 pytest 一律走仓库自带的测试入口./scripts/test.sh，不要用裸的python3、python -m pytest或系统 pytest——脚本负责在仓库内创建并维护 Python 3.11–3.13 的.venv，避免本地误用不受支持的系统解释器。本文覆盖：准备条件、运行完整套件、判读结果、聚焦运行，以及脚本报错时的处理路径。

准备条件

• 机器上至少有一个受支持的 Python 解释器：3.11、3.12 或 3.13。脚本按python3.13、python3.12、python3.11、python3的顺序查找，取第一个版本合格的；都找不到时报错退出，提示安装 3.11/3.12/3.13 后重跑。
• 环境提供 bash（脚本头是#!/usr/bin/env bash）。
• 不需要预先安装任何测试依赖。脚本会检查.venv中是否缺少cryptography、mcp、pytest、pytest_asyncio、pytest_shard、pytest_timeout、ruff、yaml这些模块，缺哪个就通过pip install -r requirements-dev.txt补装。requirements-dev.txt 还包含-r requirements.txt（运行时依赖）以及 Office 预览测试用到的python-docx、openpyxl、python-pptx。

运行完整测试套件

在仓库根目录执行：

cd hermes-webui ./scripts/test.sh

scripts/test.sh 的实际行为（见脚本源码）：

1. 定位仓库根目录，检查已有的.venv：版本受支持且 pip 可用则直接复用；.venv的 Python 不受支持或无法运行 pip 时自动重建。
2. 没有可用.venv时，用支持版本的基础 Python 执行python -m venv创建；创建失败会清理并给出指引。
3. 依赖缺失时在.venv内安装requirements-dev.txt——依赖只装进仓库本地虚拟环境，不会装进系统或 Homebrew 解释器。
4. 不带参数时，脚本自动补全默认参数tests/ -v --timeout=60，最后exec python -m pytest，所以 pytest 的退出码就是脚本的退出码。

规模参考：README.md 给出的当前快照是约 11,500 个测试、约 1,150 个测试文件；CI 在 Python 3.11、3.12、3.13 上各以 3 个并行 shard 运行同一套件。本地跑完整套件的时间请按机器性能预估，文档没有给出固定耗时。

验证结果

• 脚本退出码为 0 说明全部通过；非 0 时 pytest 输出中会列出 failed/errored 的具体测试项。

• 只想确认收集数量而不是全量执行，TESTING.md 给出的命令是：

  ./scripts/test.sh tests/ --collect-only -q

• 脚本透传普通 pytest 参数，聚焦运行某个文件或目录即可，例如（README.md 示例为./scripts/test.sh tests/test_regressions.py -v）：

  # 将 tests/test_auth.py 替换为你要运行的测试文件或目录 ./scripts/test.sh tests/test_auth.py -v

• pytest.ini 中定义了integration（命中真实测试服务器或外部集成面）和reproduction（直接执行 issue 复现 fixture）两个 marker，定位特定类别的测试时可以作为 pytest 参数依据。

常见报错与处理

• 直接调用 pytest 报解释器不受支持：tests/conftest.py 开头有版本守卫，遇到不受支持的 Python 会以退出码 3 结束，提示Run ./scripts/test.sh so the repo-local supported .venv is used。AGENTS.md 的处理建议是：改回通过./scripts/test.sh运行，再去调试产品代码。

• 无法创建.venv：脚本报Could not create a working .venv ...，提示安装匹配的 venv/ensurepip 包（Debian/Ubuntu 上是python3.x-venv），或设置HERMES_WEBUI_TEST_PYTHON指向受支持解释器后重跑。

• 想用指定的基础解释器：

  # /path/to/python3.12 替换为本机 3.11/3.12/3.13 解释器的绝对路径 HERMES_WEBUI_TEST_PYTHON=/path/to/python3.12 ./scripts/test.sh tests/ -v

  该变量只决定创建/重建.venv时用的基础解释器，依赖仍装进仓库.venv。

• .venv是指向其他位置的符号链接：脚本拒绝通过 symlink 创建或清空虚拟环境，提示移除该 symlink 或设置HERMES_WEBUI_TEST_PYTHON后重跑。

测试隔离与环境副作用

按 tests/conftest.py 的说明：测试运行在一个独立的服务器实例上——端口是进程启动时自动绑定的127.0.0.1临时端口，状态目录独立，且每次完整运行前和 teardown 时都会清理；生产数据和真实 cron 任务不会被触碰。需要固定端口或状态目录（例如可复现地调试）时，可用环境变量HERMES_WEBUI_TEST_PORT/HERMES_WEBUI_TEST_STATE_DIR显式指定。

对环境的影响只有两点：脚本可能创建或重建仓库内的.venv（不写系统 Python），以及按requirements-dev.txt在.venv内安装包。除此之外不修改仓库文件。

与 CI 的一致性

CI 对每个 PR 运行与本地相同的 pytest 套件（Python 3.11/3.12/3.13 各 3 个并行 shard），并配套 ruff lint 门禁和浏览器 smoke 测试。本地套件通过是提交 PR 的前提；如果改动影响浏览器行为，CONTRIBUTING.md 还要求按 TESTING.md 中的手动检查项补充验证——那是独立于./scripts/test.sh的手动流程，不属于本文的执行范围。

【免费下载链接】hermes-webuiHermes WebUI: The best way to use Hermes Agent from the web or from your phone!项目地址: https://gitcode.com/GitHub_Trending/he/hermes-webui