# TEST_PLAN.md —— 测试策略与轮次纪律

> 版本 1.0 ｜ 作者 PM ｜ 本文件由 PM 独占写入，所有开发/测试 agent **只读**
>
> 本文件定义「怎么测」。测什么以 `PRD.md` 为准，用例在 `TEST_CASES.md`（T 编写）。

---

## 1. 测试分层

| 层 | 工具 | 归属 | 覆盖对象 | 运行方式 |
|---|---|---|---|---|
| L1 后端单元 | pytest | A1/A2/A3 自测 | normalize 别名收敛、SSE 帧解析、阶段→相位映射、SQLite CRUD、错误信封 | `cd sdk && pytest tests -m unit` |
| L2 后端接口 | pytest + respx（mock 上游） | T 主写，A 组配合 | 每个 BFF 接口的正常/降级/超时/重试路径 | `pytest tests -m api` |
| L2s 上游 smoke | 脚本 | T | 对真实 7920/8000/Neo4j 的最小连通验证（**不在 CI 每轮跑**，仅集成点与验收前跑一次） | `bash tests/smoke_upstreams.sh` |
| L3 前端单元 | Vitest | B 组自测 + T 补写 | stores、SSE parser、labels 映射、modes 参数集、工具函数 | `cd ui && npx vitest run` |
| L4 前端组件 | Vitest + @vue/test-utils | B 组自测 + T 补写 | 每个组件的全部状态（默认/悬停/激活/禁用/加载/空/错误） | 同上 |
| L5 端到端 | Playwright | T | 完整流程 × 三档视口 | `npx playwright test` |
| L6 验收 | 人工 + 浏览器 | PM | 真实上游 + 视觉走查 | 见验收脚本 |

## 2. 覆盖率定义（100% 的可验证判定）

1. **需求追溯（主门禁）**：`PRD.md` 的 81 个 `FR-*`（FR-RESP-013 除外，为可选项）中，**每一个**在 `TEST_CASES.md` 追溯矩阵中至少映射一条 `TC-*`；同时**无孤儿 TC**（每条用例必须追溯到至少一个 FR）。双向映射完整性 = 100%。
2. **行覆盖（辅门禁）**：后端 pytest ≥85%，前端 Vitest ≥80%。未达标不能宣称 100%，但行覆盖达标**不替代**需求覆盖。

测试 agent 每轮报告首页必须给出：FR 总数 / 已覆盖 / 未覆盖清单（若不为空）。

## 3. 测试环境

| 项 | 值 |
|---|---|
| L1/L2 运行处 | 远端 `plantai-bff` conda 环境（pytest） |
| L3/L4 运行处 | 远端 `ui/`（Vitest，Node 18） |
| L5 运行处 | 远端（Playwright chromium，headed 不强制），**或** Mac 本地通过 SSH 隧道打到远端 |
| L5 视口 | iPhone 14 390×844 ｜ iPad 768×1024 ｜ Desktop 1440×900 |
| mock 服务 | `python sdk/mock/mock_server.py`，端口 8099，scenario 参数切场景 |
| 真实上游 | 7920 / 8000 / 7900 / Neo4j（按 DISCOVERY.md 选型） |

## 4. 缺陷分级

| 级别 | 定义 | 处置 |
|---|---|---|
| 阻断 Blocker | 主流程无法走通、数据损坏、崩溃 | 修复前不得进入下一轮 |
| 严重 Major | 功能错误、契约不符、数据错误 | 本轮必须修复 |
| 一般 Minor | 视觉瑕疵、次要交互问题 | 本轮修复，可批量 |
| 轻微 Trivial | 文案、间距等不影响理解 | 累积到 M6 收尾处理 |

缺陷编号：`BUG-R{n}-{序号}`，报告含复现步骤、预期/实际、截图或日志证据、对应 TC 编号。

## 5. 轮次纪律（用户明确要求，铁律）

1. 测试 agent **完整跑完一整轮全部用例**（L1+L2+L3+L4+L5 全量），**中途不修改任何代码**。
2. 产出 `docs/TEST_REPORT_R{n}.md`：首页统计（TC 总数 / pass / fail / 未跑 + FR 覆盖统计 + 行覆盖率）、缺陷清单（分级）、证据。
3. PM 汇总缺陷，**批量派发**给归属 agent 修复；开发 agent 只修自己文件归属内的缺陷。
4. 修复完成后进入下一轮：**再次完整跑完全部用例**（全量回归，不做增量）。
5. 循环直至：所有 TC pass + 主门禁 100% + 辅门禁达标。
6. 移交 PM 做 L6 验收。验收发现问题按第 4 级（轻微）回流或直接修复，由 PM 判定。

## 6. L5 端到端场景（必测主线）

对三档视口分别执行（各视口用例独立编号）：

1. **E2E-主流程**：新建会话 → 问答模式提问 → 流水线五相位推进 → 答案揭示（含表格）→ 来源 tab 有数据 → 图谱 tab 渲染 → 刷新后历史恢复
2. **E2E-检索模式**：检索模式提问 → 只出来源不出答案块
3. **E2E-错误与重试**：mock `scenario=error` 下提问 → 错误展示 + 重试按钮可用；`scenario=degraded` 下作曲器禁用
4. **E2E-会话管理**：新建/切换/重命名/删除/搜索过滤/分组
5. **E2E-中断**：流式中途切会话 → 原会话置 error 标注已中断
6. **E2E-主题**：深浅切换 + 刷新持久化
7. **E2E-图谱**：实体搜索 → 邻域展开 → 节点详情 → 缩放平移（移动端双指）
8. **E2E-抽取**：任务列表 → 详情展开 → 运行日志；mock 下上传 PDF
9. **E2E-响应式专项**：三档视口各自布局断言（见 PRD FR-RESP-001~004）+ 移动端专项（安全区、16px 输入、44px 触控、表格横滚、键盘适配）

## 7. 运行命令约定

```bash
# 后端（远端，plantai-bff 环境）
cd sdk && pytest tests -m unit -q          # L1
cd sdk && pytest tests -m api -q           # L2（respx mock）
bash tests/smoke_upstreams.sh                  # L2s 真实连通（手动触发）

# 前端（远端）
cd ui && npx vitest run                  # L3+L4
cd ui && npx playwright test             # L5（三档视口配置在 playwright.config.js）

# mock（开发与 L5 的 error/degraded 场景）
python sdk/mock/mock_server.py             # 127.0.0.1:8099
```

## 8. 报告模板（TEST_REPORT_R{n}.md 必须包含）

1. 轮次信息：日期、被测版本、运行环境
2. 首页统计表：TC 总数/pass/fail/skip、FR 覆盖 80/80 或缺口清单、行覆盖率（后端/前端）
3. 缺陷清单表：编号 | 级别 | TC | 归属 agent | 现象 | 预期 | 证据路径
4. 上轮缺陷修复确认表：BUG 编号 | 是否修复 | 本轮对应 TC 结果
5. 遗留问题与风险

---

## 9. 生信编排测试分层（FR-BIO 专属，在 §1 基础上扩展）

| 层 | 工具 | 归属 | 覆盖对象 | 运行方式 |
|---|---|---|---|---|
| L1 生信服务单元 | pytest | 开发 agent 自测 | runner 状态机全路径、manifest 解析、db 三表迁移、错误信封（mock docker 执行） | `pytest tests -m bioflow_unit` |
| L2 生信服务接口 | pytest + respx | T 主写 | 20 个端点正常/参数校验/错误/降级/边界；SSE 事件序；断线回放快照（mock LLM/vstore/docker） | `pytest tests -m bioflow_api` |
| L2s 生信冒烟 | 脚本 | T | 金标 docker 等价性（24 ID diff）、镜像构建、18 入口 --help（手动触发，不在每轮） | `bash bioflow_kernel/tests/smoke_golden.sh` |
| L3 前端单元 | Vitest | 开发自测 + T | bioflow store、意图分流用例表（前后端同表双跑） | `cd ui && npx vitest run` |
| L4 前端组件 | Vitest + @vue/test-utils | 开发自测 + T 补写 | 五卡片+两面板全状态 + UI 动作矩阵 | 同上 |
| L5 端到端 | Playwright | T | §11 九条主线 × 三档视口 | `npx playwright test` |
| L6 验收 | TL 亲自 | TL | 金标+七项引导端到端+三形态+全量回归 | 终验 |

## 10. 生信用例规模与覆盖门禁（用户要求，阶段 0 复查放行）

1. **规模门禁**：TEST_CASES.md 生信部分用例总数 **≥600 条**（P6 评估集 30-50 条另计）。分组建制：后端 L1/L2 ~230、前端 L3/L4 ~220、E2E L5 ~105、三形态+回归+P0/P6 冒烟 ~60。
2. **追溯门禁（主门禁）**：每个 FR-BIO 至少 1 条 TC、无孤儿 TC（双向完整）。
3. **UI 动作矩阵**：每个可交互元素（按钮/开关/输入框/拖放区/可选卡片）按动作逐一覆盖：点击/双击/悬停/键盘 Enter 与 Esc/拖入/悬停拖放/离开/聚焦/失焦/禁用态/加载中态——每条 TC 一个元素×一个动作。
4. **七项引导**：每条引导都有 UI 显示断言 + 操作断言；上下游动作（BFF 反代、报告登记、fig:// 渲染、docker 执行、manifest 判成败、SSE 事件序、断线回放、vstore 检索）都有接口级用例。
5. 阶段 0：T1 编制 → TL 逐条复查，不达标返工，达标才放行开发 agent。

## 11. 生信 E2E 必测主线（三档视口各独立编号，视口后缀 M/T/D）

1. **BIO-E2E-01 主流程**：「帮我跑水稻 SPL 家族鉴定」→ 2-3 条候选路径卡 → 点选 → 路径确认卡 → 确认 → 文件引导卡 → 拖拽上传金标数据（进度条）→ 参数表单（改一个参数）→ 点继续 → 进度卡逐阶段流转（含日志尾）→ 报告预览 → 导出 PDF → 存档提示 → 存档 → 状态回复
2. **BIO-E2E-02 自动连续**：开启自动连续开关 → 全程不等待表单自动推进 → 中途暂停 → 停在下一阶段前
3. **BIO-E2E-03 失败注入**：mock 使某阶段失败 → 进度卡标红 + 三选一 → 重跑成功 / 跳过生效 / 改参数重跑生效
4. **BIO-E2E-04 断线回放**：执行中切断 SSE（mock 或代理）→ 重连 → 进度卡恢复当前状态
5. **BIO-E2E-05 存档复用**：「用 XXX 存档任务的方法帮我跑 yyy」→ 名称匹配 → 表单预填 → 新任务执行
6. **BIO-E2E-06 探活显隐**：停 8098 → 刷新 → 生信 TAB/块隐藏；恢复 → 出现
7. **BIO-E2E-07 图表调整**：「xxx 图表颜色换成红色」→ 重跑绘图阶段 → 新图回填 → 预览刷新
8. **BIO-E2E-08 知识库问答**：「identify 阶段需要什么输入」→ 答案含引用块 → 跳转原文
9. **BIO-E2E-09 三档视口**：三档布局断言（卡片/面板/进度卡不溢出、触控目标 ≥44px 移动端）

## 12. 生信轮次报告追加项（在 §8 模板上扩展）

首页统计加：BIO FR 总数/已覆盖/未覆盖清单、生信用例总数（≥600 门禁核对）、UI 动作矩阵执行数；缺陷清单归属填 agent 代号（A1-A4）。