wandering1
d3107f374f
- rename_ref.py 搬迁：git mv + 全库引用改写 33 文件 82 处 - README.md 保留 §0 编号空间 / §1 未闭环一览 / §2 推进顺序权威 / §3 维护约定 - 拆出 6 文件：W1-采集保护收尾（任务卡五字段）、排期详述、暂缓-RS485、 登记簿、测试与架构专项、基线与待确认 - 外部引用重定位 ~50 处：裸「登记簿 §X」、§5.1→基线与待确认 §2.1、 §2.4→暂缓-RS485、§6→基线与待确认 §3、脚本注释 T-x/N-x→登记簿 - 新增并行写纪律：任务分支不改本文件夹，状态列由 Lead 主工作树更新 - 验证：doc-links 141 文档全绿；mem-numbers 一致；refgraph 重生成； @build 0 错误 0 警告；新文件无 BOM / LF / 零乱码
274 lines
11 KiB
Python
274 lines
11 KiB
Python
#!/usr/bin/env python3
|
||
# -*- coding: utf-8 -*-
|
||
"""unit_test_harness.py - 主机侧单元测试（L0.5）的通用运行器 harness。
|
||
|
||
职责（**不认识任何具体模块**）：
|
||
探测本机 MSVC 工具链 -> 拼 INCLUDE/LIB -> 编译测试单元 -> 运行 -> 判定退出码。
|
||
被测模块的差异（源文件、桩目录、额外 include、断言汇总行特征）全部由调用方
|
||
（各模块自己的 `run_unit_test.py`）传入。
|
||
|
||
为什么要 harness（2026-10-01 测试架构评审 T-3）：
|
||
看门狗单测的运行器（`test/host/watchdog/run_unit_test.py`，170 行）把工具链
|
||
探测、`INCLUDE`/`LIB` 拼接、GBK 解码、`/wd4819` 抑制、退出码契约**全部写死在
|
||
模块目录内**。第二个 L0.5 单测出现时须整段复制——工具链细节一旦修正（新增 VS
|
||
版本、SDK 布局变化、编码处理调整）就会发散。抽到这里后，各模块运行器只剩
|
||
"声明式"配置。
|
||
|
||
实现要点（为何不用 vcvars64.bat）：
|
||
vcvars64.bat 内部调用 reg.exe 探测环境；本机策略禁止 reg.exe。故这里**直接
|
||
拼 INCLUDE/LIB 环境变量**并绝对路径调用 cl.exe——只需 3 个已知目录
|
||
（MSVC 版本 / Windows SDK include / SDK lib），无副作用、可重复。
|
||
|
||
退出码契约（各模块运行器统一遵循）：
|
||
0 = PASS（编译 + 运行成功，且日志满足 summary_marker 要求）
|
||
1 = FAIL（有测试用例未通过）
|
||
2 = 环境错误（找不到编译器 / 编译失败 / 未产生汇总行）
|
||
|
||
用法（模块侧 `run_unit_test.py`）：
|
||
|
||
from unit_test_harness import run_host_unit_test, TestBuild
|
||
|
||
if __name__ == "__main__":
|
||
raise SystemExit(run_host_unit_test(TestBuild(
|
||
name="Task Watchdog Tests",
|
||
src=<测试单元 .c 的绝对路径>,
|
||
include_dirs=[<桩目录>, <生产源码目录>],
|
||
summary_marker="=== Task Watchdog Tests:",
|
||
)))
|
||
|
||
设计依据：docs/任务规划/登记簿.md T-3；docs/测试说明/测试开发标准流程.md §4.2
|
||
创建日期：2026-10-01
|
||
"""
|
||
|
||
import glob
|
||
import os
|
||
import subprocess
|
||
import sys
|
||
import tempfile
|
||
from dataclasses import dataclass, field
|
||
|
||
# ----------------------------- 工具链探测位置 -----------------------------
|
||
# 显式覆盖（环境变量，见 docs/环境与部署/本地工具路径环境变量方案.md）：
|
||
# DTU_MSVC_CL x64 Host cl.exe 完整路径（最高优先级；无效直接报错）
|
||
# DTU_WINDOWS_KITS_ROOT Windows Kits\10 根目录
|
||
# 未设置时用标准布局自动探测：默认安装根由系统变量 %ProgramFiles% /
|
||
# %ProgramFiles(x86)% 推导（不写死盘符）；`_first` 取每个根目录下最大的版本子目录。
|
||
|
||
|
||
def _default_vs_roots():
|
||
"""标准 VS 安装根（2019 -> Program Files (x86)；2022/2026 -> Program Files）。"""
|
||
pf = os.environ.get("ProgramFiles", r"C:\Program Files")
|
||
pf86 = os.environ.get("ProgramFiles(x86)", r"C:\Program Files (x86)")
|
||
roots = []
|
||
for year, base in (("2019", pf86), ("2022", pf), ("2026", pf)):
|
||
for edition in ("BuildTools", "Community", "Professional", "Enterprise"):
|
||
roots.append(os.path.join(base, "Microsoft Visual Studio", year, edition))
|
||
# VS2026 的实际安装目录名是 "18"（2026-10 台架实测：vswhere → ...\18\Community，
|
||
# MSVC 14.51 + SDK 10.0.26100 布局与 2022 一致，cl.exe 路径模式不变）；
|
||
# 上面 "2026" 目录名在本机并不存在，保留以防将来布局回改
|
||
for edition in ("BuildTools", "Community", "Professional", "Enterprise"):
|
||
roots.append(os.path.join(pf, "Microsoft Visual Studio", "18", edition))
|
||
return roots
|
||
|
||
|
||
def _default_sdk_roots():
|
||
r"""Windows SDK 默认安装根（%ProgramFiles(x86)%\Windows Kits\10）。"""
|
||
pf86 = os.environ.get("ProgramFiles(x86)", r"C:\Program Files (x86)")
|
||
return [os.path.join(pf86, "Windows Kits", "10")]
|
||
|
||
|
||
def _sdk_dirs(sdk):
|
||
"""返回某 Windows Kits 根下的 (include 子目录列表, lib 子目录列表)。"""
|
||
sdk_inc = _first(os.path.join(sdk, r"Include\*"))
|
||
sdk_lib = _first(os.path.join(sdk, r"Lib\*"))
|
||
inc = []
|
||
if sdk_inc:
|
||
inc = [os.path.join(sdk_inc, "ucrt"),
|
||
os.path.join(sdk_inc, "shared"),
|
||
os.path.join(sdk_inc, "um")]
|
||
lib = []
|
||
if sdk_lib:
|
||
lib = [os.path.join(sdk_lib, "ucrt", "x64"),
|
||
os.path.join(sdk_lib, "um", "x64")]
|
||
return inc, lib
|
||
|
||
# 编译开关（各模块共用；模块特有开关见 TestBuild.extra_flags）
|
||
_BASE_FLAGS = [
|
||
"/nologo", "/W4", "/std:c11", "/utf-8",
|
||
# C4819（"源代码包含不能在当前代码页中表示的字符"）是**纯编码诊断**：
|
||
# 测试单元确为 UTF-8（带 BOM，已核验），且已显式传 /utf-8，字节解码无误、
|
||
# 编译产物正确。但在"只设 INCLUDE/LIB、不调 vcvars"的调用方式下，
|
||
# MSVC 的代码页探测会退化为 `代码页(0)` → 恒定误报。
|
||
# 测试单元仅主机侧编译（ARMCC 从不编译 test/），故显式屏蔽，保持门禁输出干净。
|
||
"/wd4819",
|
||
]
|
||
|
||
|
||
@dataclass
|
||
class TestBuild:
|
||
"""一个主机侧单测的构建描述（声明式；harness 只读这些字段）。"""
|
||
|
||
name: str # 人类可读名称（打印用），如 "Task Watchdog Tests"
|
||
src: str # 测试单元 .c 的绝对路径（内部 #include 生产源）
|
||
include_dirs: list = field(default_factory=list) # /I 目录（桩目录需在前，覆盖真实头）
|
||
summary_marker: str = "" # 运行输出中必须出现的汇总行前缀；空 = 不校验
|
||
extra_flags: list = field(default_factory=list) # 追加的 cl.exe 开关
|
||
exe_name: str = "" # 产物 exe 名；空 = 由 name 派生
|
||
obj_tag: str = "" # 中间 obj 目录名；空 = 由 name 派生
|
||
|
||
def resolved_exe(self):
|
||
if self.exe_name:
|
||
return self.exe_name
|
||
tag = "".join(c if c.isalnum() else "_" for c in self.name).strip("_").lower()
|
||
return tag + ".exe"
|
||
|
||
def resolved_obj_tag(self):
|
||
if self.obj_tag:
|
||
return self.obj_tag
|
||
tag = "".join(c if c.isalnum() else "_" for c in self.name).strip("_").lower()
|
||
return tag + "_obj"
|
||
|
||
|
||
def _first(pattern):
|
||
"""glob 命中里取最大者（版本号目录的字符串序即数值序，前提是位数一致）。"""
|
||
hits = sorted(glob.glob(pattern))
|
||
return hits[-1] if hits else None
|
||
|
||
|
||
def decode(b):
|
||
"""把 subprocess 字节输出解码为字符串。
|
||
|
||
本机 MSVC 输出为 GBK（代码页 936），测试程序自身输出为 UTF-8；
|
||
按 UTF-8 优先、失败回退 GBK 处理。
|
||
"""
|
||
if isinstance(b, str):
|
||
return b
|
||
try:
|
||
return b.decode("utf-8")
|
||
except UnicodeDecodeError:
|
||
return b.decode("gbk", errors="replace")
|
||
|
||
|
||
def locate_toolchain():
|
||
"""返回 (cl.exe, include_dirs, lib_dirs)；找不到返回 (None, [], [])。
|
||
|
||
优先级（见方案文档）：DTU_MSVC_CL / DTU_WINDOWS_KITS_ROOT（显式设置但
|
||
无效 → 立即报错，**不静默回退**自动探测）→ 标准布局自动探测
|
||
（_default_vs_roots / _default_sdk_roots）。
|
||
"""
|
||
# ---- cl.exe ----
|
||
explicit_cl = os.environ.get("DTU_MSVC_CL", "").strip()
|
||
if explicit_cl:
|
||
if not os.path.isfile(explicit_cl):
|
||
print("[ENV] DTU_MSVC_CL 已设置但不存在: {}（请修正变量值，不做自动探测回退）"
|
||
.format(explicit_cl), file=sys.stderr)
|
||
return None, [], []
|
||
tail = os.path.normpath(explicit_cl).lower()
|
||
if not tail.endswith(os.path.join("bin", "hostx64", "x64", "cl.exe")):
|
||
print("[ENV] DTU_MSVC_CL 必须是 x64 Host 编译器（路径以 bin\\Hostx64\\x64\\cl.exe 结尾）: {}"
|
||
.format(explicit_cl), file=sys.stderr)
|
||
return None, [], []
|
||
cl = explicit_cl
|
||
else:
|
||
cl = None
|
||
for vs in _default_vs_roots():
|
||
c = _first(os.path.join(vs, r"VC\Tools\MSVC\*\bin\Hostx64\x64\cl.exe"))
|
||
if c:
|
||
cl = c
|
||
break
|
||
if not cl:
|
||
return None, [], []
|
||
|
||
# cl.exe = <vs>\VC\Tools\MSVC\<ver>\bin\Hostx64\x64\cl.exe
|
||
msvc_ver_dir = os.path.dirname(os.path.dirname(os.path.dirname(
|
||
os.path.dirname(cl)))) # -> ...\MSVC\<ver>
|
||
inc = [os.path.join(msvc_ver_dir, "include")]
|
||
lib = [os.path.join(msvc_ver_dir, "lib", "x64")]
|
||
|
||
# ---- Windows SDK ----
|
||
explicit_sdk = os.environ.get("DTU_WINDOWS_KITS_ROOT", "").strip()
|
||
if explicit_sdk:
|
||
if not os.path.isdir(explicit_sdk):
|
||
print("[ENV] DTU_WINDOWS_KITS_ROOT 已设置但不存在: {}（请修正变量值，不做自动探测回退）"
|
||
.format(explicit_sdk), file=sys.stderr)
|
||
return None, [], []
|
||
sdk_inc, sdk_lib = _sdk_dirs(explicit_sdk)
|
||
if not sdk_inc and not sdk_lib:
|
||
print("[ENV] DTU_WINDOWS_KITS_ROOT 下未找到 Include\\<ver> 或 Lib\\<ver>: {}".format(explicit_sdk),
|
||
file=sys.stderr)
|
||
return None, [], []
|
||
else:
|
||
sdk_inc, sdk_lib = [], []
|
||
for sdk in _default_sdk_roots():
|
||
sdk_inc, sdk_lib = _sdk_dirs(sdk)
|
||
if sdk_inc or sdk_lib:
|
||
break
|
||
inc += sdk_inc
|
||
lib += sdk_lib
|
||
return cl, inc, lib
|
||
|
||
|
||
def build_and_run(build, out=None):
|
||
"""编译并运行一个测试单元。返回退出码 0/1/2（见模块 docstring 契约）。"""
|
||
if out is None:
|
||
out = sys.stdout
|
||
err = sys.stderr
|
||
|
||
cl, inc, lib = locate_toolchain()
|
||
if not cl:
|
||
print("[ENV] 找不到 MSVC cl.exe（设置 DTU_MSVC_CL，或安装 VS2019/2022/2026 的 C++ 工具链）", file=err)
|
||
return 2
|
||
|
||
tmp = tempfile.gettempdir()
|
||
objdir = os.path.join(tmp, build.resolved_obj_tag())
|
||
os.makedirs(objdir, exist_ok=True)
|
||
exe = os.path.join(tmp, build.resolved_exe())
|
||
|
||
env = dict(os.environ)
|
||
env["INCLUDE"] = os.pathsep.join(inc)
|
||
env["LIB"] = os.pathsep.join(lib)
|
||
env["PATH"] = os.path.dirname(cl) + os.pathsep + env.get("PATH", "")
|
||
|
||
cmd = [cl] + _BASE_FLAGS
|
||
for d in build.include_dirs:
|
||
cmd += ["/I", d]
|
||
cmd += list(build.extra_flags)
|
||
cmd += [build.src, "/Fe:" + exe, "/Fo:" + objdir + os.sep]
|
||
|
||
print("=== 编译并运行 {} ===".format(build.name), file=out)
|
||
cp = subprocess.run(cmd, env=env, capture_output=True)
|
||
cout, cerr = decode(cp.stdout), decode(cp.stderr)
|
||
if cout:
|
||
out.write(cout)
|
||
if cerr:
|
||
err.write(cerr)
|
||
if cp.returncode != 0:
|
||
print("[ENV] 编译失败", file=err)
|
||
return 2
|
||
|
||
run = subprocess.run([exe], env=env, capture_output=True)
|
||
rout = decode(run.stdout)
|
||
out.write(rout)
|
||
rerr = decode(run.stderr)
|
||
if rerr:
|
||
err.write(rerr)
|
||
|
||
if build.summary_marker and build.summary_marker not in rout:
|
||
print("[ENV] 未产生测试汇总行（找不到 {!r}）".format(build.summary_marker), file=err)
|
||
return 2
|
||
if run.returncode == 0:
|
||
print("[OK] 单元测试全部通过", file=out)
|
||
return 0
|
||
print("[FAIL] 有测试用例未通过", file=err)
|
||
return 1
|
||
|
||
|
||
def run_host_unit_test(build):
|
||
"""模块侧入口薄封装：固定控制台 UTF-8 后调用 build_and_run。"""
|
||
for stream in (sys.stdout, sys.stderr):
|
||
try:
|
||
stream.reconfigure(encoding="utf-8", errors="replace")
|
||
except Exception:
|
||
pass
|
||
return build_and_run(build)
|