Files
STM32F4-Base/test/host/README.md
T
wandering1 685a366890 refactor(test): 把 test/host 顶层 25 个台架脚本按域收进 bench/
原来 test/host 一层混了三类东西:51 个主机侧单测模块目录、25 个台架驱动
与探针、若干专用目录。台架脚本平铺在顶层,与单测目录并列,看不出哪个是
「连板跑一次的」,也看不出加新脚本该往哪放。

现在按被验对象分域归档,单测模块目录一律不动(22 根 pre-commit 钩子逐个
点名它们,50 个运行器按固定层数推仓库根):

- bench/bench_defaults.py 台架连接默认值单一真源
- bench/ftp/ (10) FTP 功能、速率、鉴权、中止、完整性、背靠背复现
- bench/net/ (9) CH395F socket、keepalive 判死、挂机、复连压力、PASV、
  UDP 队列、链路时延对端
- bench/iec104/ (2) 主站客户端与它的离线样帧自检
- bench/wave/ (1) 录波段文件 PC 侧解码
- bench/screenlink/ (2) 屏板链路顶替与拉帧压测

顶层条目 78 -> 53。逐脚本作用、运行前置与「加新脚本往哪放」写在新建的
test/host/bench/README.md;test/host/README.md 增目录地图表,把原平铺的
网络/FTP 两节压成指针。

配套修正(移动后不修就会坏):
- 17 个脚本加上 bench/ 到 sys.path 的 bootstrap(sys.path[0] 是脚本自身
  目录,不补就 import bench_defaults 失败)
- cal/cal_write.py 本来就坏的(只插 cal/ 到自己 sys.path,import
  bench_defaults 直接 ModuleNotFoundError),补两段路径后可用
- e6_soak 与 wave_read 用 dirname 固定层数推仓库根,多两层后分别指向
  test/test 与 test/ci-artifacts(后者静默写错目录、不报错),层数已改对
- scripts/board_ui_nav.py 与 MDK-ARM 两个探针的 bench_defaults 搜索路径

清理与标注:删掉 test/host/iec104/(旧自研协议层单测退役后只剩一个零引用
的 stub 桩头);文档里对 test/host/iec104 与 iec104_serv 的引用加上「已
删除/已不存在 2026-11-18」状态词。冻结历史证据(带日期戳的台架日志)与
编号别名登记表里的旧路径按原样保留。
2026-11-18 12:46:03 +08:00

180 lines
16 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# test/host/ — 主机端测试脚本
> PC 侧的两类东西:**主机侧纯逻辑单测**(编真实 C 源码跑在开发机上,零硬件)与
> **台架驱动/探针**(连板 / 连模拟器 / 连 PC 对端,一次性台架动作)。
> 台架脚本自 2026-11-18 起全部收进 `bench/`,本层只剩目录与表格。
## 目录地图
**先看这张表再加东西**——四个位置服务四种不同目的,放错了要么门禁跑不到,要么被门禁误伤。
| 类别 | 位置 | 放什么 | 加新东西该往哪放 |
|---|---|---|---|
| 主机侧单测模块 | `<模块>/run_unit_test.py`(本层 51 个模块目录,其中 48 个带运行器;`cal/` `common/` `iec104_netmcu/` 不带;另有一个 `bench/` 见下行) | 声明式 `TestBuild` + 真实 C 源码 + `stub/`,MSVC 离线编译,纯逻辑零硬件 | **新增单测才往这里加**。目录名即模块名,被 pre-commit 的 21 根 `-unit-test` 钩子逐个点名(`files:` 触发面按目录),`scripts/ci_local.py` 与 `test-coverage` 总闸按 `test/host/**/run_unit_test.py` 发现 |
| 台架驱动与探针 | `bench/`(按域分 `ftp/` `net/` `iec104/` `wave/` `screenlink/`) | 连板 / 连模拟器 / 连 PC 对端的东西:压测、复现器、验收腿、协议抓包 | **一次性台架动作都往这儿**,按被验对象选域子目录。索引与逐脚本一句话见 [`bench/README.md`](bench/README.md) |
| 104 验收资产 / fake net 单测 | `iec104_dtu/`、`iec104_netmcu/` | 前者:真板 104 只读验收探针 + 回环 TCP 用例(`PROBE_RUNBOOK.md`);后者:vendor 协议核与 `net_socket` fake 的静态+动态核查 | 专用,各自 `MATRIX.md` 是口径。**不要**往 `bench/iec104/` 混——那里只有主站客户端与它的离线自检 |
| harness 与假件 | `common/` | `unit_test_harness.py`(MSVC 探测→编译→运行→判退出码)+ 跨模块复用的 `*_fake.c/h` | 新单测只**声明** `TestBuild`,工具链细节不进各模块 |
| 标定工具 | `cal/` | `cal_collect.py`(串口日志取中位数填执行卡)/ `cal_fit.py`(N 点最小二乘,全仓唯一实现)/ `cal_write.py`(C_SE 两段写下发 + C_RD 读回) | 标定是一次性台架动作但**位置固定不动**:执行卡与文档都按这个路径写,挪了要同步 `docs/测试说明/专项验证/ADC多点标定执行流程.md` |
> 已删除(2026-11-18):`iec104/`(旧自研协议层单测,随三源退役,只剩一个零引用的 `stub/dbg_log.h`)
> 与 `iec104_serv/`(旧服务层单测,随服务层重写退役)。
## bench/ — 台架驱动与探针
原来平铺在本层的 25 个脚本(FTP / CH395F / E1·E6·E8·E11·E12 自愈腿 / 104 主站 / 录波 / 屏板链路)
已按域归档进 `bench/`。**逐脚本一句话作用、运行前置、连接默认值在哪 → [`bench/README.md`](bench/README.md)。**
两个高频入口先记在这里:
- **台架地址只改一处**:`bench/bench_defaults.py`(设备 IP / 网关 / PC 对端 IP)。下面的脚本、`cal/`、
`scripts/board_ui_nav.py`、`MDK-ARM/*.py` 都从它取默认值。
- **自愈/Trap 常备回归腿**在 `bench/net/`(`relisten_stress` / `e6_soak` / `e11_keepalive_probe` /
`pasv_probe`)与 `bench/ftp/`(`ftp_abort_probe` / `n30_repro` / `ftp_list_fill_test`)。
## cal/ — 标定三件套(位置固定,勿挪)
一次性的台架标定动作,但路径被执行卡与文档按死(执行卡 `docs/测试说明/专项验证/ADC多点标定执行流程.md`
§3/§4 直接写 `test/host/cal/…`),所以留在本层不进 `bench/`。
| 脚本 | 作用 |
|---|---|
| `cal_collect.py` | **串口日志取数**:从 `serial.log` 最近 N 拍(默认 15)取 `meas:` 读数中位数,填进执行卡 `CALDATA` 表对应行;同一 `--point` 重跑覆盖旧值 |
| `cal_fit.py` | **N 点最小二乘标定求解(全仓唯一实现,v2.2 起固件侧拟合已删除)**(**3~8 点**,推荐 5 点):`--selftest` 跑金标向量回归(原 C 侧 `r_q16=39322000 / b=12` + 4 条拒绝路径,exit 0 全过 / 1 有失败,改动算法后必跑);`--from-doc` 直接读执行卡 §3 `CALDATA` 长表按路分组拟合,输出合并 `WRITE-ALL` 命令;单路 `--sem/--x/--y` 亦可;exit 0 可写 / 2 拒绝(入参越界、点数越界、点位没拉开、单调性反转、斜率非正、r/b 越带、残差 >2%、表还是旧 6 列)或未填 |
| `cal_write.py` | **标定参数写入器**(库层复用 `bench/iec104/iec104_master.py`):C_SE 两段写下发定值段 `0x8050~`(变比 r)/`0x8048~`(零点 b,落笔置 VALID),C_RD 读回复核;每路**先 r 后 b**(b 置 VALID 要求 r 已在带);输出纯 ASCII 可归档;exit 0 全过 / 1 有失败 / 2 连接或协议错误 |
## 主机侧单元测试(纯逻辑,无硬件)
| 文件 | 作用 |
|---|---|
| `common/unit_test_harness.py` | **通用单测 harness**(主机侧纯逻辑单测):探测 MSVC → 拼 `INCLUDE`/`LIB` → 编译 → 运行 → 判定退出码。各模块运行器只做**声明式**配置(`TestBuild`),不含工具链细节 |
| `watchdog/run_unit_test.py` | **看门狗判定状态机单测**:声明 `TestBuild` 后调 harness,用 MSVC 离线编译真实 `App/util/task_watchdog.c`(可观测桩驱动),47 用例穷举边界。零硬件、秒级(退出码 0=PASS/1=FAIL/2=环境错误) |
| `watchdog/watchdog_test.c` | 测试单元本体(`#include` 生产源码 + 平台钩子桩) |
| `watchdog/stub/` | 桩头文件(`main.h`/`iwdg.h`/`dbg_log.h`),覆盖 MCU 版以在 PC 上编译 |
| `sys_clock/run_unit_test.py` | **系统时钟换算单测**:离线编译真实 `App/util/sys_clock.c`,以可控时钟 + 阴影 RTC 桩驱动,100 断言点覆盖闰年/月末/世纪/2038 上限/星期/30 天惰性再基准化/RTC 故障降级 |
| `sys_clock/sys_clock_test.c` | 测试单元本体(`#include` 生产源码 + 强符号桩;**不改生产代码**) |
| `sys_clock/stub/` | 桩头文件(`main.h`/`FreeRTOS.h`/`task.h`/`dbg_log.h`),覆盖 MCU 版以在 PC 上编译 |
| `cfg_file/run_unit_test.py` | **配置引擎单测**:离线编译真实 `App/cfg/cfg_file.c`,以**内存虚拟文件系统**桩驱动,149 断言点覆盖 INI 解析/四种值类型编解码/段注册校验/load-save-poll 契约/超长守卫/故障注入 |
| `cfg_file/cfg_file_test.c` | 测试单元本体(`#include` 生产源码 + `cfg_store_*` 内存 FS 后端桩;**不改生产代码**) |
| `cfg_file/stub/` | 桩头文件(`dbg_log.h`),覆盖 MCU 版以在 PC 上编译 |
| `phasor/run_unit_test.py` | **相量层(L2)单测**:离线编译真实 `App/algo/phasor.c` + `sample_ring.c`(**无需任何桩**,纯算法),57 用例覆盖傅氏系数表 / 幅值·相位 / 谐波抑制与提取 / 频偏 / 采样环 / 双区原子交换 |
| `phasor/phasor_test.c` | 测试单元本体(`#include` 两个生产源码 + 合成任意波形) |
| `adc_input/run_unit_test.py` | **ADC 输入层(L1)单测**:离线编译真实 `App/algo/adc_input.c`,**103** 用例给每个 Rank 注入互异码值**逐通道钉死映射**,并覆盖 DMA 挂载失败 / **乒乓半区选择(撕裂帧防线)** / 超拍丢帧 / 停摆 / HAL 回调句柄守卫 / **停摆拍陈旧帧** / 参数错等真机难复现分支 |
| `adc_input/adc_input_test.c` | 测试单元本体(`#include` 生产源码 + HAL / TPAFE 可注入桩) |
| `adc_input/stub/` | 桩头文件(`adc.h` / `tpafe5160.h`) |
| `vol_lock/run_unit_test.py` | **卷锁单测**:离线编译真实 `App/fs/vol_lock.c`,33 断言点覆盖创建 / 获取 / 释放契约(**fail-open 不变量**:创建失败仍返回 1 且零阻塞)/ 幂等 / 超时透传 |
| `vol_lock/vol_lock_test.c` | 测试单元本体(`#include` 生产源码 + CMSIS 互斥桩) |
| `vol_lock/stub/` | 桩头文件(`cmsis_os.h`) |
| `time_sync/run_unit_test.py` | **时间同步任务载体单测(v2.0)**:离线编译真实 `App/sync/time_sync.c`,33 断言点覆盖分片喂狗延时 / 就绪屏障(100 ms 分片、`osFlagsNoClear`、永不就绪不挂死)/ SNTP 节拍驱动与**网络代次当轮交接** / 未出网守门(:8888 退役后任务即纯校时节拍宿主) |
| `time_sync/time_sync_test.c` | 测试单元本体(`#include` 生产源码 + 网络 / 事件 / RTOS 可脚本化桩 + `longjmp` 跳出 `for(;;)` 任务循环) |
| `time_sync/stub/` | 桩头文件(`FreeRTOS.h` / `task.h` / `cmsis_os2.h` / `net_socket.h`(裁剪至 `net_get_generation`,**编译期绊线**:生产码若再引监听类 API 立刻炸)/ `sys_events.h`) |
| `nand_port/run_unit_test.py` | **dhara NAND 移植层单测**:离线编译真实 `Drivers/BSP/GD5F2GQ5UE/nand_ftl.c` + 真实 `Lib/dhara/{journal,map}.c`,以 **RAM 假芯片**驱动,**149** 断言覆盖 is_free 整页扫描 / 六个 HAL 入口的越界守卫 / 故障注入 / dhara map"写入 → 重新 resume"场景 |
| `nand_port/nand_port_test.c` | 测试单元本体(`#include` 生产源码 + RAM 假芯片;内联一份"只看页首 64 B"的**旧算法对照**,证明断言能咬人) |
| `nand_port/stub/` | 桩头文件(`gd5f2gq5ue.h` 芯片几何与 SPI 原语声明 / `dbg_log.h` 日志宏计数) |
> 本表只列**有专属说明文档**的那几套;`test/host/` 下带 `run_unit_test.py` 的目录共 **48** 个,
> 全量清单以 `scripts/check_test_coverage.py --list` 为准(它同时是 `test-coverage` 总闸的
> 发现规则)。
> 已删除(2026-11-18):`iec104/run_unit_test.py`(82 用例,旧自研协议层三源退役)——
> 对应 `iec104-unit-test` 钩子已于 2026-11-17 摘除,见 `docs/门禁说明/README.md`。
> 详见 `docs/测试说明/单元测试/看门狗单元测试说明.md`、`docs/测试说明/单元测试/系统时钟单元测试说明.md`、
> `docs/测试说明/单元测试/配置文件单元测试说明.md`、`docs/测试说明/单元测试/ADC输入层单元测试说明.md`、
> `docs/测试说明/单元测试/相量层单元测试说明.md`、`docs/测试说明/单元测试/卷锁单元测试说明.md`、
> `docs/测试说明/单元测试/时间同步单元测试说明.md`;
> harness 用法见 [`common/README.md`](common/README.md)。
> 已挂 pre-commit 钩子(各模块同名 `*-unit-test`,共 **21** 个;逐个说明见
> `docs/代码规范/pre-commit使用说明.md` §2.2 与 `docs/门禁说明/host-unit-tests.md`)。
### nand_port —— dhara NAND 移植层为什么能在 PC 上测
**一句话**:移植层是**纯逻辑 + 假芯片**,能钉死真机极难复现的越界/误判路径。
`nand_ftl.c` 的 dhara HAL 六个入口只做地址算术与边界判定,芯片侧全部经 11 个 SPI
原语打交道——把它们换成一块 RAM 假芯片,整层即可离线跑。而它要防的两类缺陷恰恰是
板端**拿不到观测面**的:
- `is_free` 旧实现只看页首 64 B,"页首 0xFF、后段有数据"的已编程页被误判
空闲 → dhara 往已编程页再编程 = 静默数据丢失。真机要恰好撞上那种页形态才发作,
发作后只表现为"某次复位后丢数据"。假芯片把**双编程做成可数事件**(违规计数),
测试还内联一份旧算法做对照:同一页旧算法答"空闲"、新实现答"非空"。
- 越界页/块号(含 `DHARA_PAGE_NONE` 哨兵)旧会被地址位截断成**真实页**
→ 静默读写/搬走无辜数据。真机上没有任何路径会主动喂进越界号。假芯片记录**全部
访问次数**,于是"越界 → 返回 -1 + `DHARA_E_CORRUPT_MAP` 且零芯片访问、零标坏块"
可机械断言。
## 运行方式
```bash
# /serial-boot-test 一键闭环(推荐,需真机)
& '.venv\Scripts\python.exe' .dsh/skills/serial-boot-test/scripts/run_boot_test.py
# 测试套件构建的回归:要求套件跑到汇总行且断言数 > 0
& '.venv\Scripts\python.exe' .dsh/skills/serial-boot-test/scripts/run_boot_test.py `
--required "=== Storage Tests:" --forbidden "ERROR;HardFault;[ERR]" `
--require-suite-summary "Storage Tests"
# 看门狗判定状态机单测(纯逻辑,无需真机)
& '.venv\Scripts\python.exe' test/host/watchdog/run_unit_test.py
# 系统时钟换算单测(纯逻辑,无需真机)
& '.venv\Scripts\python.exe' test/host/sys_clock/run_unit_test.py
# 配置引擎单测(纯逻辑,无需真机)
& '.venv\Scripts\python.exe' test/host/cfg_file/run_unit_test.py
# 相量层(L2)单测(纯逻辑,无需真机)
& '.venv\Scripts\python.exe' test/host/phasor/run_unit_test.py
# ADC 输入层(L1)单测(纯逻辑,无需真机)
& '.venv\Scripts\python.exe' test/host/adc_input/run_unit_test.py
# 卷锁单测(纯逻辑,无需真机)
& '.venv\Scripts\python.exe' test/host/vol_lock/run_unit_test.py
# 时间同步单测(纯逻辑,无需真机)
& '.venv\Scripts\python.exe' test/host/time_sync/run_unit_test.py
# dhara NAND 移植层单测(纯逻辑 + RAM 假芯片,无需真机)
& '.venv\Scripts\python.exe' test/host/nand_port/run_unit_test.py
# 台架脚本(需真机;台架地址在 bench/bench_defaults.py)
& '.venv\Scripts\python.exe' test/host/bench/net/relisten_stress.py --port 7003
& '.venv\Scripts\python.exe' test/host/bench/ftp/ftp_regression.py
& '.venv\Scripts\python.exe' test/host/bench/iec104/iec104_master.py
```
> 串口端口配置在 `.serialtest/config.json`(单一配置源,当前 COM6/115200)。
## ⚠️ 注意
- **PYTHONPATH/路径敏感**:脚本按仓库根相对路径读写,**从仓库根执行**;解释器用 `.venv`。
- 本目录**被 pre-commit 门禁的 cppcheck / 代码规范排除**(`test/` 豁免);
但各模块的 `run_unit_test.py` 自身**作为独立钩子**参与门禁(见上,共 21 个)
- `bench/` 下的脚本要 `import bench_defaults` 时**自带 `_BENCH_DIR` 那三行 `sys.path` bootstrap**
(补 `bench/` 进 `sys.path`),不靠调用方的工作目录或 `PYTHONPATH`;`cal/`、
`scripts/board_ui_nav.py`、`MDK-ARM/*.py` 是跨目录的三处同类 bootstrap。
- `MDK-ARM/*.py` 只余被文档**当作可信判据引用过**的三件(`ftp_freeze_probe` /
`tcp_reconnect_probe` / `bench_verdict`)——2026-10-22 清掉了一批既无人引用、又因设备侧
启用鉴权而再也登录不上的历史一次性探针(`MDK-ARM/ftp_retr_abort_probe.py` 与整个
`MDK-ARM/bench_diag/`(4 个诊断脚本)),需要时从 git 历史取回;`ftp_freeze_probe.py`
因被 Trap 记录当复现配方而保留,已改用设备账号登录。它们也 import `bench_defaults`
(从 `MDK-ARM/` 补 `../test/host/bench`)。
- 全部主机侧单测(48 个带 `run_unit_test.py` 的模块目录)都需要本机装有 MSVC(VS2019/2022/2026 的 C++ 工具链);
无则脚本报环境错误(退出码 2)
## 相关文档
- [`bench/README.md`](bench/README.md) — 台架脚本域索引(逐脚本一句话)+ 运行前置
- [`common/README.md`](common/README.md) — 单测 harness 用法
- `docs/测试说明/流程与规范/自动化测试流程.md` — `/serial-boot-test` 细节与失败模式
- `docs/测试说明/流程与规范/测试开发标准流程.md` — 测试分层与门禁
- `docs/门禁说明/host-unit-tests.md` — 21 根专属钩子台账与补钩判据
- `docs/测试说明/单元测试/看门狗单元测试说明.md` — 主机侧单测(用例 / 平台层 / 扩展方法)
- `docs/测试说明/单元测试/系统时钟单元测试说明.md` — 系统时钟换算单测(用例 / 桩 / Zeller 缺陷记录)
- `docs/测试说明/单元测试/配置文件单元测试说明.md` — 配置引擎单测(内存 FS 桩 / 抓出的 P0)
- `docs/测试说明/单元测试/ADC输入层单元测试说明.md` — ADC 输入层单测(逐 Rank 钉死映射)
- `docs/测试说明/单元测试/相量层单元测试说明.md` — 相量层单测(傅氏系数 / 双区交换)
- `docs/测试说明/单元测试/卷锁单元测试说明.md` — 卷锁单测(fail-open 不变量)
- `docs/测试说明/单元测试/时间同步单元测试说明.md` — 时间同步任务载体单测 v2.0(SNTP 节拍 / 代次交接 / 未出网守门)
- `docs/测试说明/板级测试/CH395F_Test_Guide.md`、`FTP_Test_Guide.md`