wandering1/STM32F4-Base
1
0
Fork 0
Code Issues 29 Pull Requests 1 Actions Packages Projects 2 Releases Wiki Activity

测试：落地测试架构改进 T-1~T-5（套件开关门禁/汇总行校验/通用 harness/公共断言宏/多套件编排）

Browse Source 
背景：L0.5 主机侧单测落地后复审测试架构，给出 6 条改进意见（P0~P3），
登记进 docs/待处理内容.md「测试与验证基础设施」后逐条实施。

- T-1(P0) 测试套件开关门禁：新增 scripts/check_test_suite.py + pre-commit 钩子
  test-suite-switch，默认要求产品构建（全部 TEST_SUITE_* 注释），跑套件回归用
  --allow-test-build / ALLOW_TEST_BUILD=1 显式放行。顺带把 test_config.h 中长期
  开启的 TEST_SUITE_CH395F 改回注释（仓库此前躺着的是测试固件）。
- T-2(P1) verify_log.py 增加 --require-suite-summary：要求
  "=== <名称>: N/M PASSED (failed=0) ===" 且 N>0，堵住"套件没跑到汇总行/
  断言数为 0 仍判 PASS"的盲区；run_boot_test.py 同名参数透传。不传参向后兼容。
- T-3(P1) 抽取通用 harness test/host/common/unit_test_harness.py（工具链探测/
  INCLUDE-LIB 拼接/wd4819/GBK 解码/退出码契约）；watchdog 运行器 170→55 行，只声明 TestBuild。
- T-4(P2) 新增 test/board/test_common.h 集中断言内核（TEST_CHECK_IMPL/TEST_REPORT_IMPL），
  4 套件各用一行宏绑定自身统计变量（保持 g_xxx_stats 独立、防跨套件串数）。
  刻意不 include dbg_log.h——否则冻结 DBG_TAG 默认值触发 #47-D 重定义警告。
- T-5(P2) 新增 test/run_all_suites.py 多套件回归编排，try/finally 无条件还原套件开关。

验证：@build 产品构建 0 错 0 警；4 套件逐一构建均 0/0；看门狗单测 39/39 PASS；
pre-commit 14 钩子全通过；编排脚本 dry-run/开关切换/异常还原均实测通过。
This commit is contained in:
Wanderingss
2026-10-01 07:28:57 +08:00
parent 6b90fa0581
commit 2055de0303
24 changed files with 1135 additions and 261 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/测试说明/测试开发标准流程.md
+85 -12
View File
@@ -91,6 +91,7 @@ flowchart TD
```
- **套件互斥**：一次构建最多启用一个 `TEST_SUITE_*`，否则 `#error`（编译期门禁）；全部注释 = 正常产品构建。
- **测试固件不得静默提交**：`TEST_SUITE_*` 开关受 pre-commit 钩子 `test-suite-switch` 门禁（默认要求全部注释）。跑完套件回归**务必改回产品构建**再提交；确需提交测试构建时用 `ALLOW_TEST_BUILD=1` 显式放行（会打 `[WARN]` 横幅）。见 §7.1。
- **main.c / freertos.c 不含任何测试逻辑** —— 测试代码只能出现在 `test/`。
| 套件 | 宏 | 文件 | 阶段组织 | 备注 |
@@ -109,20 +110,41 @@ flowchart TD
断言宏（语义统一，统计变量按套件独立，防跨套件串数）：
```c
typedef struct { uint16_t total, passed, failed; } xxx_test_stats_t;
**内核集中在 `test_common.h`**（2026-10-01 抽取，T-4）——4 套件的宏此前逐字重复，改一处要改四处：
#define XXX_TEST_CHECK(cond, fmt, ...) do { \
g_xxx_stats.total++; \
if (cond) { g_xxx_stats.passed++; DBG_INFO(" [PASS] " fmt, ##__VA_ARGS__); } \
else { g_xxx_stats.failed++; DBG_ERROR(" [FAIL] " fmt, ##__VA_ARGS__); } \
```c
/* test/board/test_common.h */
typedef struct { uint16_t total, passed, failed; } test_stats_t;
#define TEST_CHECK_IMPL(stats, cond, fmt, ...) do { \
(stats).total++; \
if (cond) { (stats).passed++; DBG_INFO("[PASS] " fmt, ##__VA_ARGS__); } \
else { (stats).failed++; DBG_ERROR("[FAIL] " fmt, ##__VA_ARGS__); } \
} while (0)
#define XXX_TEST_REPORT(name) do { \
DBG_INFO("=== %s: %d/%d PASSED (failed=%d) ===", name, ...); \
#define TEST_REPORT_IMPL(stats, name) do { \
DBG_INFO("=== %s: %u/%u PASSED (failed=%u) ===", name, ...); \
} while (0)
```
各套件**用一行宏把它绑定到自己的统计变量**（保持 `g_xxx_stats` 独立）：
```c
/* 套件头文件内（如 gd5f_test.h） */
#include "test_common.h"
typedef test_stats_t gd5f_test_stats_t;
extern gd5f_test_stats_t g_gd5f_test_stats;
#define GD5F_TEST_CHECK(cond, fmt, ...) \
TEST_CHECK_IMPL(g_gd5f_test_stats, cond, fmt, ##__VA_ARGS__)
#define GD5F_TEST_REPORT(name) TEST_REPORT_IMPL(g_gd5f_test_stats, name)
```
> ⚠️ **`test_common.h` 刻意不 include `dbg_log.h`**：`dbg_log.h` 在未定义 `DBG_TAG` 时给出
> 默认值 `""`，而本头文件被套件头在**很靠前**的位置包含——若在此处拉入，会把空 `DBG_TAG`
> 冻结，导致 `.c` 随后 `#define DBG_TAG "[TEST_TASK]"` 触发 ARMCC `#47-D: incompatible
> redefinition`（实测 8 条警告）。宏只在**使用点**展开（使用点在已按约定先定义
> `DBG_TAG` 的 `.c` 内），故无需在此引入。
每 Phase 用标准注释头（与文档用例一一对应）：
```c
@@ -174,7 +196,6 @@ static void phaseN_run(void) {
- 硬件层模式下挂起的 netTask 仍占 4KB 栈，为基础线程策略的接受成本（彻底方案可回收，暂无计划）。
### 3.5 新测试文件 / 新套件 checklist
1. `test/` 下新建 `xxx_test.h` / `xxx_test_task.c`（按 §3.2 模式）；
2. `test/board/test_config.h`：补 `TEST_SUITE_XXX` 注释开关 + 互斥 `#error` 加项 + 分发分支（include + `TEST_SUITE_NAME`）；
3. `test/board/test_config.c`：`start_test_task()` 加分发分支；
@@ -183,6 +204,24 @@ static void phaseN_run(void) {
6. 立 `docs/测试说明/<模块>_Test_Guide.md`（§2 模板）；
7. `@test` 以套件标题行为 `-Required` 标记跑通回归。
### 3.6 多套件回归编排（`test/run_all_suites.py`，2026-10-01 加 T-5）
套件互斥（编译期 `#error`）→ 跑 4 个套件的回归本来要手工循环 4 轮
（改宏 → 构建 → 烧录 → 采集 → 判读）。本脚本编排成一条命令：
```powershell
& '.venv\Scripts\python.exe' test/run_all_suites.py # 全部套件
& '.venv\Scripts\python.exe' test/run_all_suites.py --suites STORAGE,GD5F
& '.venv\Scripts\python.exe' test/run_all_suites.py --dry-run # 只看计划
```
**核心保障：`try/finally` 无条件还原 `test_config.h`**（含异常 / `KeyboardInterrupt`
路径）——跑完忘还原 = **测试固件进库**。这与提交期门禁 `test-suite-switch`（§7.1）
是**两条独立防线**：前者是流程自动化、后者是门禁兜底。
> ⚠️ **不挂 pre-commit**：每轮真机烧录 + 采集（8s 静默 + boot），4 套件约数分钟起，
> 且破坏性套件会改设备持久状态。仅回归窗口手工使用。
---
## 4. 主机侧测试工具
@@ -193,8 +232,9 @@ static void phaseN_run(void) {
|---|---|---|
| Python 串口助手（serial_tool） | `tools/serial_tool/serial_tool.py`（.venv + pyserial） | 常驻 daemon + 薄 CLI：列端口 / 开关 / 收发 / 全量日志 / wait-idle |
| `test/host/run_boot_test.py` | `test/host/` | 一键闭环：采集 → 烧录 → 提取日志 → 校验 |
| `test/host/verify_log.py` | `test/host/` | 日志标记校验（Required / Forbidden → PASS / FAIL） |
| **`test/host/watchdog/run_unit_test.py`** | `test/host/watchdog/` | **L0.5 主机侧单测**：MSVC 离线编译真实 `task_watchdog.c` + 可观测桩，穷举判定状态机（零硬件、秒级）。**需本机装有 VS（`cl.exe`）**，见 §4.2 环境要求 |
| `test/host/verify_log.py` | `test/host/` | 日志标记校验（Required / Forbidden → PASS / FAIL）+ 可选套件汇总行校验（T-2） |
| **`test/host/common/unit_test_harness.py`** | `test/host/common/` | **L0.5 通用单测 harness**：工具链探测 / `INCLUDE`-`LIB` 拼接 / 编译运行 / 退出码契约。各模块运行器只做声明式配置（T-3） |
| **`test/host/watchdog/run_unit_test.py`** | `test/host/watchdog/` | **L0.5 主机侧单测**：声明 `TestBuild` 后调 harness，穷举看门狗判定状态机（零硬件、秒级）。**需本机装有 VS（`cl.exe`）**，见 §4.2 环境要求 |
| `.opencode/serial_config.json` | 仓库 | **串口端口单一配置源**（当前 COM6 / 115200）；换端口只改这个文件 |
| `test/host/ftp_*.py`（4 个）/ `ch395f_socket_test.py` / `time_sync_server.py` | `test/host/` | PC 端交互测试工具（FTP 客户端 / socket 回显 / 对时推送） |
| `simulator/tests/*.py`（4 个） | `simulator/tests/` | LVGL 模拟器回归脚本（见 §5） |
@@ -209,7 +249,9 @@ static void phaseN_run(void) {
1. 模块的**硬件访问**收敛到薄平台层（`__weak` 钩子或后端函数）——参照
`App/cfg/cfg_file_store.h` 的"共享核心 + 平台后端"；
2. 测试单元 `#include` **生产源文件**（保证测的是真代码，非副本），用桩替换平台层；
3. 用 MSVC 离线编译运行（`run_unit_test.py` 自动探测工具链）；
3. 写模块侧运行器：**只声明** `TestBuild`（源码 / 桩目录 / 汇总行标记）+ 调
`test/host/common/unit_test_harness.py`（工具链探测与编译运行细节在 harness 内，
见 [`../../test/host/common/README.md`](../../test/host/common/README.md)）；
4. 挂 pre-commit 钩子，被改动时自动跑（**只 commit 不烧录**，秒级）。
**环境要求**（详见 [`../环境与部署/项目部署环境要求.md`](../环境与部署/项目部署环境要求.md) §2.3 / §2.7）：
@@ -302,6 +344,31 @@ flowchart TD
| 开机全量（存储 / RTC / RS485 / ADC） | 默认 + `RS485 init: OK;NAND init:;ADC init:;SD2506 ID:` |
| 测试套件构建 | 套件结尾汇总行（`=== Storage Tests:` / `=== GD5F2GQ5UE Tests:` 等，确切字符串见各模块 Test_Guide） |
### 6.2.1 套件汇总行校验（2026-10-01 加，T-2）
> ⚠️ **纯 Required 子串匹配有盲区**：套件启动横幅命中即判 PASS——**套件是否跑到汇总行、
> 断言数是否为 0 完全不可见**。套件中途挂死/复位、或 Phase 宏全关（没编入任何断言）时，
> 会被**误判为通过**。测试套件构建的回归**必须**加 `--require-suite-summary`。
```powershell
# 测试套件构建回归（要求套件跑到汇总行，且断言数 > 0）
& '.venv\Scripts\python.exe' test/host/run_boot_test.py `
--required "=== Storage Tests:" --forbidden "ERROR;HardFault;[ERR]" `
--require-suite-summary "Storage Tests"
```
校验语义（`verify_log.py`）：
| 情形 | 判定 |
|---|---|
| 汇总行存在、`N>0`、`failed=0`、`N==M` | PASS（打印 `[OK] suite summary ok`） |
| 汇总行**缺失**（套件没跑到/挂死） | FAIL `[MISS]` |
| `total == 0`（没编入任何断言） | FAIL `[FAIL] total is 0` |
| `failed != 0` | FAIL `[FAIL] reports failures` |
| `passed != total` | FAIL `[FAIL] inconsistent` |
> 未传 `--require-suite-summary` 时行为与旧版**逐字一致**（向后兼容，产品构建回归不受影响）。
### 6.3 三条铁律
1. **采集必须先于烧录武装** —— 开串口 + clear 在烧录前完成（daemon 常驻全量日志兜底，不会漏字节；`run_boot_test.py` 已保证顺序）；
@@ -323,6 +390,7 @@ flowchart TD
| cppcheck | 静态分析（warning / performance / portability / style，含 suppress 清单） |
| no-mojibake | 禁止 U+FFFD 乱码字节（保护中文注释） |
| coding-standard | 代码规范 V1.0 机械检查（S1~S19） |
| **test-suite-switch** | **测试套件开关=产品构建**（`test/board/test_config.h` 的 `TEST_SUITE_*` 须全注释；跑套件回归确需提交测试构建时用 `--allow-test-build` 显式放行） |
范围：仅项目自有代码受检；第三方与生成物（`Lib/`、`Middlewares/`、CMSIS/HAL、`lftpd`、`dhara`、`MDK-ARM/`、`test/`、CubeMX 生成的 `Src/` `Inc/` 等）被排除（详见 `pre-commit使用说明.md`）。
@@ -369,6 +437,7 @@ flowchart LR
| 文件 | 作用 |
|---|---|
| `test_config.h` / `test_config.c` | 套件选择（互斥 `#error`）+ 统一调度入口 `start_test_task()` |
| `test_common.h` | **板端测试公共断言内核**（`test_stats_t` + `TEST_CHECK_IMPL`/`TEST_REPORT_IMPL`） |
| `ch395f_test.h` / `ch395f_test_task.c` | CH395F 套件：阶段开关、断言宏、Phase 1~5 实现 |
| `net_test_task.h` / `net_test_task.c` | CH395F 套件 NET 层（6~11）：TCP 监听循环 / Client 主动连接测试 |
| `storage_test.h` / `storage_test_task.c` | STORAGE 套件：FTL + FatFS 集成（TC-STO-01~04）+ 恢复测试 |
@@ -395,6 +464,10 @@ flowchart LR
| 日期 | 变更 |
|---|---|
| 2026-10-01 | §3.6 新增 **`test/run_all_suites.py`** 多套件回归编排（`try/finally` 无条件还原套件开关；T-5）；`test/README.md` 同步 |
| 2026-10-01 | §3.2 断言宏改为**集中内核**：新增 `test/board/test_common.h`（`test_stats_t` + `TEST_CHECK_IMPL`/`TEST_REPORT_IMPL`），4 套件各自用一行宏绑定自身统计变量（T-4；零行为变化、零 RAM 增量、`@build` 0/0，四套件均 0/0 验证）。附 `test_common.h` 不 include `dbg_log.h` 的原因（`DBG_TAG` 冻结 → `#47-D`） |
| 2026-10-01 | 新增 §7.1 钩子 **`test-suite-switch`**（测试套件开关=产品构建，防测试固件静默提交）+ §3.1 铁律（跑完套件回归务必改回产品构建）；依据 `docs/待处理内容.md` T-1（测试架构评审 P0）。同步更新 `../代码规范/pre-commit使用说明.md` §2.13 |
| 2026-10-01 | §4.1/§4.2 更新：主机侧单测运行器统一走通用 harness `test/host/common/unit_test_harness.py`（T-3），模块运行器只做声明式配置；§6.2.1 新增套件汇总行校验（T-2） |
| 2026-10-01 | §4.2 补 **L0.5 环境要求表**（MSVC `cl.exe` = 装了 VS 即有、与模拟器共用；Windows SDK；纯标准库 Python；缺失时退出码 2 且 pre-commit 钩子拦截）+ "不调 `vcvars64.bat`（`reg.exe` 受限）"原因说明；§4.1 工具清单标注该运行器需 VS。同步更新 `../环境与部署/项目部署环境要求.md`（§2.3 / §2.7 / 第 3、10 步 / 清单 / 下载表 / 速查表） |
| 2026-09-15 | §3.4 更新：P1-6 修复落地（基础线程策略）——USER CODE 区冗余 netTask 创建删除 + `net_task_func` 入口 `ENABLE_HW_LAYER_TESTS` 自挂起守卫；"代码事实/设计约束"按修复后现状重写（硬件层模式中断断言恢复安全、NET 层/产品仍按"netTask 恒在轮询"设计）；彻底方案（`.ioc` 移除）经评估未采用。同日构建验证发现两处**存量**测试固件缺陷（与 P1-6 无关，A/B 对照确证）：① `net_test_task.c` `s_rx_buf` 使用先于声明 → NET 层配置自 2026-08（88160a5）起不可编译；② 128KB 静态 RAM 预算溢出（产品镜像 123.6KB，HW 全阶段固件超 8.7KB、NET 固件超 ~28KB）——已立 P1-9/P1-10 跟踪 |
| 2026-09-13 | 重写：对齐现测试架构——统一 `test_config.h` 套件（旧版仅描述 CH395F 单套件与 `ch395fTestTask` 旧入口）；新增 @test 自动化闭环、pre-commit 门禁、UI 模拟器五步门禁、主机侧工具约定；新增"测试构建下 netTask"已知问题（旧版"硬件层模式 netTask 不创建"表述与代码不符，改为设计约束并给出重构路径）；修正附录路径（旧版 `docs/测试说明/CH395F_Test_Guide.md` 等已移入 `docs/测试说明/`）；新增双端注册、内存预算、陷阱沉淀要求 |