ykcheungab
433b76e43c
把丢失的 box 录像放回 apps/studio/tests/data/，修掉第 3 节 3–10 号与两处过时测试桩， 注册 timing 标记并让根目录收集零错误；新增 tools/gate.ps1 与可选的 pre-push 钩子。 验证：studio 524 通过 19 跳过、shared 467 通过 18 跳过、ui_check 632 项 0 失败、gate.ps1 退出码 0。 细节见 docs/test-repair-plan.zh.md。
76 lines
6.9 KiB
Markdown
76 lines
6.9 KiB
Markdown
# App 分层测试执行计划
|
|
|
|
状态：待实施。日期：2026-10-15。适用 shared、Autocal 和 Studio；本计划不改变测试断言或产品行为。先决条件见 [测试修复与门禁计划](test-repair-plan.zh.md)：现有失败清零、门禁可运行之后，本计划的分层选择才可靠。
|
|
|
|
目标是让日常修改只运行能验证其影响的测试，避免代理在每次小修改后重复执行全量。目录已按产品分开，首期保留原路径，先解决测试选择和执行规则。
|
|
|
|
## 当前情况与取舍
|
|
|
|
根 pyproject.toml 的 testpaths 同时包含 shared/tests、apps/autocal/tests、apps/studio/tests；没有指定路径的 pytest 会收集三者。最近一次 Autocal 全量记录为 476 项、约 89 秒，证据在 .scratch/autocal-review-fixes/final.xml；这是单次测量，不是耗时承诺。
|
|
|
|
沿用 pytest 和现有环境，不引入自动依赖分析、测试缓存或并行插件。先使用明确的文件分组和少量共享依赖规则；测试目录重排、Qt 启动优化和慢测试治理在取得耗时证据后另行安排。
|
|
|
|
## 执行规则
|
|
|
|
| 改动 | 最低验证范围 | 扩大条件 |
|
|
|---|---|---|
|
|
| 仅文档 | 文档门禁和链接核对 | 文档同时改变可执行示例时核对示例 |
|
|
| 文案、布局 | locale 检查或对应 UI 测试 | 控件状态或流程改变时加操作流程测试 |
|
|
| 单个业务函数 | 对应回归测试及直接调用方 | 影响文件格式、线程或公共接口时加集成测试 |
|
|
| Autocal / Studio 某功能 | 该功能文件组 | 涉及多个功能时取并集 |
|
|
| shared 某能力 | 对应 shared 测试及两个产品的相关消费者 | 消费者不明确时先查调用关系，再决定产品范围 |
|
|
| conftest、pytest 配置、环境依赖 | 受影响测试树及收集检查 | 根配置影响三棵测试树时运行仓库全量 |
|
|
| 发布或多模块重大变更 | 相关产品全量，公共基础变更时仓库全量 | 真实硬件、GL 和打包验证仍单独说明 |
|
|
|
|
代理开始验证前说明“改动 → 所选测试 → 扩大理由”。定向测试通过后结束验证；没有新增改动、失败或未解决风险时，不追加全量。全量只在最终候选状态运行一次；之后仅复验新改动涉及的测试，除非新改动再次触及公共基础。
|
|
|
|
**提交前跑一次 `tools/gate.ps1`。** 定向测试用于开发中，门禁用于“这一版可以交给别人”的那一刻：它依次跑改动文件的 lint、studio 全量、shared 全量、`ui_check.py`，并要求 `tools/known_failures.txt` 为空、跳过数与收集数在 `tools/skip_budget.txt` 之内。可选 `pre-push` 钩子会调用它（安装方式见 [README](../README.md)，不自动安装）。门禁平台是 **Windows**：测试渲染真实 Qt 控件，而 [测试修复与门禁计划](test-repair-plan.zh.md) 第 3 节的 11、13 号只在 Linux 上失败，Linux 的通过不等于同一结论。
|
|
|
|
不能通过跳过失败、删除断言或把必需测试标成可选来提速。测试缺依赖、收集为空或意外跳过必须报告。间歇性错误先保留证据，查明影响后只重跑受影响范围；不循环重跑全量碰运气。
|
|
|
|
## 拟提供的入口
|
|
|
|
新增 tools/test_scope.py，负责选择并调用现有 pytest。以下为拟议接口，尚不可直接使用：
|
|
|
|
```powershell
|
|
& .venv-build/Scripts/python.exe tools/test_scope.py --product autocal --area records --collect-only
|
|
& .venv-build/Scripts/python.exe tools/test_scope.py --product autocal --area records
|
|
& .venv-build/Scripts/python.exe tools/test_scope.py --files apps/autocal/tests/test_pose_move.py
|
|
& .venv-build/Scripts/python.exe tools/test_scope.py --product autocal --full
|
|
& .venv-build/Scripts/python.exe tools/test_scope.py --full
|
|
```
|
|
|
|
无参数、未知分组或缺失文件返回非零，不默认跑全量，也不静默减少范围。输出所选路径、选择理由、收集数量和耗时；提供唯一 scratch 目录、.active 标记、JUnit 报告及 -p no:cacheprovider。使用明确的项目解释器，并透传 pytest 退出码。
|
|
|
|
保留根 pytest 默认配置，避免改变已有入口语义；通过文档及仓库 AGENTS 指引代理优先使用分范围入口。直接指定 pytest 文件和用例仍然有效。
|
|
|
|
## 功能分组起点
|
|
|
|
| 产品 | 分组 | 主要内容 |
|
|
|---|---|---|
|
|
| Autocal | motion | kinematics、pose_move、poller、controller_sequence、units |
|
|
| Autocal | acquisition | finger_source_panel、manual_trial、multipoint、calibration_feedback |
|
|
| Autocal | records | session_review、record_overview、record_diagnostics、review_job |
|
|
| Autocal | ui | finger_panel、device_setup、move_buttons、locales、preferences |
|
|
| Studio | source / records / visualization / ui | 根据现有文件和调用关系建立明确文件组 |
|
|
| shared | acquisition / recording / force / visualization / contracts | 复用现有测试文件，不复制到产品目录 |
|
|
|
|
表中名称是初始分类，不是已核准的完整清单。跨域测试允许属于多个组，运行时去重。例如 multipoint_align 同时覆盖 motion 和 acquisition；录制契约修改应加入 shared 录制测试及 Autocal、Studio 的录制消费者测试。
|
|
|
|
## 实施任务与验收
|
|
|
|
| 顺序 | 工作与预计时间 | 验收与验证 |
|
|
|---|---|---|
|
|
| 1 | 梳理文件分组及共享消费者，1–2 小时 | 建立显式映射；检查每个现有测试文件至少归组一次，新文件未归组会被映射检查发现。只收集，不执行全量。 |
|
|
| 2 | 实现选择入口，2–3 小时 | 覆盖参数错误、并集去重、空集合、缺失文件、scratch 隔离和退出码；以假 pytest 子进程验证调度，不拿真实全量当入口单元测试。 |
|
|
| 3 | 接入代理执行规范，约 1 小时 | 仓库 AGENTS 链接执行指南，说明默认范围及停止条件；登记文档并运行文档门禁。不改工作区通用测试标准。 |
|
|
| 4 | 验证实际选择，1–2 小时 | 分别选择 Autocal 记录修复、Studio 局部界面、shared 录制契约三个场景；核对收集清单包含必要消费者，至少实际执行一个受影响组。 |
|
|
|
|
门禁平台：**Windows**。上表的定向验证可以在任何平台开发，但“提交前通过 `tools/gate.ps1`”这一条以 Windows 结果为准。
|
|
|
|
任务 2 依赖任务 1，任务 3 依赖入口可用，任务 4 最后验收。建议一名工程师顺序完成，总计约 5–8 小时；无需多个代理并行修改公共入口。
|
|
|
|
任务 1 后核对依赖覆盖，任务 2–3 后核对入口与规则一致。验收只运行调度工具测试、必要功能组和文档检查；不为证明调度工具可用而运行三个产品的全部测试。
|
|
|
|
完成标准：小改动有明确、可复现的定向命令；共享修改覆盖实际消费者；全量始终可显式执行；报告区别“所选测试通过”和“所有产品通过”。只有证明仍有主要耗时来自目录结构或 Qt 初始化，才启动后续重排或优化。
|