STM32F4-Base/docs/测试说明/测试文档模板规范.md

测试文档模板规范

本文档定义本项目测试文档的统一模板与编写规范，确保各模块（CH395F、GD5F2GQ5UE、SD2506 RTC、存储等）测试文档格式一致、可追溯，并能直接接入 @test 自动化闭环与门禁体系。

---

1. 定位与关联文档

文档	关系
测试开发标准流程.md	测试开发总流程（规划 → 实现 → 门禁 → 沉淀）；本文是其"测试规划（文档先行）"环节的可执行模板
自动化测试流程.md	@test 闭环命令、参数与失败模式；本文"回归接入"章节引用它
docs/UI设计/UI_自动化测试流程.md	UI 类改动的模拟器回归门禁
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 工具清单与调用方式
门禁层级	板端测试套件 / 主机侧回归（串口标记 + 模拟器回归）/ 人工目检，见 测试开发标准流程.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 / 像素参考 / 池水位 / 人工目检（见 §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 对象泄漏、结构漂移
人工目检	人工目检 / 交互	屏幕观感等无法机器判定的项（必须写目检步骤）

• 好的示例：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（现象 / 根因 / 修复 / 规避），并在本文档"已知陷阱与故障模式"章节留链接；
• 判定标准经实测修正 → 更新用例表，并把修正后的判据与实测依据写进正文（为什么这么判、拿什么证的），改动过程本身查 git log。

测试文档不再设「变更记录」节（2026-10-28 用户裁定，口径见 docs/文档规范.md §5.1）：文档只写现状，「哪天改了什么」由 git log 负责；例外只有被别处当台账 / 唯一证据出处的文档（那份清单也在 docs/文档规范.md §5.1）。

---

8. 快速参考

8.1 新模块测试文档模板

# [模块名] 测试规范

## 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` |
| 门禁层级 | 板端测试套件 + 主机侧回归 |

## 2. 阶段 1：[阶段名]

| 项 | 值 |
|---|---|
| 阶段 | 阶段 1 |
| 类型 | ... |
| 耗时 | ... |
| 入口 | ... |
| 出口 | ... |
| 阶段宏 | `ENABLE_XXX_PHASE1_TESTS` |

### TC-<模块码>-<序号>: 用例标题

| 字段 | 值 |
|------|-----|
| **ID** | `TC-<模块码>-<序号>`（全局唯一，不复用） |
| **优先级** | P0 |
| **类型** | 功能测试 |
| **标题** | ... |
| **前置条件** | 1. ...<br>2. ... |
| **测试步骤** | 1. ... |
| **预期结果** | ... |
| **通过标准** | ...（可量化） |
| **机器可判** | 串口标记 / TEST_CHECK / 像素参考 / 池水位 / 人工目检 |

## 附录 A：通过/失败汇总矩阵

| 阶段 | TC ID | 优先级 | 类型 | 状态 |
|------|-------|--------|------|------|

## 附录 B：测试覆盖 vs 设计原则

| 原则 | 覆盖用例 |
|------|----------|

## 附录 C：API 覆盖（驱动类模块建议）

| API | 已覆盖 | 用例 |
|-----|--------|------|

8.2 附录模板

## 附录 A：通过/失败汇总矩阵

| 阶段 | TC ID | 优先级 | 类型 | 状态 |
|------|-------|--------|------|------|

## 附录 B：测试覆盖 vs 设计原则

| 原则 | 覆盖用例 |
|------|----------|

## 附录 C：API 覆盖

| API | 已覆盖 | 用例 |
|-----|--------|------|