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

背景：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/开关切换/异常还原均实测通过。
2026-10-01 07:28:57 +08:00
parent 6b90fa0581
commit 2055de0303
24 changed files with 1135 additions and 261 deletions
@@ -8,6 +8,7 @@
 | 文件 | 测试对象 / 作用 |
 |---|---|
 | `test_config.c/h` | **测试任务配置**：`TEST_SUITE_*` 套件选择开关（互斥）+ `ENABLE_DESTRUCTIVE_TESTS` |
+| `test_common.h` | **公共断言内核**：`test_stats_t` + `TEST_CHECK_IMPL`/`TEST_REPORT_IMPL`；各套件用一行宏绑定自身统计变量（T-4） |
 | `ch395f_test_task.c/h` + `ch395f_test.h` | CH395F 以太网（硬件层 Phase 1~5 / NET 层 Phase 6~11） |
 | `gd5f_test_task.c/h` + `gd5f_test.h` | GD5F2GQ5UE SPI NAND 存储 |
 | `sd2506_test_task.c/h` + `sd2506_test.h` | SD2506 RTC |
@@ -19,6 +20,10 @@

 - **套件互斥**：`test_config.h` 的 `TEST_SUITE_CH395F/STORAGE/GD5F/RTC` 一次只能启用一个
  （违反则 `#error`）；**全部注释 = 产品构建**
+- ⚠️ **测试固件不得静默提交**：`TEST_SUITE_*` 开关受 pre-commit 钩子 `test-suite-switch`
+  门禁——默认要求全部注释。跑完套件回归**务必改回产品构建**再提交（2026-10-01 实测已提交
+  HEAD 里 `TEST_SUITE_CH395F` 就是开启状态，纯靠人记得改；故补此门禁）。确需提交测试构建时用
+  `ALLOW_TEST_BUILD=1 git commit ...` 或 `python scripts/check_test_suite.py --allow-test-build` 显式放行
 - **破坏性用例默认关闭**：`ENABLE_DESTRUCTIVE_TESTS`（默认注释）控制写/擦 NAND、格式化、
  坏块注入。关闭时为**只读模式**（横幅 `mode: READ-ONLY`），可随时在在用设备上跑
 - ⚠️ 实测一轮破坏性 GD5F 运行即让 dhara **多记一个坏块**（容量下降且需全片擦除恢复）——
@@ -37,6 +37,7 @@ extern "C" {
 #endif

 #include <stdint.h>
+#include "test_common.h"

 /*
 * 阶段使能开关（取消注释即启用对应阶段）
@@ -85,30 +86,15 @@ extern "C" {
 #error "硬件层(1~5)与NET层(6~11)测试互斥：请分两次构建，见 CH395F_Test_Guide 构建模式与执行顺序"
 #endif

-/* 测试统计 */
-typedef struct {
-    uint16_t total;
-    uint16_t passed;
-    uint16_t failed;
-} test_stats_t;
+/* 测试统计（本套件独立，防跨套件串数；内核见 test_common.h） */
+typedef test_stats_t ch395f_stats_t;

-extern test_stats_t g_test_stats;
+extern ch395f_stats_t g_test_stats;

-#define TEST_CHECK(cond, fmt, ...) do { \
-    g_test_stats.total++; \
-    if (cond) { \
-        g_test_stats.passed++; \
-        DBG_INFO("[PASS] " fmt, ##__VA_ARGS__); \
-    } else { \
-        g_test_stats.failed++; \
-        DBG_ERROR("[FAIL] " fmt, ##__VA_ARGS__); \
-    } \
-} while (0)
+#define TEST_CHECK(cond, fmt, ...) \
+    TEST_CHECK_IMPL(g_test_stats, cond, fmt, ##__VA_ARGS__)

-#define TEST_REPORT(name) do { \
-    DBG_INFO("=== %s: %d/%d PASSED (failed=%d) ===", \
-             name, g_test_stats.passed, g_test_stats.total, g_test_stats.failed); \
-} while (0)
+#define TEST_REPORT(name) TEST_REPORT_IMPL(g_test_stats, name)

 #ifdef __cplusplus
 }
@@ -31,6 +31,7 @@ extern "C" {
 #endif

 #include <stdint.h>
+#include "test_common.h"
 #include "gd5f2gq5ue.h"

 /* ======================== 阶段使能开关 ======================== */
@@ -53,30 +54,14 @@ extern "C" {

 /* ======================== 测试统计与断言 ======================== */

-typedef struct {
-    uint16_t total;
-    uint16_t passed;
-    uint16_t failed;
-} gd5f_test_stats_t;
+typedef test_stats_t gd5f_test_stats_t;

 extern gd5f_test_stats_t g_gd5f_test_stats;

-#define GD5F_TEST_CHECK(cond, fmt, ...) do { \
-    g_gd5f_test_stats.total++; \
-    if (cond) { \
-        g_gd5f_test_stats.passed++; \
-        DBG_INFO("[PASS] " fmt, ##__VA_ARGS__); \
-    } else { \
-        g_gd5f_test_stats.failed++; \
-        DBG_ERROR("[FAIL] " fmt, ##__VA_ARGS__); \
-    } \
-} while (0)
+#define GD5F_TEST_CHECK(cond, fmt, ...) \
+    TEST_CHECK_IMPL(g_gd5f_test_stats, cond, fmt, ##__VA_ARGS__)

-#define GD5F_TEST_REPORT(name) do { \
-    DBG_INFO("=== %s: %d/%d PASSED (failed=%d) ===", \
-             name, g_gd5f_test_stats.passed, g_gd5f_test_stats.total, \
-             g_gd5f_test_stats.failed); \
-} while (0)
+#define GD5F_TEST_REPORT(name) TEST_REPORT_IMPL(g_gd5f_test_stats, name)

 #if defined(ENABLE_GD5F_TESTS)
 void gd5f_test_run(void);
@@ -2,6 +2,7 @@
 #define SD2506_TEST_H

 #include <stdint.h>
+#include "test_common.h"

 #ifdef __cplusplus
 extern "C" {
@@ -11,31 +12,15 @@ extern "C" {
 #define ENABLE_RTC_BASIC_TESTS        /* Phase 1: 基本读写 / 走时 */
 #define ENABLE_RTC_API_TESTS          /* Phase 2: 全功能 API 覆盖（BCD互转/温度/电压/ID/SRAM/报警） */

-/* ============ 测试统计（与 STORAGE/GD5F 套件一致的独立统计） ============ */
-typedef struct {
-    uint16_t total;
-    uint16_t passed;
-    uint16_t failed;
-} sd2506_test_stats_t;
+/* ============ 测试统计（本套件独立，防跨套件串数；内核见 test_common.h） ============ */
+typedef test_stats_t sd2506_test_stats_t;

 extern sd2506_test_stats_t g_sd2506_test_stats;

-#define SD2506_TEST_CHECK(cond, fmt, ...) do { \
-    g_sd2506_test_stats.total++; \
-    if (cond) { \
-        g_sd2506_test_stats.passed++; \
-        DBG_INFO("[PASS] " fmt, ##__VA_ARGS__); \
-    } else { \
-        g_sd2506_test_stats.failed++; \
-        DBG_ERROR("[FAIL] " fmt, ##__VA_ARGS__); \
-    } \
-} while (0)
+#define SD2506_TEST_CHECK(cond, fmt, ...) \
+    TEST_CHECK_IMPL(g_sd2506_test_stats, cond, fmt, ##__VA_ARGS__)

-#define SD2506_TEST_REPORT(name) do { \
-    DBG_INFO("=== %s: %u/%u PASSED (failed=%u) ===", \
-             name, g_sd2506_test_stats.passed, g_sd2506_test_stats.total, \
-             g_sd2506_test_stats.failed); \
-} while (0)
+#define SD2506_TEST_REPORT(name) TEST_REPORT_IMPL(g_sd2506_test_stats, name)

 /* 测试入口：由 start_test_task 经 TEST_SUITE_RTC 调度，顺序执行 Phase 1~3 */
 void sd2506_test_run(void);
@@ -16,31 +16,16 @@ extern "C" {
 #endif

 #include <stdint.h>
+#include "test_common.h"

-typedef struct {
-    uint16_t total;
-    uint16_t passed;
-    uint16_t failed;
-} storage_test_stats_t;
+typedef test_stats_t storage_test_stats_t;

 extern storage_test_stats_t g_storage_stats;

-#define STORAGE_TEST_CHECK(cond, fmt, ...) do { \
-    g_storage_stats.total++; \
-    if (cond) { \
-        g_storage_stats.passed++; \
-        DBG_INFO("  [PASS] " fmt, ##__VA_ARGS__); \
-    } else { \
-        g_storage_stats.failed++; \
-        DBG_ERROR("  [FAIL] " fmt, ##__VA_ARGS__); \
-    } \
-} while (0)
+#define STORAGE_TEST_CHECK(cond, fmt, ...) \
+    TEST_CHECK_IMPL(g_storage_stats, cond, fmt, ##__VA_ARGS__)

-#define STORAGE_TEST_REPORT(name) do { \
-    DBG_INFO("=== %s: %d/%d PASSED (failed=%d) ===", \
-             name, g_storage_stats.passed, g_storage_stats.total, \
-             g_storage_stats.failed); \
-} while (0)
+#define STORAGE_TEST_REPORT(name) TEST_REPORT_IMPL(g_storage_stats, name)

 /* 存储测试入口：FTL + FatFS 文件系统与性能测试 */
 void storage_test_run(void);
@@ -0,0 +1,82 @@
+/*
+ * 模块名称：板端测试套件公共断言宏
+ * 模块功能：为 test/board/ 下的各测试套件提供**语义统一**的统计结构体与断言/
+ *           报告宏内核，消除 4 套件（CH395F / STORAGE / GD5F / RTC）之间逐字重复的
+ *           宏定义（2026-10-01 测试架构评审 T-4）。
+ *
+ *           设计取舍：**统计变量仍按套件独立**（各套件持有自己的 `g_xxx_stats`），
+ *           公共宏只提供"内核"，由各套件用一行宏把它绑定到自己的统计变量。
+ *           理由见 docs/测试说明/测试开发标准流程.md §3.2：
+ *             - 统计变量独立 = 防跨套件串数（历史约定，不能破）；
+ *             - 内核共用    = 报告行格式/字段一处维护，改一次即全生效。
+ *
+ * 适用平台：STM32F4 系列
+ * 作者：王建锋
+ * 创建日期：2026-10-01
+ *
+ * ⚠️ 本头文件**刻意不 include `dbg_log.h`**：
+ *  `dbg_log.h` 在未定义 `DBG_TAG` 时会给出默认值 `""`（`#ifndef DBG_TAG`），
+ *  而本文件被各套件头在**很靠前**的位置包含——若在此处拉入 `dbg_log.h`，
+ *  会把空 `DBG_TAG` 冻结，导致各 `.c` 文件随后 `#define DBG_TAG "[TEST_TASK]"`
+ *  触发 ARMCC `#47-D: incompatible redefinition of macro "DBG_TAG"`（实测 8 条警告）。
+ *  这里的宏只在**使用点**展开（使用点在 `.c` 中，且那些 `.c` 已按约定先
+ *  `#define DBG_TAG` 再 include `dbg_log.h`），故无需在此引入。
+ *
+ * 用法（套件头文件内）：
+ *   #include "test_common.h"
+ *   typedef test_stats_t gd5f_stats_t;              // 或直接用 test_stats_t
+ *   extern gd5f_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)
+ */
+
+#ifndef TEST_COMMON_H
+#define TEST_COMMON_H
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#include <stdint.h>
+
+/* 测试统计（各套件**各自**定义一个此类型的外部变量，防跨套件串数） */
+typedef struct {
+    uint16_t total;
+    uint16_t passed;
+    uint16_t failed;
+} test_stats_t;
+
+/*
+ * 断言内核：统计自增 + [PASS]/[FAIL] 打印。
+ * 套件侧不应直接调用本宏（每次都要写统计变量名），而应用它派生出
+ * 自己的 `XXX_TEST_CHECK(cond, fmt, ...)`（见文件头用法）。
+ */
+#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)
+
+/*
+ * 报告内核：套件运行结束时打印汇总行
+ *   `=== <name>: N/M PASSED (failed=0) ===`
+ * 该汇总行是 `@test` 回归的默认判定标记（见 测试开发标准流程.md §3.2/§6.2.1）。
+ */
+#define TEST_REPORT_IMPL(stats, name) do { \
+    DBG_INFO("=== %s: %u/%u PASSED (failed=%u) ===", \
+             name, \
+             (unsigned)(stats).passed, (unsigned)(stats).total, \
+             (unsigned)(stats).failed); \
+} while (0)
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* TEST_COMMON_H */
@@ -23,11 +23,11 @@ extern "C" {
 #include <stdint.h>

 /* === 选择当前构建的测试套件（三选一，或都注释 = 正常产品构建）===
- * 2026-09-22：M1~M3（链路时延 Phase 12/13/14，阶段表见说明文档 §4.2）交付 ——
- * 当前启用 CH395F 套件 + Phase 14（生产路径时延，M3 基线已锁定，2026-09-22 重锁）。
- * 恢复产品构建 = 注释掉下方 TEST_SUITE_CH395F 一行（ch395f_test.h 的阶段宏
- * 仅在套件启用时生效，无需另改）。详见 docs/测试说明/链路延迟测试说明.md §4.2/§5。 */
-#define TEST_SUITE_CH395F
+ * ⚠️ 默认必须是**产品构建**（全部注释）——pre-commit 钩子 `test-suite-switch` 会拦截
+ * 未显式放行的测试构建（`--allow-test-build` / `ALLOW_TEST_BUILD=1`）。
+ * 跑套件回归时取消注释所需套件；跑完务必改回、或直接用 `test/run_all_suites.py`
+ * （自动改宏 + 结束后无条件还原）。详见 docs/测试说明/测试开发标准流程.md §3.1/§3.6。 */
+//#define TEST_SUITE_CH395F
 //#define TEST_SUITE_STORAGE
 //#define TEST_SUITE_GD5F
 //#define TEST_SUITE_RTC