Skip to main content
Orbi 用完整测试套件、分层覆盖率要求和仓库的远程 CI 检查为交付设置门禁。 仓库契约（见 AGENTS.md）：Python 代码的完整 pytest 套件， 分层覆盖率门禁（Issue #234）。同一契约在 Runner 机器本地和 GitHub 远端运行。

​
分层覆盖率策略

低于 95% 的代码只允许是非核心、可明确解释的历史/防御性分支；每个例外 必须在覆盖率报告中可定位。无理由的 # pragma: no cover 是契约违规 （静态测试钉住少数正当位置：__main__ 入口守卫和测试里一个防御性 except 守卫）。

​
本地契约命令

从仓库根目录运行（生产解释器 /usr/bin/python3，Python 3.14）。COVERAGE_FILE （coverage.py 官方环境变量）把覆盖率数据指到已排除的运行目录 .orbi/ （Issue #302）：worktree 根不会出现任何覆盖率产物，dirty-worktree 门禁 也就不会被它绊住：
贡献者本地怎么跑测试（虚拟环境、包装脚本、任何方式）是贡献者的私事—— 不是仓库契约，仓库不维护本地测试链（Issue #569）。 报告逐文件给出两个真实数字（行和分支）。两个门禁脚本才是门禁，不是 报告：tools/coverage_gate.py 在行层级或分支层级任一低于 95% 时退出非零 （它分别读取 coverage JSON 的 percent_statements_covered 和 percent_branches_covered——JSON 字段 percent_covered 是行+分支合并 百分比，绝不作为门禁），tools/diff_coverage_gate.py 在 base ref 之后变更的 Python 行或分支未达 100% 覆盖时退出非零。

​
远端 CI（GitHub Actions）

.github/workflows/ci.yml 在每次 pull_request 和每次 push 到 main 时运行同一契约：单个 job，actions/setup-python 固定 Python 3.14（GitHub-hosted runner 没有生产路径上的生产解释器，所以 workflow 固定同一 minor 版本，通过 PATH 上的 python3 运行相同命令），安装 requirements.txt，然后运行上面的契约命令——报告、tools/coverage_gate.py 和 tools/diff_coverage_gate.py origin/main（变更代码层级对照 PR base；纯 文档 PR 没有变更的 Python，直接通过）。没有 lint、没有矩阵、没有缓存。 workflow 自含环境声明——CI 的工具链属于 ci.yml，不属于仓库（Issue #569）。 Checkout 保持默认浅克隆并加 fetch-tags: true，随后用有界命令显式 抓取 base ref 和 +refs/tags/*:refs/tags/*。diff coverage 的 base 比较还会解除 shallow history；删除的一次性对账测试不再需要该设置。 发布文档测试用真实 tag objects： 发布文档测试（tests/test_docs_releases.py）用 git rev-parse / git cat-file 对 checkout 里每个已发布 tag 的真实 tag object 做校验，默认 --no-tags 抓取会让 tag object 缺失、测试以 could not get object info 失败（Issue #126）。被删除的发布对账测试 曾需要的完整历史 checkout（fetch-depth: 0）已随之移除（Issue #910）。 现有 tags 只是在 CI 里可见，不被移动、覆盖或重写。 CI 里还运行 Mintlify 文档构建 smoke（Issue #116）：官方 mint CLI 的 mint validate（严格构建校验，任何 warning 或 error 都退出非零） ——文档配置、页面和链接在远端同样被门禁。

​
macOS 兼容性 workflow（hosted 兼容性边界）

.github/workflows/ci-macos.yml 增加一个独立的、串行的 macOS job，在 每次 pull_request、每次 push 到 main 以及手动触发时运行：单个 job， 固定在 macos-15 runner 镜像上（绝不使用漂移的 macos-latest 标签）， actions/setup-python 固定 Python 3.14，安装 workflow 自己的测试 依赖，并做真实 runner 探测（sw_vers、Python 版本、launchctl 和 launchctl print gui/$(id -u)——用户的 launchd GUI domain 是一切 launchctl 操作依赖的 runner 级前提）。该 job 以单条有界命令运行完整 pytest 套件并保留真实退出码，从目录中性位置构建软件包并做 clean-venv wheel smoke（orbi --version、orbi --help、site-packages 导入源）， 且在不真实安装的前提下演练安装器的 Darwin 分支：bash -n install.sh、 对 launchd plist 模板 plutil -lint、在临时 ORBI_HOME 里以 PATH 桩 运行安装器入口——真实的 macOS uname/launchctl 通过调度器门禁， 桩 git 在 clone 步骤前停下。hosted macOS 镜像没有 GNU coreutils 的 timeout（与 install.sh 处理的限制相同，Issue #868），workflow 用 perl alarm 提供一行 timeout 垫片，让每条命令保持文档规定的 timeout <秒> <命令> 形式。该 job 绝不改动 runner 自身的 launchd 部署（探测只读，不 enable/bootstrap）。 边界是刻意且诚实的：hosted macOS CI 校验 macOS 代码路径（测试、打包、 安装器逻辑）和 runner 级 launchd 前提——它无法证明真实用户的登录 GUI 会话、凭据、模型 provider 或完整的 GitHub Issue 到 merge 旅程，也不能 替代真实 Mac 硬件上的真实 macOS launchd smoke。同样的诚实也适用于套件 内部：部署、setup、doctor 与健康检查契约通过 systemd_scheduler 测试 fixture 钉在 systemd 实现上（launchd 实现保有自己基于 fakes 的测试）， 基于 /proc 的真实子进程 idle-recovery 场景与 runner 子进程 e2e 场景 在 Darwin 上以明确理由跳过——上方的 Ubuntu workflow 仍是它们唯一的 权威。覆盖率与变更代码门禁仍 以上面的 Ubuntu workflow 为准；macOS job 对任何测试、打包或安装器兼容 性失败仍然变红——没有任何失败被吞掉或洗成通过。 CI 红的时候 PR 不可合并——Runner 的 merge 门禁也要求 PR mergeable。

​
测试覆盖什么

  • 行为测试：runner、CLI、slots、进度发布、活动流、 resume/review/merge 逻辑（套件主体，包括针对真实 git 和 gh fixture 的端到端测试）。
  • 静态契约测试：把仓库钉在它自己的文档和文件上：AGENTS.md 契约项、标签集、systemd units（每 5 分钟调度、preflight）、CI workflow、LICENSE、docs/ 下的文档站（本页的声明由 tests/test_docs_site.py 强制执行；中文页面和 EN/ZH 同一事实源由 tests/test_docs_i18n.py 强制执行；Mermaid 图由 tests/test_docs_mermaid.py 强制执行）。
改代码时，在同一个 PR 里更新或新增测试，保持覆盖率门禁绿。