245 lines
6.2 KiB
Markdown
245 lines
6.2 KiB
Markdown
# 嵌入式测试开发标准流程（基于 STM32F4 + CH395F 经验）
|
||
|
||
> 适用范围：STM32 裸机/FreeRTOS 项目，Keil MDK-ARM v5 (ARMCC)，串口日志输出测试结果。
|
||
|
||
---
|
||
|
||
## 1. 测试规划（文档先行）
|
||
|
||
在 `docs/` 下创建测试规范文档，定义以下结构：
|
||
|
||
### 1.1 阶段概览表
|
||
|
||
| 阶段 ID | 类型 | 耗时 | 入口 | 出口 |
|
||
|---------|------|------|------|------|
|
||
| TM-PHY-01 | 独立运行 | ~1s | 宏启用 | 串口汇总 |
|
||
|
||
### 1.2 每个测试用例
|
||
|
||
| 字段 | 说明 |
|
||
|------|------|
|
||
| **ID** | `TC-NET-NNN`，唯一编号 |
|
||
| **优先级** | P0（核心）/ P1（重要） |
|
||
| **类型** | 功能测试 / 边界测试 / 负向测试 / 压力测试 / 恢复测试 |
|
||
| **标题** | 一句话描述 |
|
||
| **前置条件** | 硬件状态、PC 端命令、依赖的其他用例 |
|
||
| **测试步骤** | 编号操作序列 |
|
||
| **成功标准** | 精确到"返回值 == 0x00"、"延迟 >= 60000ms" |
|
||
| **失败标准** | 每种失败对应的现象 |
|
||
| **覆盖原则** | 对应哪个设计原则 |
|
||
|
||
关键原则：**先写判定标准，再写测试代码**，避免"测了但不知道算不算过"。
|
||
|
||
---
|
||
|
||
## 2. 测试框架搭建
|
||
|
||
### 2.1 目录结构
|
||
|
||
```
|
||
test/
|
||
ch395f_test.h # 宏定义 + TEST_CHECK/TEST_REPORT + test_stats_t
|
||
ch395f_test_task.h # 仅导出 StartCh395fTestTask
|
||
ch395f_test_task.c # 全 Phase 实现
|
||
```
|
||
|
||
### 2.2 模板文件
|
||
|
||
#### `ch395f_test.h` — 宏+类型
|
||
|
||
```c
|
||
// 阶段使能开关（取消注释即启用）
|
||
#define ENABLE_PHASE1_TESTS
|
||
|
||
// 测试统计
|
||
typedef struct {
|
||
uint16_t total;
|
||
uint16_t passed;
|
||
uint16_t failed;
|
||
} test_stats_t;
|
||
|
||
extern test_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_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)
|
||
```
|
||
|
||
#### `ch395f_test_task.c` — 每个 Phase 的模板
|
||
|
||
```c
|
||
#ifdef ENABLE_PHASEX_TESTS
|
||
/*
|
||
* Phase X — 功能说明
|
||
*
|
||
* 测试目的：（概括）
|
||
* 前置条件：（硬件/软件/PC 端）
|
||
* 通过：（整体判定条件）
|
||
* 失败：（整体判定条件）
|
||
*/
|
||
static void phaseX_run(void) {
|
||
DBG_INFO("=== CH395F Phase X Tests ===");
|
||
|
||
/* ---- TC-NET-NNN: 用例标题 ---- */
|
||
{
|
||
// 原理说明
|
||
// 通过：精确条件
|
||
// 失败：精确条件
|
||
ret = some_api();
|
||
DBG_INFO(" expect: ...");
|
||
DBG_INFO(" actual: ...");
|
||
TEST_CHECK(ret == EXPECTED, "description");
|
||
}
|
||
|
||
TEST_REPORT("Phase X");
|
||
}
|
||
#endif
|
||
```
|
||
|
||
---
|
||
|
||
## 3. 编码规范
|
||
|
||
### 3.1 DBG_INFO 三行输出
|
||
|
||
每个判定点输出三行，一眼看出"期望什么、拿了什么、过没过"：
|
||
|
||
```
|
||
[P1-01] ch395f_check_exist()
|
||
expect: 0x00 (~0x57 = 0xA8)
|
||
actual: 0x00
|
||
[PASS] P1-01 check_exist = 0x00 (expect 0x00)
|
||
```
|
||
|
||
### 3.2 硬编码值加注释
|
||
|
||
```c
|
||
// 好：
|
||
ch395f_status_t ret = ch395f_check_exist();
|
||
// SPI 写入 0x06 (CMD_CHECK_EXIST) + 0x57 (测试字节)
|
||
// 成功：回复 == ~0x57 == 0xA8（CH395F_ERR_SUCCESS = 0x00）
|
||
// 失败：回复 != 0xA8（CH395F_STATUS_NOT_DETECTED = 0xFF）
|
||
|
||
// 不好：
|
||
ch395f_status_t ret = ch395f_check_exist();
|
||
TEST_CHECK(ret == 0, "check_exist OK");
|
||
```
|
||
|
||
### 3.3 无中文字符串
|
||
|
||
ARMCC v5 不识别 UTF-8 多字节字符。`DBG_INFO`/`DBG_ERROR` 中只写 ASCII。注释可以写中文。
|
||
|
||
### 3.4 栈安全
|
||
|
||
大缓冲区（如 64KB）用 `static` 全局，不放任务栈：
|
||
|
||
```c
|
||
#define TEST_BUF_SIZE 65536
|
||
static uint8_t s_rx_buf[TEST_BUF_SIZE];
|
||
```
|
||
|
||
### 3.5 条件编译消除未使用变量警告
|
||
|
||
```c
|
||
static uint8_t s_rx_buf[TEST_BUF_SIZE];
|
||
#if defined(ENABLE_PHASE5_TESTS) || defined(ENABLE_PHASE8_TESTS)
|
||
static uint8_t s_tx_buf[TEST_BUF_SIZE];
|
||
#endif
|
||
```
|
||
|
||
---
|
||
|
||
## 4. 统一入口
|
||
|
||
### 4.1 所有测试在 FreeRTOS 任务中串行执行
|
||
|
||
```
|
||
ch395fTestTask:
|
||
1. 等待 g_net_ready（netTask 初始化完成）
|
||
2. 阻塞执行 Phase 1/2/3/6/9（内部循环，无需外部连接）
|
||
3. 创建 TCP 监听 Socket（端口 8080，单连接模式）
|
||
4. 事件驱动循环 Phase 4/5/7/8/10（等待 PC 连接）
|
||
```
|
||
|
||
### 4.2 不要在 main.c 中直接调用测试
|
||
|
||
main.c 只做硬件初始化和启动 OS，不包含任何测试逻辑。
|
||
|
||
### 4.3 测试文件的手动注册
|
||
|
||
新测试文件需：
|
||
1. 添加到 `test/` 目录
|
||
2. 修改 `MDK-ARM/STM32F407-Demo.uvprojx` 添加文件引用和 IncludePath
|
||
|
||
---
|
||
|
||
## 5. 文档与代码同步
|
||
|
||
- 文档中的入口函数名、宏名、流程描述必须与代码一致
|
||
- 代码变更后立即更新文档，否则文档两天内就会失效
|
||
- 测试用例的通过/失败标准在**文档和代码注释中都写清楚**
|
||
- 文档使用标准 Markdown 表格，避免复杂嵌套导致渲染异常
|
||
|
||
---
|
||
|
||
## 6. 编译验证
|
||
|
||
### 6.1 底线
|
||
|
||
**`0 Error(s), 0 Warning(s)`**，不可妥协。
|
||
|
||
### 6.2 常见警告处理
|
||
|
||
| 警告 | 原因 | 解决 |
|
||
|------|------|------|
|
||
| `#177-D: variable was declared but never referenced` | 条件编译导致 | 加 `#ifdef` 包裹变量声明 |
|
||
| `#870-D: invalid multibyte character sequence` | DBG_INFO 中有中文 | 改为纯 ASCII |
|
||
| 隐式类型转换 | 参数类型不匹配 | 加显式 `(uint8_t)` 等 cast |
|
||
|
||
### 6.3 构建命令
|
||
|
||
```bat
|
||
MDK-ARM\build.bat
|
||
:: 或项目根目录执行 @build
|
||
```
|
||
|
||
退出码：0 = 成功 | 1 = 有警告（不通过）| 2+ = 错误
|
||
|
||
---
|
||
|
||
## 7. 迭代节奏
|
||
|
||
```
|
||
文档（规划 + 判定标准）
|
||
→ 代码（添加 Phase 实现）
|
||
→ @build（0 Error(s), 0 Warning(s)）
|
||
→ 烧录验证（串口观察 PASS/FAIL）
|
||
→ 根据实际结果修正判定标准
|
||
→ 更新文档（保持同步）
|
||
→ 下一阶段
|
||
```
|
||
|
||
---
|
||
|
||
## 附录：本项目的测试文件清单
|
||
|
||
| 文件 | 作用 |
|
||
|------|------|
|
||
| `test/ch395f_test.h` | 测试宏、类型定义、Phase 使能开关 |
|
||
| `test/ch395f_test_task.h` | 导出 `StartCh395fTestTask` |
|
||
| `test/ch395f_test_task.c` | 全 10 个 Phase 实现 |
|
||
| `docs/CH395F_Test_Guide.md` | 测试规范、用例表格、通过/失败标准 |
|
||
| `docs/CH395F_Trap_Records.md` | 已知硬件/软件陷阱及修复 |
|