orisys-app/docs/test-execution-plan.zh.md

# 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`（`-Serial` 改为逐个运行并实时显示输出），并要求 `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 初始化，才启动后续重排或优化。