wandering1
343305b433
背景：ADC 采集的软件链路已全部打通（节拍、语义取数、折算、相量、 200 ms 快照、104/UI 消费），但"读数对不对"从未验证过——卡 0 的 已知电压注入一直挂账。挂账的直接原因之一是读数出口不够用： 固件只有 cal: 行（UA/UN/IA 三路，mV）与 first: 行（9 路码值，仅 开机一次），验 8 个通道 × 3 个注入点要复位二十余次。 改动一（App/task/adc_task.c，v3.3） - 心跳新增 adc: 行，每 10 s 输出 9 路原始码值，与 first: 行同序 同格式，台架"改电压 → 读一行"即可对表，全程免复位。 - 不并入 cal: 行：9 个码值会把该行推到 168 字符，撞 DBG_CON_LINE_MAX(192) 的静默截断边界（截断不报错，只会少打几路， 是最难发现的台架假数据来源）。 - 无新增跨任务状态、无新增外设访问；栈 +36 B（局部码值数组）， adcTask 静态最坏 1400 B / 余量 1160 B（底线 1024 B），stack_report PASS；静态 RAM 不变，Flash +188 B。 改动二（新增 docs/测试说明/ADC前端注入验证流程.md） - 卡 0 的执行侧：注入点清单、期望码值表、零点/线性/映射/极性/节奏 五步、现场记录表、安全红线、已知坑。 - 固化 2026-10-27 的网表结论：逐通道追 V0.1.tel 确认 ADCn 节点上 只有"串阻 2 脚 + 滤波电容 + 转换器引脚"，没有对地分流电阻；所谓 "1k 到地"是 TPAFE 负输入脚 AIN_nGND 经 1k 拴到 AGND 的差分滤波。 故本板不存在 2:1 分压，端子侧斜率 = 引脚侧斜率 = 6553.6 / 1241.2 码/V。数据可信.md §2.1 的 305.18 / 1611.3 µV/码 确认不成立。 - 不验交流：台架无信号源，且五路单极性削顶。 改动三（索引与指针） - docs/README.md 测试说明索引、测试文档模板规范.md 的 ADC 缩写行 （原"待立"）同步。 - 数据可信.md 卡 0 增加指向该流程的指针（本表只写判据，不写怎么 接表笔）。 门禁：Keil 构建 0 错误 0 警告；check_ids --strict 通过； check_doc_links --all --sections-strict 通过（193 文档 / 2871 处引用）； pre-commit 全过（含 cppcheck、编码规范、体积档、标定层与量纲回归 单测）；两处内存台账已按 --write / --update 刷新。
334 lines
13 KiB
Markdown
334 lines
13 KiB
Markdown
# 测试文档模板规范
|
||
|
||
本文档定义本项目测试文档的统一模板与编写规范，确保各模块（CH395F、GD5F2GQ5UE、SD2506 RTC、存储等）测试文档格式一致、可追溯，并能直接接入 `@test` 自动化闭环与门禁体系。
|
||
|
||
---
|
||
|
||
## 1. 定位与关联文档
|
||
|
||
| 文档 | 关系 |
|
||
|---|---|
|
||
| `测试开发标准流程.md` | 测试开发总流程（规划 → 实现 → 门禁 → 沉淀）；本文是其"测试规划（文档先行）"环节的可执行模板 |
|
||
| `自动化测试流程.md` | `@test` 闭环命令、参数与失败模式；本文"回归接入"章节引用它 |
|
||
| `docs/UI设计/UI_自动化测试流程.md` | UI 类改动的模拟器回归门禁（L2 层） |
|
||
| `docs/问题记录/<模块>_Trap_Records.md` | 陷阱记录；测试文档"已知陷阱"章节引用它 |
|
||
|
||
---
|
||
|
||
## 2. 文档结构
|
||
|
||
每份测试文档包含以下章节：
|
||
|
||
```
|
||
# [模块名] 测试规范
|
||
|
||
## 1. 概述
|
||
### 1.1 套件与入口（TEST_SUITE_* 宏 / 入口函数 / 阶段宏 / 运行方式）
|
||
### 1.2 设计原则覆盖表（原则短语 → 描述 → 验证用例）
|
||
### 1.3 测试环境（拓扑、工具链、硬件版本、PC 端依赖）
|
||
### 1.4 启用方法（编译开关 + 运行命令）
|
||
### 1.5 回归接入（@test 标记 / PC 端脚本 / 门禁层级）
|
||
|
||
## 2~N. 阶段 x：[阶段名]
|
||
- 阶段元信息表（含阶段宏）
|
||
- TC-XXX-xxx: 测试用例（完整表格）
|
||
|
||
## N+1. 脚本参考（如有 PC 端工具）
|
||
## N+2. 已知陷阱与故障模式（引用 Trap 文档）
|
||
## 附录 A：通过/失败汇总矩阵
|
||
## 附录 B：测试覆盖 vs 设计原则
|
||
## 附录 C：API 覆盖（驱动类模块建议）
|
||
## 变更记录
|
||
```
|
||
|
||
---
|
||
|
||
## 3. 概述章节要求
|
||
|
||
### 3.1 套件与入口（必填）
|
||
|
||
| 项 | 说明 |
|
||
|---|---|
|
||
| 套件宏 | `TEST_SUITE_XXX`（`test/board/test_config.h` 选择，套件互斥，见 `测试开发标准流程.md` §3.1） |
|
||
| 入口函数 | `xxx_test_run()`（由 `start_test_task()` 统一调度） |
|
||
| 阶段宏 | `ENABLE_XXX_PHASEN_TESTS`（各阶段使能开关，取消注释启用） |
|
||
| 运行方式 | 独立运行 / 需 PC 配合（逐阶段标注所需 PC 端工具） |
|
||
|
||
### 3.2 回归接入（必填）
|
||
|
||
| 项 | 说明 |
|
||
|---|---|
|
||
| `@test` 标记 | 套件结尾汇总行（如 `=== Storage Tests:`）或阶段标题行；**必须与串口实际输出逐字一致**（`verify_log.py` 子串匹配） |
|
||
| 禁止模式 | 默认 `FAIL;ERROR;HardFault;assert`，可按模块增补 |
|
||
| PC 端脚本 | `test/*.py` 工具清单与调用方式 |
|
||
| 门禁层级 | L1（板端套件）/ L2（串口标记 + 模拟器回归）/ L3（人工目检），见 `测试开发标准流程.md` §1 |
|
||
|
||
> 标记字符串一律**从代码 `DBG_*` 实际输出复制**（含大小写 / 冒号 / 空格）；代码改了输出文案必须同步改文档（§7.6）。
|
||
|
||
---
|
||
|
||
## 4. 阶段元信息表
|
||
|
||
每个阶段以表格开头，描述阶段的整体属性：
|
||
|
||
| 字段名 | 填写说明 |
|
||
|--------|----------|
|
||
| **阶段** | 直接写中文「阶段 N」（如 阶段 1、阶段 6），不再发阶段号 |
|
||
| **类型** | 独立运行 / 需 PC 配合 / 需物理操作 / 在 xxTask 中运行 |
|
||
| **耗时** | 预估执行时间 |
|
||
| **入口** | 代码入口函数或宏定义 |
|
||
| **出口** | 阶段结束标志（如串口输出内容，即 `@test` 可校验的标记） |
|
||
| **阶段宏** | 对应使能宏（如 `ENABLE_PHASE1_TESTS`） |
|
||
|
||
---
|
||
|
||
## 5. 测试用例表格模板
|
||
|
||
每个测试用例使用统一表格格式：
|
||
|
||
```
|
||
### TC-模块缩写-序号: 用例标题
|
||
|
||
| 字段 | 值 |
|
||
|------|-----|
|
||
| **ID** | TC-XXX-NNN（全局唯一，不复用） |
|
||
| **优先级** | P0 / P1 |
|
||
| **类型** | 见下文 5.1 |
|
||
| **标题** | 一句话描述测试什么 |
|
||
| **前置条件** | 测试执行前必须满足的条件（编号列表） |
|
||
| **测试步骤** | 操作步骤（编号列表，动作具体到 API 或操作） |
|
||
| **预期结果** | 系统应表现的行为 |
|
||
| **通过标准** | 可量化的判定条件 |
|
||
| **机器可判** | 串口标记 / TEST_CHECK / 像素参考 / 池水位 / L3 人工（见 §7.4） |
|
||
| **覆盖原则** | 设计原则短语（可选，关联设计原则） |
|
||
```
|
||
|
||
### 5.1 类型枚举
|
||
|
||
| 类型 | 说明 | 适用场景 |
|
||
|------|------|----------|
|
||
| 功能测试 | 验证某项功能是否符合预期 | 正常的收发、初始化、配置等 |
|
||
| 负向测试 | 验证系统对非法/异常输入的处理 | 超时、断开、无效参数等 |
|
||
| 边界测试 | 验证系统在边界条件的表现 | 最大包长、最小超时、满队列等 |
|
||
| 压力测试 | 验证系统在高负载下的稳定性 | 多客户端、高频请求、长时运行等 |
|
||
| 恢复测试 | 验证系统从故障中恢复的能力 | 断线重连、PHY 重连、复位恢复、掉电恢复等 |
|
||
| 合规测试 | 验证实现是否符合特定约束 | 中断处理位置、等待顺序、字节序等 |
|
||
| 稳定性测试 | 验证系统长时间运行的可靠性 | 长时间压力、反复循环等 |
|
||
| 集成测试 | 验证跨模块组合场景下的行为 | FTL+FatFS 联合、FTP+存储、网络+存储等 |
|
||
|
||
### 5.2 优先级定义
|
||
|
||
| 优先级 | 定义 |
|
||
|--------|------|
|
||
| **P0** | 核心功能，必须通过。阻塞后续测试或影响系统基本可用性 |
|
||
| **P1** | 重要功能，建议通过。失败表明潜在缺陷但不阻塞基本功能 |
|
||
|
||
---
|
||
|
||
## 6. 命名规则
|
||
|
||
### 6.1 阶段
|
||
|
||
- 正文、元信息表、汇总表一律写中文**「阶段 N」**（如 阶段 1、阶段 6），**不再发阶段号**；
|
||
- 用例号的百位已经带阶段信息（§6.3），无需另立阶段标识；
|
||
- 历史文档里出现过的旧阶段号冻结不回改，新文档按本条。
|
||
|
||
### 6.2 模块缩写（以项目现用为准）
|
||
|
||
| 缩写 | 模块 | 现用文档 |
|
||
|---|---|---|
|
||
| `NET` | CH395F 网络（驱动 + 协议栈 + FTP 自动化用例） | `CH395F_Test_Guide.md`（`FTP_Test_Guide.md` 的自动化部分复用其 TC-NET-8xx 编号） |
|
||
| `GD5F` | GD5F2GQ5UE NAND Flash 驱动 | `GD5F2GQ5UE_Test_Guide.md` |
|
||
| `STO` | 存储（FTL + FatFS 集成） | `GD5F2GQ5UE_Test_Guide.md`（TC-STO 章节） |
|
||
| `RTC` | SD2506 RTC | `SD2506_Test_Guide.md` |
|
||
| `ADC` | TPAFE5160 + STM32 ADC1 采集与折算（台架注入验证） | `ADC前端注入验证流程.md` |
|
||
| `RS485` | RS-485 通信 | （待立） |
|
||
|
||
> 新模块立测试文档时先定缩写（2~4 个大写字母），并同步更新本表与 `测试开发标准流程.md` §2.2 的缩写表。
|
||
> 注：旧版缩写 `PHY` / `NAND` 已被实际用法 `NET` / `GD5F` 取代（历史文档不回改，新文档按本表）。
|
||
|
||
### 6.3 测试用例 ID（**已停发新号**，以下形态只用于读现存号）
|
||
|
||
```
|
||
TC-{MOD}-{NNN}
|
||
```
|
||
|
||
> ⚠ **本族的号已于 2026-10-27 停发**（用户裁定「批次三，不坐」→ `docs/编号规范.md` §4.1）：**新用例不再配
|
||
> TC 号**，标识 = 语义化测试函数名 + 本文档用例表的行名（§6.4 同口径）。下面的形态约定是**读现存号**用的，
|
||
> 不是起新号的模板。现存号保留、不清、不复用——测试追溯门禁按字面量读它。
|
||
|
||
- **分阶段套件（历史形态，只读）**：序号**百位放阶段号**，`TC-NET-101` = CH395F Phase 1 第 1 项、`TC-NET-601` = Phase 6 第 1 项、`TC-NET-1101` = Phase 11 第 1 项；
|
||
- **无阶段划分套件（历史形态，只读）**：全局顺序编号（如 `TC-STORAGE-03`、`TC-RTC-001`）；
|
||
- 编号不复用：废弃用例保留编号并注明"已废弃"；停发之后**没有"取哪个号"这一步**。
|
||
|
||
### 6.4 设计原则
|
||
|
||
- 设计原则**写语义短语**，**不再发号**：如「单连接 socket」「中断集中处理」「线程安全」「DMA 边界安全」；
|
||
- 覆盖原则处、汇总表与代码注释**引用同一条短语**（同一事实只在一处详述）。
|
||
|
||
---
|
||
|
||
## 7. 编写规范
|
||
|
||
### 7.1 表格格式
|
||
|
||
- 使用 GFM (GitHub Flavored Markdown) 表格
|
||
- 首列为字段名，加粗（`**字段**`）
|
||
- 第二列为值，左对齐
|
||
- 多行内容使用 `<br>` 换行（保持表格可读性）
|
||
|
||
### 7.2 测试步骤与前置条件
|
||
|
||
- 使用有序列表（`1. 2. 3.`）
|
||
- 每个步骤是一个完整的可执行动作
|
||
- 包含具体 API 名或操作名（如 `net_recv()`、`ch395f_open_socket()`）
|
||
- 前置条件写明硬件状态、PC 端命令（含完整命令行）、代码配置（宏 / 编译开关）
|
||
|
||
### 7.3 语言
|
||
|
||
- 中文书写（技术标识保留英文）
|
||
- 保持客观、精确、可验证
|
||
- 避免模糊表述（如 "应该能正常工作" → "回显内容与发送完全一致"）
|
||
|
||
### 7.4 通过标准（必须可机器判定，或显式人工层）
|
||
|
||
通过标准必须落到以下通道之一，并在用例表"机器可判"字段标明：
|
||
|
||
| 通道 | 判定方 | 适用 |
|
||
|---|---|---|
|
||
| 串口日志标记 | `@test` / `verify_log.py` 子串匹配 | 启动序列、阶段标题行、关键事件 |
|
||
| 返回值 / 寄存器 / 数据 | 板端 `XXX_TEST_CHECK` 断言 | 驱动命令、协议交互、数据完整性 |
|
||
| 像素参考 | LVGL 模拟器回归（`simulator/tests/`） | UI 渲染、字体、样式 |
|
||
| 内存池水位 | 模拟器池基线 / 往返常量 | LVGL 对象泄漏、结构漂移 |
|
||
| L3 人工 | 人工目检 / 交互 | 屏幕观感等无法机器判定的项（必须写目检步骤） |
|
||
|
||
- 好的示例：`70/70 成功率（100%）`、`串口显示 "PHY_CHANGE: 0x01"`、`10/10 回显匹配`、`=== Storage Tests: 11/11 PASSED (failed=0) ===`
|
||
- 差的示例：`功能正常`、`系统稳定`
|
||
|
||
### 7.5 引用
|
||
|
||
- 引用函数、宏、文件名使用反引号（`` `net_poll()` ``）
|
||
- 引用其他文档使用仓库相对路径：`docs/问题记录/CH395F_Trap_Records.md`、`docs/测试说明/自动化测试流程.md`
|
||
- 代码位置引用：`文件路径:行号` 或函数名
|
||
|
||
### 7.6 文档维护（与代码同步）
|
||
|
||
- 代码变更影响用例 / 判定标准 / 日志文案 → **当天**更新本文档，并在变更记录登记（与 `测试开发标准流程.md` §7.3 同标准）；
|
||
- 测试发现陷阱 → 写入 `docs/问题记录/<模块>_Trap_Records.md`（现象 / 根因 / 修复 / 规避），并在本文档"已知陷阱与故障模式"章节留链接；
|
||
- 判定标准经实测修正 → 更新用例表并在变更记录注明修正原因。
|
||
|
||
---
|
||
|
||
## 8. 快速参考
|
||
|
||
### 8.1 新模块测试文档模板
|
||
|
||
```markdown
|
||
# [模块名] 测试规范
|
||
|
||
## 1. 概述
|
||
|
||
### 1.1 套件与入口
|
||
|
||
| 项 | 值 |
|
||
|---|---|
|
||
| 套件宏 | `TEST_SUITE_XXX` |
|
||
| 入口函数 | `xxx_test_run()` |
|
||
| 阶段宏 | `ENABLE_XXX_PHASE1_TESTS` … |
|
||
| 运行方式 | 独立运行 / 需 PC 配合（列明哪些阶段、用什么 PC 工具） |
|
||
|
||
### 1.2 设计原则覆盖
|
||
|
||
| 原则 | 描述 | 验证用例 |
|
||
|------|------|----------|
|
||
| 单连接 socket | ... | TC-NET-601 |
|
||
|
||
### 1.3 测试环境
|
||
|
||
（硬件拓扑 / 工具链 / PC 端依赖）
|
||
|
||
### 1.4 启用方法
|
||
|
||
（test_config.h 开关 + 构建 / 运行命令）
|
||
|
||
### 1.5 回归接入
|
||
|
||
| 项 | 值 |
|
||
|---|---|
|
||
| `@test` 标记 | `=== XXX Tests:`（套件结尾汇总行的确切字符串） |
|
||
| PC 端脚本 | `test/xxx_test.py` |
|
||
| 门禁层级 | L1 + L2 |
|
||
|
||
## 2. 阶段 1：[阶段名]
|
||
|
||
| 项 | 值 |
|
||
|---|---|
|
||
| 阶段 | 阶段 1 |
|
||
| 类型 | ... |
|
||
| 耗时 | ... |
|
||
| 入口 | ... |
|
||
| 出口 | ... |
|
||
| 阶段宏 | `ENABLE_XXX_PHASE1_TESTS` |
|
||
|
||
### TC-<模块码>-<序号>: 用例标题
|
||
|
||
| 字段 | 值 |
|
||
|------|-----|
|
||
| **ID** | `TC-<模块码>-<序号>`（全局唯一，不复用） |
|
||
| **优先级** | P0 |
|
||
| **类型** | 功能测试 |
|
||
| **标题** | ... |
|
||
| **前置条件** | 1. ...<br>2. ... |
|
||
| **测试步骤** | 1. ... |
|
||
| **预期结果** | ... |
|
||
| **通过标准** | ...（可量化） |
|
||
| **机器可判** | 串口标记 / TEST_CHECK / 像素参考 / 池水位 / L3 人工 |
|
||
|
||
## 附录 A：通过/失败汇总矩阵
|
||
|
||
| 阶段 | TC ID | 优先级 | 类型 | 状态 |
|
||
|------|-------|--------|------|------|
|
||
|
||
## 附录 B：测试覆盖 vs 设计原则
|
||
|
||
| 原则 | 覆盖用例 |
|
||
|------|----------|
|
||
|
||
## 附录 C：API 覆盖（驱动类模块建议）
|
||
|
||
| API | 已覆盖 | 用例 |
|
||
|-----|--------|------|
|
||
|
||
## 变更记录
|
||
|
||
| 日期 | 变更 |
|
||
|---|---|
|
||
```
|
||
|
||
### 8.2 附录模板
|
||
|
||
```markdown
|
||
## 附录 A：通过/失败汇总矩阵
|
||
|
||
| 阶段 | TC ID | 优先级 | 类型 | 状态 |
|
||
|------|-------|--------|------|------|
|
||
|
||
## 附录 B：测试覆盖 vs 设计原则
|
||
|
||
| 原则 | 覆盖用例 |
|
||
|------|----------|
|
||
|
||
## 附录 C：API 覆盖
|
||
|
||
| API | 已覆盖 | 用例 |
|
||
|-----|--------|------|
|
||
```
|
||
|
||
---
|
||
|
||
## 变更记录
|
||
|
||
| 日期 | 变更 |
|
||
|---|---|
|
||
| 2026-09-13 | 补充完善：模块缩写表更新为项目实际用法（`NET`/`GD5F`/`STO`/`RTC`/`FTP`，取代旧版 `PHY`/`NAND`，历史文档不回改）；概述新增"套件与入口"与"回归接入"章节（衔接 `test_config.h` 套件互斥与 `@test` 闭环，标记须与串口实际输出逐字一致）；用例表新增"机器可判"字段（四通道 + L3 人工层）；类型枚举新增"集成测试"；TC 序号约定"分阶段套件百位放阶段号"（TC-NET-601 = Phase 6）；新增附录 C API 覆盖；陷阱引用路径修正为 `docs/问题记录/`；新增 §7.6 文档维护规范与文末变更记录章节 |
|