Operit PR Check Android 构建与单测拆分:验证流程与 fork 测试实战
Operit PR Check Android 构建与单测拆分:验证流程与 fork 测试实战
本文以 Operit 仓库中
pr_check_android_build_split_20260815改造的验证记录为骨架,完整还原「Android build 与 Android JVM tests 独立 job」改造从静态检查、fork 线上验证到问题修复的完整闭环。读者将掌握如何为拆分后的 CI 设计可复现的验证矩阵、如何用 fork PR 观察 job 独立性,以及如何定位并修复拆分后暴露的既有测试源码问题。
一、背景:为什么要把构建与单测拆成两个 job
在拆分之前,PR Check 的 Candidate checks 单个 job 同时承担作用域规划、快速检查、JavaScript 专项检查、Android 资源编译、依赖准备和完整 Android Gradle 检查;完整 Android lane 在同一个 job 中依次执行 assembleDebug 和 :app:testDebugUnitTest。Android Build workflow 也在编译后继续执行 JVM 单测。
这带来三个直接问题:
- 共享失败边界:单测失败会连带判定构建失败,APK 编译结果无法独立呈现;
- 共享 runner 时间:测试与构建串行排队,拉长整个 CI 反馈周期;
- 共享产物上传条件:构建产物(APK/AAB)的上传被测试结果牵连。
改造目标(详见 1_JobBoundaries.md 与 index.md)是把职责拆开:
Fast checks只负责规划、快速门禁、资源 lane、WebChat 与 ToolPkg 专项检查;Android build仅在android_full作用域下运行assembleDebug;Android JVM tests在android_jvm或android_full作用域下运行 JVM 单测;- 两个 Android job 基于同一个 merge candidate,但各自拥有干净 workspace;
- 新增 job 的结果由最终的
Candidate checks聚合。
同时保留约束:仅有快速门禁的 PR 不能因不存在 Android job 而失败;Android build 必须自行生成 WebChat 和 ToolPkg 的 Gradle 输入;JVM test job 必须自行准备 Gradle 依赖和 native ripgrep;不在 job 之间传递未审计的 workspace,只复用既有缓存和 candidate checkout。
拆分完成后,3_Verification.md 记录了这套改造的验证设计、执行过程与问题修复,正是本文的主体。
二、静态验证:先在本地把规则钉死
任何线上验证之前,先做不依赖 runner 的静态验证,确保 workflow 语法、门禁逻辑和聚合语义本身正确。
2.1 检查 workflow YAML 与 actionlint
第一步是对 .github/workflows/ 下的 YAML 做双重校验:
- YAML 语法:用 Ruby Psych 的
Psych.parse_file做 AST 级解析(而非直接加载成 Ruby 对象),确认语法合法; - actionlint:对变更的 workflow 文件运行 actionlint(仓库使用 v1.7.12,并先通过 sha256 校验下载归档再解压执行),检查
on、jobs、needs、if条件等结构的正确性。
这一步骤的实际命令实现可在 pr-check.yml 的 Check changed YAML and Actions workflows step 中查看:它先 git diff --name-only 收集 base..candidate 之间变更的 *.yml/*.yaml 文件,再按路径筛选出 .github/workflows/*.yml 交给 actionlint。
2.2 运行 CI Python 单元测试
门禁逻辑本身是用标准库 unittest 写的,命令为:
python3 -B -m unittest discover -s ci/test -p 'test_*.py'
仓库 ci/test/ 下共有 6 个测试文件,实测合计 46 个 test_* 用例,与验证记录中「46 个 CI 门禁单元测试」一致:
| 测试文件 | 用例数 | 覆盖对象 |
|---|---|---|
| test_pr_check.py | 13 | candidate 契约、scope 分类 |
| test_localizations.py | 11 | 本地化检查器 |
| test_android_dependencies.py | 10 | Android 依赖下载/准备 |
| test_markdown_links.py | 7 | Markdown 链接检查 |
| test_toolpkg_sync.py | 4 | ToolPkg 示例同步 |
| test_repo_hygiene.py | 1 | 仓库卫生检查 |
这些用例由 pr-check.yml 的 Check gate implementation step 执行(continue-on-error: true,收集诊断后由后续 step 统一裁决)。
2.3 检查 scope 分类、job 条件与聚合逻辑
这是静态验证中最关键的一环:确认改动路径被分到正确的 lane。分类实现集中在 ci/script/pr_check.py:
ANDROID_FULL_PATTERNS定义哪些路径会触发完整 Android lane(如cmake/**、gradle.properties、tools/native_ripgrep/**、.github/workflows/android-*.yml等);ANDROID_MODULE_ROOTS列出独立原生模块根(avator/dragonbones、avator/fbx、avator/mmd、llm/llama、llm/mnn、quickjs、showerclient、terminal),命中任一即android_full;- 对
app/下的普通改动,除翻译资源外默认归入android_jvm;纯翻译资源(values-*/strings.xml、locales_config.xml)走资源 lane(android_resources,只用 aapt2 compile 校验资源语法,不触发完整构建); android_instrumentation在命中app/src/androidTest/时置真,测试 job 会额外编译 AndroidTest 源码。
从源码结构可以推断,scope 判定顺序是「先 full、再资源、再 jvm」:android_jvm = android_jvm_change and not android_full,android_resources = resource_change and not android_jvm and not android_full(见 pr_check.py)。
对应的 job 条件写在各 workflow 中:
Android build只当needs.fast.result == 'success' && needs.fast.outputs.android_full == 'true'时运行(pr-check.yml);Android JVM tests当android_jvm == 'true' || android_full == 'true'时运行(pr-check.yml);Candidate checks聚合三个 job,用同一套check_stage函数按Required列决定是否阻断,并在 step summary 输出表格(pr-check.yml)。
值得注意的边界用例在 test_pr_check.py 中有明确覆盖:
- 纯翻译改动只走资源 lane,不触发 JVM/完整 lane(
test_translation_only_uses_resource_lane); - 默认
values/strings.xml走 JVM lane(test_default_strings_use_jvm_lane); - CMake 或 Android workflow 改动走 full lane(
test_native_change_uses_full_lane、test_android_workflow_changes_use_full_lane); - AndroidTest 源码同时触发 JVM 与 instrumentation 编译(
test_android_test_source_uses_instrumentation_compile); - candidate 必须恰好有两个父提交且与事件中的 base/head 一致,否则拒绝(
test_stale_branch_uses_candidate_first_parent_diff、test_non_merge_candidate_is_rejected)。
三、线上验证:用 fork 分支观察 job 独立性
静态验证通过后,进入线上验证。由于不能直接在 upstream 仓库提交,验证流程采用 fork 隔离:
- 把改动推送到 fork 的
ci/split-android-pr-check分支; - 在 fork 中创建指向 fork
main的测试 PR; - 观察
Android build与Android JVM tests两个 job 是否各自独立启动、独立呈现结果; - 人为构造「构建失败但单测通过」「单测失败但构建通过」两种场景,确认一方失败时另一方仍保留自己的结果;
- 确认无 Android 改动的 PR 不会被错误阻断(即不触发 Android job 的 PR 必须正常通过);
- 全部通过后再由用户决定是否提交 upstream。
这套流程的意义在于:fork PR 触发的是与 upstream 完全相同的 Actions 流水线,但不会污染正式仓库的合并历史与门禁状态。ci/README.md 的「PR check lanes」一节也说明了同样的安全边界——PR workflow 只有 contents: read 权限,不读取仓库 secret,也不上传 APK/AAB,因此可以在 fork 环境安全复现。
3.1 fork 验证中需要盯住的观察点
根据 pr-check.yml 的实际结构,验证时应重点确认:
needs.fast是否只被fastjob 触发,两个 Android job 之间没有needs依赖(并行关系);Android buildjob 是否包含 test step(拆分后已删除 JVM test 输入和 test step,只保留依赖、assets 生成、Gradle build 和产物上传);Android JVM testsjob 是否运行:app:testDebugUnitTest,并在android_instrumentation时追加:app:compileDebugAndroidTestKotlin与:app:compileDebugAndroidTestJavaWithJavac(pr-check.yml);Android build是否自行完成 WebChat assets 构建(npm run build:webchat)与 ToolPkg 示例同步(sync_example_packages.py --no-hot-reload),即「必须自行生成 Gradle 输入」的约束是否落实(pr-check.yml)。
四、验证结果:两轮 fork PR 与问题修复
4.1 Fork PR #15:验证 job 独立性并暴露既有测试缺陷
第一轮验证(Fork PR #15)得到以下结果:
- Fast checks 通过:包含 46 个 CI 门禁单元测试和 actionlint 检查;
Android buildjob 通过:assembleDebug完成,构建报告生成;Android JVM testsjob 独立启动,并执行到 Gradle 测试编译阶段;Candidate checks正确记录Android build=success、Android JVM tests=failure——这正是拆分想要的效果:单测失败不再拖垮构建判定。
拆分同时也放大了此前被「同 job 顺序执行」掩盖的问题:首轮 JVM 测试暴露了 upstream 既有的测试源码错误,包括:
ProviderUsageCancellationTest.kt(provider 取消传播测试);RecordingSQLiteDriver.kt(SQLite 记录驱动测试夹具);TokenCanonicalTotalsTest.kt与TokenCostCalculatorTest.kt(token 统计相关测试)。
修复方式为:补齐导入和参数、删除过期测试夹具,并修正日志与 Gemini usage 测试夹具。其中 TokenCostCalculatorTest.kt 目前仍存于 app/src/test/java/com/ai/assistance/operit/data/stats/TokenCostCalculatorTest.kt,可继续作为理解 token 统计逻辑的测试入口;RecordingSQLiteDriver.kt 与 TokenCanonicalTotalsTest.kt 因属过期夹具/过期用例已被删除,故当前仓库中不再存在。
4.2 run 31835091374:只剩 cancellation 身份断言问题
修复后重新运行(run 31835091374),Android build 通过,JVM 测试仅剩 ProviderUsageCancellationTest.kt 中 3 个跨 IO dispatcher 的 cancellation 对象身份断言。
问题本质:provider 的 sendMessage 会通过其内部 IO context 派发,协程取消时抛出的 CancellationException 实例可能被重新创建,因此断言「抛出的异常对象与原异常是同一个对象(object identity)」是不可靠的——对象身份并非 provider 接口契约。
修复方式:改为验证取消消息语义,即只断言 expected.message 与捕获到的异常消息一致。当前实现可在 ProviderUsageCancellationTest.kt 中看到:
val expected = CancellationException("usage observer cancelled")
// ...
try {
response.collect { }
fail("usage callback cancellation must propagate")
} catch (actual: CancellationException) {
// Dispatching through the provider's IO context may recreate the cancellation instance;
// the callback contract is cancellation propagation, not object identity.
assertEquals(expected.message, actual.message)
}
这段注释(the callback contract is cancellation propagation, not object identity)正是对本次修复原则的源码级记录:契约是取消必须传播,而不是协程实例必须原样抵达。
4.3 Fork PR #14(run 31839888120):全绿
第二轮验证(Fork PR #14,run 31839888120)全部通过:Fast checks、Android JVM tests、Android build、Candidate checks 均为 success。同时,可信的 Android Build 手动运行也通过,并上传了 Android 报告和成功产物。
4.4 可信 workflow 的纯构建化验证
除了 PR workflow,改造还涉及两条可信 workflow:
- android-build.yml:
push到main或workflow_dispatch触发,只做「准备打包输入 → 执行 Gradle 构建 → 上传报告与产物」,不再包含 JVM 单测;支持assembleDebug、:app:assembleNightly、:app:assembleClone、:app:bundleRelease四种可选任务; - android-tests.yml:
push到main或workflow_dispatch触发,只运行:app:testDebugUnitTest并上传测试报告,不生成 APK/AAB。
两条 workflow 都复用「terminal 子模块初始化 → JDK/SDK/NDK → 依赖缓存恢复 → native ripgrep 编译 → local.properties 配置」这套准备步骤,与 PR workflow 中的对应 step 保持一致,保证可信构建与 PR 构建行为等价。
五、验证结论与交付判定
综合静态与线上验证,可以确认以下事实:
- Android 编译已在单测失败时独立完成——run 31835091374 中
Android build通过而 JVM 测试仅剩 cancellation 断言问题时即为证据; - JVM 测试与
Candidate checks聚合状态已通过最新 run 验证——run 31839888120 四项全绿; - 拆分后的 scope 分类与 job 条件有单元测试钉底——46 个门禁用例覆盖 candidate 契约与全部 lane 边界;
- fork 安全边界保留——PR workflow 无 secret、无 APK 上传,可信构建只在 main push / 手动触发时产出产物。
验证通过后,这套拆分方案才被允许提交 upstream。对任何想要复刻此改造的团队,可参照 1_JobBoundaries.md(边界契约)、2_WorkflowImplementation.md(实现要点)与本文(验证闭环)三份文档组合使用;本地提交前也可按 ci/README.md 的「Local checks」一节先跑一遍门禁单元测试与各检查器,把大部分问题拦截在推送之前。