测试

Hoshimi 的测试不访问网络，也不需要任何真实的渠道凭据：上游由假的渠道或 httpx.MockTransport 代替，每个测试都有自己的临时数据目录。提交前运行一次 python scripts/dev.py check，它覆盖 CI 的 Python 与 Web UI 检查。

一览复制锚点链接

Python 测试复制锚点链接

布局复制锚点链接

pytest 的配置在 pyproject.toml：testpaths = ["tests"]，并跳过沙箱运行留下的 tests/_pytest_tmp 与 tests/_tmp。

只运行一部分时直接调用 pytest（test-py 不接受选项）：

python -m pytest tests/core/test_registry.py
python -m pytest tests/api -k messages
python -m pytest -x -q

共享夹具复制锚点链接

tests/conftest.py 提供一个不访问网络的渠道和建立在它之上的服务与应用：

FakeProvider 注册在 PROVIDER_CLASSES["fake"] 中，否则保存设置时的重建会把 fake 当作未知渠道丢掉。

一个路由测试的样子：

def test_messages_defaults_to_json_and_counts_one_turn(client, services):
    response = client.post("/v1/messages", json=body(), headers={"anthropic-version": "2023-06-01"})
    assert response.status_code == 200
    message = response.json()
    assert message["id"].startswith("msg_")
    assert message["content"] == [{"type": "text", "text": "echo:fake-1:1"}]

常用写法复制锚点链接

• 渠道适配器：用 httpx.MockTransport 构造适配器的客户端，检查请求的地址、头和体，以及 stream_raw 产出的分片类型。例子见渠道适配器。
• Anthropic Messages：tests/api/test_native_messages.py 用官方 Anthropic SDK（dev 附加依赖中）的 JSON 与流式辅助函数访问网关，上游是本地的模拟传输，所以不需要真实凭据。tests/api/test_messages_heartbeat.py 单独检查心跳的时机、心跳不会切开完整的 SSE 帧，以及客户端断开时释放上游。用真实的 Claude Code 试用一个已配置的网关，见 Claude Code。
• 只在 POSIX 上运行的测试：Playground 的 shell 与后台命令测试在 Windows 上跳过（pytest.mark.skipif(os.name == "nt", ...)）；需要切换本地时区的用量测试在没有 time.tzset 的平台上跳过。
• 自己的 Services：需要特定设置时调用 make_services(default_model=..., ...)；需要多个渠道时传入额外的 FakeProvider 或子类。

Web UI 测试复制锚点链接

在 hoshimi/webui 中，bun run test 运行 Vitest，bun run typecheck 运行 vue-tsc；python scripts/dev.py test-web 依次运行两者。测试环境是 happy-dom，src/test/setup.ts 补上 @material/web 需要的 ElementInternals，src/test/motion-zero.css 把所有动效时长设为 0，测试永远不必等待过渡。Vitest 用 vmThreads 池运行（Windows 上工作线程会争抢创建临时目录）。

测试和被测文件放在一起（*.test.ts）。除了组件、仓库和查询的测试，有几组测试检查的是全局规则：

生成类型的检查复制锚点链接

python scripts/dev.py typegen-check 由当前代码重新生成 hoshimi/webui/src/api/schema.d.ts，再用 git diff --exit-code 比较。失败说明管理 API 的模型变了而类型没有重新生成：运行 python scripts/dev.py typegen 并提交 schema.d.ts。

在浏览器里检查布局：check_layout.py复制锚点链接

Web UI 中每个滚动区域只朝一个方向滚动（.app-scroll 纵向，.app-scroll-x 横向，例如代码块、表格和步骤条），所以其他任何地方出现横向滚动条都是布局错误。单元测试只能读源码；scripts/check_layout.py 在真实浏览器里找出这类错误。

pip install playwright && playwright install chromium firefox
python scripts/check_layout.py --url http://127.0.0.1:10600

先启动一个服务器（hoshimi serve 或 python scripts/dev.py dev），最好在 Playground 里有一段对话，这样聊天列表、编辑器和菜单都有东西可以打开。脚本：

• 依次打开 /overview、/models、/channels、/usage、/playground、/settings；
• 在 Chromium（显示滚动条，与桌面一致）和 Firefox（滚动条浮动）中，以 320、360、600、900、1280、1600 像素的窗口宽度检查；
• 每个页面先检查打开时的样子，再打开第一个菜单；Playground 还会切换聊天列表、打开消息编辑器和对话菜单；
• 报告每个内部比可见部分更宽的区域，以及超出的元素和超出的像素。

没有发现溢出时退出码为 0，发现时为 1，没有安装 Playwright 时为 2，所以它可以作为发布前的一道检查。Playwright 不是项目依赖，CI 也不运行它。

CI 中的检查复制锚点链接

CI 的共享检查（.github/workflows/checks.yml）运行：

依赖用 uv 安装：ty 与 pytest 作业安装 .[dev,google,bedrock]。共享检查还会对文档站做类型检查、测试和构建。发布流程见 CI 与发布。