QA 与测试规范

按规范编写测试计划、测试用例、自动化脚本与测试报告；并在排查缺陷或测试失败时采用系统性排错与根因分析（先确认根因再修复，禁止只治标不治本）。规范细节见 references/REFERENCE.md。

何时使用

• 用户要求「写一份测试计划」「设计 xxx 的测试用例」「补充接口/UI 自动化」「生成测试报告」
• 用户提供需求/接口/页面说明，需要据此设计测试策略、用例或自动化脚本
• 用户需要评审或规范化现有测试文档/用例/脚本
• 用户排查缺陷、修复测试失败、分析异常行为或「为什么又挂了」— 使用系统性排错（见下方「系统性排错与根因分析」）

系统性排错与根因分析

在排查缺陷、修复失败用例或分析异常行为时，必须先做根因分析，再实施修复。禁止仅做症状层面的修补而掩盖真实问题。

核心原则

未确认根因前不实施修复（NO FIXES WITHOUT ROOT CAUSE FIRST）。

不应对症下药式地打补丁；先弄清「为什么失败」，再改代码。

四阶段框架

1. 阶段一：根因调查（改代码之前）

   • 完整阅读报错信息（每一句都有用）
   • 稳定复现问题（无法复现则无法验证修复）
   • 查看近期变更（失败前改了什么）
   • 收集诊断证据：日志、堆栈、状态 dump
   • 追踪数据流：沿调用链找到错误值的来源
     根因追溯：从现象 → 直接产生错误的代码 → 谁调用了它 → 沿调用栈向上 → 找到最初触发问题的位置。不要只修报错点，要追溯到原始触发点。

2. 阶段二：模式对比

   • 找到能正常工作的类似代码
   • 完整对比实现差异（不要只扫一眼）
   • 明确「正常」与「异常」的差异点
   • 理清依赖与前提条件

3. 阶段三：假设与验证

   • 提出一条清晰假设（例如「错误是因为 X」）
   • 设计最小复现/最小改动（一次只动一个变量）
   • 预测「若假设成立，应看到什么」
   • 执行验证并对照预测
   • 不符合则修正假设，符合则进入实施

4. 阶段四：实施与验证

   • 先写失败用例（能复现该缺陷）
   • 实施单一、针对根因的修复（不治标）
   • 确认该用例通过
   • 跑完整测试套件，确认无回归
     规则：若连续三次修复均失败或引出新问题，应停止补丁式修改，视为设计/架构问题，需要讨论与重新评估。

过程红线

一旦出现以下想法，应立即停下：

• 「先快速修一下，以后再查根因」
• 多次修复失败后仍「再试一次修复」
• 未理解原因就认为「这样改应该能行」
• 没有明确假设就「先试一下…」
• 「在我这儿能跑」却不排查环境/数据差异

与测试的衔接

• 修复前：用可复现该缺陷的用例（或最小复现步骤）锁定根因并验证假设。
• 修复后：该用例应由红变绿，并跑全量用例防回归。
• 详细场景（测试失败、运行时错误、间歇性失败等）与检查清单见 references/REFERENCE.md「系统性排错」。

---

执行流程（测试计划 / 用例 / 自动化 / 报告）

1. 确认测试范围

向用户确认：

• 被测对象：功能模块、接口、页面或端到端场景；是否有需求文档、接口契约或 UI 设计
• 测试类型：功能、接口、UI、性能、安全等；是否需自动化及框架（pytest、Playwright、Postman 等）
• 已有约定：项目内是否有 docs/测试规范.md、用例模板、自动化目录结构，优先遵从

2. 查阅规范

• 若存在 docs/测试规范.md 或 docs/xx规范.md：优先读取其中的用例格式、优先级定义、命名约定、自动化目录与报告格式。
• 无则按 references/REFERENCE.md 的通用约定执行。

3. 按规范产出

产出顺序与要点：

1. 测试计划（若需要）
   目标与范围、测试类型、环境与数据、进度与风险、准入/准出标准；与需求或迭代对齐。

2. 测试用例

   • 用例 ID、标题、前置条件、步骤、预期结果、优先级、所属模块；格式见 REFERENCE。
   • 覆盖正常、边界与异常；步骤可执行、预期可验证；避免重复与模糊表述。

3. 自动化脚本（若需要）

   • 接口测试：pytest + requests 或项目既有 client；用例与实现分离，数据与断言清晰。
   • UI 测试：Playwright/Selenium 等；页面对象或组件封装，避免裸定位与重复步骤。
   • 命名：test_{场景}_{预期}；目录与文件与模块/功能对应。

4. 测试报告（若需要）
   执行结果汇总、通过/失败/阻塞统计、缺陷摘要、风险与建议；可基于模板生成。

4. 规范要点

• 用例与脚本：中文描述可接受，自动化代码与注释建议中英统一（与项目一致）。
• 用例 ID：建议模块前缀 + 序号，便于追溯与去重。
• 优先级：P0/P1/P2 或高/中/低，与项目定义一致。
• 禁止：无预期结果的步骤、无法自动断言的主观描述、硬编码敏感数据、跳过必要的清理与还原。

5. 交付物清单

单次执行应包含（按需）：

1. 测试计划文档（范围、策略、进度、准出标准）
2. 测试用例（表格或 Markdown/Excel 等，含 ID、步骤、预期、优先级）
3. 自动化脚本与说明（目录结构、运行方式、依赖）
4. 测试报告（执行结果、统计、缺陷与风险）
5. 若项目有约定，同步更新 docs/ 下测试相关文档
6. 排错场景：根因结论、复现步骤、失败用例（修复前红）、修复后验证与全量回归结果

资产与参考

• 规范与示例汇总（含系统性排错详细场景与检查清单）：references/REFERENCE.md
• 项目内规范：docs/测试规范.md、docs/xx规范.md（若存在，优先遵从）
• 既有自动化：tests/、e2e/、testcases/ 等（保持风格与命名一致）