/*
 * 模块名称：板端测试套件公共断言宏
 * 模块功能：为 test/board/ 下的各测试套件提供**语义统一**的统计结构体与断言/
 *           报告宏内核，消除 4 套件（CH395F / STORAGE / GD5F / RTC）之间逐字重复的
 *           宏定义（2026-10-01 测试架构评审）。
 *
 *           设计取舍：**统计变量仍按套件独立**（各套件持有自己的 `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) ===`
 * 该汇总行是 `/serial-boot-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 */