test-doctor

测试诊断

将测试视为对产品的保护，而非对实现的证明。对每项测试都问：“如果这项测试失败，可能是哪个用户可见功能或文档所述契约出了问题？”如果没有具体答案，就要求提供证据，说明该测试为何值得保留。

选择工作模式

• 对于审计、分析、诊断或规划请求，只检查并报告，不编辑文件。
• 对于明确的变更请求，先进行审计，然后以最小幅度修改测试，同时保留或加强回归保护。
• 除非用户明确要求修复，否则不要仅为满足测试而更改产品行为。
• 在评估预期行为前，先阅读仓库说明以及相关设计或契约文档。若发现契约不一致，应报告这一问题，而不是猜测哪一方正确。

建立证据基础

1. 定位测试文件、测试固件、辅助工具、配置、软件包脚本和 CI 工作流。
2. 确定源码包的边界和公共入口。
3. 阅读相关功能、架构、API 和错误修复文档。
4. 如果可疑测试的存在原因不明，检查相关的 Git 历史记录。
5. 记录可用的测试命令及其覆盖范围。仅运行验证发现或所请求变更所需的命令。

对于大型仓库，从软件包级清单和高风险路径入手。只有在证据表明信号较弱、重复、脆弱或保护缺失时，才深入检查单项测试。

将测试映射到受保护的功能

创建一份简洁的映射表，每个测试文件或连贯的测试组占一行：

字段	含义
测试	文件及测试或测试套件名称
类型	单元测试、集成测试、契约测试、组件测试或 E2E 测试
受保护的功能	测试失败所能揭示的用户行为或文档所述契约
边界	真实依赖项和替代依赖项
风险	回归的影响和可能性
成本	运行时间、设置复杂度、脆弱性和维护负担
置信度	高、中或低，并附证据

证据不足时，将受保护的功能标记为 unclear。不要仅凭测试名称臆测意图。

评估测试价值

将以下内容作为相对启发式标准，而非虚构的数值测量：

Test value = user impact × regression risk × bug-detection strength
             --------------------------------------------------------
                            maintenance cost

将每个因素评为高、中或低，并说明存在争议的评级。

优先考虑保护以下内容的测试：

• 用户工作流、数据正确性、安全性、兼容性和恢复能力。
• 公共 API、提供程序接口、持久化格式、迁移以及跨软件包契约。
• 核心运行时编排、文件处理、会话状态和重要的失败路径。
• 曾经出错或容易回归的边界条件。

降低主要保护以下内容的测试的优先级：

• 私有辅助方法、内部对象结构、精确调用顺序或无关紧要的函数调用次数。
• 模拟配置，而非可观察行为。
• 与契约或用户影响无关的静态格式检查。
• 已在更强边界上受到更直接保护的重复路径。

对于包含大量快照、过多模拟、脆弱选择器、耦合内部 API、大型重复测试固件、依赖时序或环境设置耗时较长的测试，应提高其维护成本评级。

检测测试异味

实现耦合

标记对私有方法、内部状态、精确调用顺序或无关紧要的调用所做的断言。建议改为断言返回状态、持久化数据、发出的公共事件、渲染语义或外部可观察到的错误。

不要自动标记交互断言。当交互本身就是契约时，应保留此类断言，例如授权检查、幂等性、事务边界或必需的协议调用。

过度模拟

标记出大多数协作者都被模拟，且断言只是复述模拟行为的测试套件。优先选择范围最窄、最贴近现实的边界：

• 使用真实的领域逻辑和存储。
• 在能忠实反映实际行为时，使用内存数据库或文件系统。
• 为网络或模型提供方使用小型、确定性的伪实现。
• 仅在成本高、非确定性、具有破坏性或由外部拥有的边界使用模拟。

无效或空洞的测试

查找被跳过或被聚焦的测试、空测试、同义反复的断言、过时的 API、无法触及的设置、即使移除被测代码也无法失败的测试，以及接受无意义变动的快照。

谨慎分类被跳过的测试：关联了已知问题的测试，可能是延期覆盖，而非无效代码。

重复覆盖

按能力和故障模式对测试分组，而非按相似名称分组。只有在移除某个测试不会降低对某种独立回归的检测能力时，才将其覆盖归类为重复。优先把重复的设置和密切相关的生命周期行为合并为一个连贯的集成测试套件或契约测试套件。

过度使用快照

将快照用于稳定、便于审查的契约，例如无障碍输出、序列化协议或关键 UI 状态。用聚焦的语义断言替代宽泛的生成标记快照和嘈杂的组件快照。

缺少负向和边界覆盖

检查仅覆盖成功路径的测试套件，关注验证、权限、取消、重试、部分失败、并发、迁移、恢复和未知变体。只有在能明确指出具体契约和可信的回归时，才建议补充测试。

选择处理方式

每项发现只能选择一个主要操作：

• 保留：该测试能以合理成本保护独立行为。
• 删除：该测试无效、空洞或完全冗余，并且已明确指出保留的覆盖。
• 合并：多个测试保护同一项能力，但设置或断言重复。
• 迁移：该行为应由不同边界负责，通常是集成测试或契约测试。
• 重写：这项能力很重要，但当前断言保护了错误的抽象层。
• 提升：重复的低层测试表明缺少公开契约测试或端到端工作流测试。
• 新增：高风险能力缺少有效的回归保护。

建议删除测试时，必须指出保留的保护，或明确说明接受的覆盖缺口。

处理 Agent 和 Electron 应用

在相关情况下，检查以下高价值契约：

• 提供方：初始化、模型发现、流式传输、工具调用、推理支持、用量报告、取消和错误。
• 运行时：用户输入、上下文组装、模型请求、工具执行、持久化和最终响应。
• 存储：会话创建、消息追加、历史加载、迁移、恢复和损坏处理。
• 技能和插件：安装、发现、加载、执行、权限和故障隔离。
• 桌面 UI：通过公开的 preload 或 IPC 契约验证渲染进程行为、无障碍交互、持久化状态和平台差异。

仅保留提供方确实存在差异的提供方专属测试。将共同行为放入可复用的契约测试套件。

验证请求的更改

编辑前，明确指出更改前后受保护的能力。删除或合并测试时，保留替代覆盖的证据。

按比例进行验证：

1. 运行受影响范围最小的测试目标。
2. 只有在边界变更足以证明其合理性时，才运行所属软件包范围更广的测试目标。
3. 当现有覆盖率或变异测试工具能解决有争议的发现时，使用这些工具。
4. 仅在获得授权且安全时引入有针对性的变异；验证测试会失败，准确还原源代码，然后验证测试会通过。

不要仅仅因为测试通过就声称保护更强。说明这些断言能检测哪些可信的回归。

报告结果

按能力风险从高到低列出可执行的发现。每项发现均包括：

Priority:
Location:
Protected capability:
Evidence:
Problem:
Primary action:
Replacement or retained coverage:
Expected benefit:
Confidence:

然后提供：

1. 高、中、低价值覆盖范围摘要。仅当清单完整时才使用数量。
2. 按替代覆盖先落实、再删除的顺序制定迁移计划。
3. 根据已记录的行为说明缺失的高风险覆盖。
4. 已执行的验证以及仍存在的证据缺口。

如果没有可执行的发现，请直接说明，并列出剩余的覆盖范围或验证缺口。将观察到的事实与建议分开，并标注不确定的推断。