1. 从“改一行不敢回归”说起:CppUTest 在代码开发工具链里的位置
接手 C/C++ 老项目时,代码开发工具里最缺的往往不是编辑器,而是一套能反复跑的 CppUTest 测试。它把 C/C++ 单元测试、Mock 依赖和内存泄漏检测放进同一条反馈链:用例组织逻辑,Mock 挡住硬件或第三方库,内存泄漏检测每次运行后给出资源警报。适合维护老代码、写嵌入式固件、想给纯 C 函数补回归的人。
我第一次把它接进某电机控制模块,最大的变化不是测试行数变多,而是改完代码敢立刻跑一遍;参数调错、边界漏判、资源没释放,都能在几秒内看到。
下面从工程骨架、用例组织、Mock 与内存泄漏,到踩坑排查和进阶验证,按能照做的顺序拆开。
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 代码开发工具选型:CppUTest 工程骨架怎么搭才不返工
2.1 为什么不是“先写个 main 跑一下”
很多老项目一开始都有个 main 里塞满 printf 的临时测试:改一个宏、重新编译、看串口输出、再改回去。这个办法不是不能用,而是它把“验证”绑在人的记忆和手工动作上。今天调通了,明天改一行别的代码,没人知道原来那个边界还在不在。CppUTest 的价值不是让测试看起来更正式,而是把一次性的手工验证变成可以重复执行的入口,失败时能定位到具体用例,而不是在一屏串口日志里翻。
选型时我看三件事:能不能直接测 C 函数、能不能把硬件依赖挡在测试外面、能不能在每次运行后暴露资源没释放的问题。CppUTest 的语法接近 xUnit 风格,但它的测试入口和断言对 C 代码比较友好,测试文件可以用 C++ 编译,被测代码仍然是 C。这样老代码不用为了测试重写一遍,头文件加 extern "C" 就能接进来。Mock 和内存泄漏检测也不是外挂插件式的临时方案,而是测试运行链里的一部分,适合在宿主机器上跑回归,再在目标板上保留少量冒烟测试。
临时 main 最大的问题是没有隔离。一个用例改坏了全局状态,下一个用例跟着失败;一个 malloc 没释放,程序跑完也看不出来。CppUTest 用 TEST_GROUP 把每个用例的 setup 和 teardown 框起来,至少让“上一个用例留下的脏状态”有地方清。它不强迫你把老代码拆成漂亮的分层,但会逼你想清楚:这个函数依赖谁、返回值怎么断言、分配的资源由谁释放。对正在维护 C/C++ 老代码的人来说,这比一上来追求覆盖率更实际。
2.2 最小可跑骨架:目录、编译入口与第一个空测试
我一般把测试骨架压到三个目录:src 放被测实现,include 放对外头文件,tests 放测试入口和用例。不要一开始就把测试文件塞进 src,否则交叉编译目标板固件时很容易把测试运行器一起编进去。测试构建单独一个入口,目标板构建只挑 src 里的实现,这是后面少返工的关键。
先给一个能跑起来的 Makefile 片段,变量用占位路径,实际接到项目已有的 CppUTest 依赖位置:
makefile复制# 测试构建单独入口,不混进目标板固件
CPPUTEST_HOME ?= /path/to/cpputest
CXX ?= g++
CXXFLAGS += -Iinclude -I$(CPPUTEST_HOME)/include -Wall -Wextra
LDFLAGS += -L$(CPPUTEST_HOME)/lib -lCppUTest -lCppUTestExt
TEST_SRC := tests/AllTests.cpp tests/SensorSampleTest.cpp
TEST_OBJ := $(TEST_SRC:.cpp=.o)
test_runner: $(TEST_OBJ) src/sensor_sample.o
$(CXX) $^ $(LDFLAGS) -o $@
这段 Makefile 只做一件事:把测试源文件、被测实现和 CppUTest 库链成一个可执行测试运行器。CPPUTEST_HOME 指向项目已有的 CppUTest 依赖目录,不要写死到某台机器的绝对路径;CXXFLAGS 里的 -Iinclude 是让测试代码能找到被测头文件,-I$(CPPUTEST_HOME)/include 是找 CppUTest 头文件;LDFLAGS 里的 -lCppUTest 是测试框架本体,-lCppUTestExt 留给后面的 Mock 扩展。TEST_SRC 先列一个入口和一个用例文件,后面加用例只改这一行,不要把每个测试文件都手写进链接命令。
测试运行器需要一个最小入口,放在 tests/AllTests.cpp:
cpp复制#include "CppUTest/CommandLineTestRunner.h"
int main(int argc, char** argv) {
// 所有测试用例由运行器统一发现和执行
return CommandLineTestRunner::RunAllTests(argc, argv);
}
这个入口不写业务逻辑,只把命令行参数交给 CommandLineTestRunner。argc 和 argv 保留下来是为了后面能按组过滤用例,排查时不用每次跑全量。入口文件只编进测试目标,不要编进目标板固件;否则目标板会多背一个用不到的命令行运行器,链接时还容易把宿主机的标准库依赖带进来。
骨架搭好后,先放一个空测试验证链路,不要急着写业务断言:
cpp复制#include "CppUTest/TestHarness.h"
TEST_GROUP(Smoke) {
void setup() {
// 每个用例前都会走这里
}
void teardown() {
// 每个用例后都会走这里
}
};
TEST(Smoke, runner_is_alive) {
CHECK(true);
}
TEST_GROUP(Smoke) 定义一组用例的公共夹具,setup 和 teardown 分别在该组每个 TEST 前后执行。TEST(Smoke, runner_is_alive) 里的第一个参数是组名,第二个参数是用例名,失败时会按这两个名字定位。CHECK(true) 只是确认运行器能跑通,不证明业务正确。先跑通这个空测试,再往 TEST_SRC 里加真实用例,能把“编译链没配好”和“业务断言写错”分开,排查时少绕很多路。
2.3 宿主测试与交叉编译的边界
CppUTest 最适合跑在宿主机器上,不是所有测试都适合搬到目标板。宿主测试跑得快、失败信息完整、可以用标准库和文件系统;目标板测试受限于内存、异常开关、RTTI 和链接脚本,跑全量测试会变慢,还容易把测试框架的资源消耗误判成业务问题。我的做法是分层:纯计算、状态机、协议打包解包放宿主测试;真正碰寄存器、时钟、外设初始化的部分只保留少量冒烟用例,能在目标板上跑通即可。
| 测试位置 | 适合测什么 | 能发现的问题 | 局限 |
|---|---|---|---|
| 宿主机器 | 纯函数、状态机、协议编解码、Mock 边界 | 逻辑错误、边界漏判、内存泄漏 | 不碰真实硬件时序 |
| 目标板 | 外设初始化、启动流程、关键链路冒烟 | 链接脚本、堆栈、工具链差异 | 运行慢,失败信息不如宿主完整 |
| 台架联调 | 传感器读数、通信稳定性、功耗 | 硬件依赖和时序问题 | 不适合每次提交都跑 |
这张表的用法不是二选一,而是把失败成本压低。宿主测试失败,先改代码;目标板冒烟失败,先看工具链和硬件初始化;台架联调失败,再查时序和外部依赖。交叉编译时常见做法是检查异常和 RTTI 开关是否和 CppUTest 的宿主构建一致,测试入口不要进目标板构建,Mock 替身也不要链进量产固件。把这些边界写在构建文件里,比写在口头约定里可靠。
跑测试时先用组过滤缩小范围:
bash复制make test_runner
./test_runner -g SensorSample
make test_runner 按前面的 Makefile 链出测试运行器;./test_runner -g SensorSample 只跑 SensorSample 这一组用例。-g 后面跟组名,适合在改一个模块时先跑局部,再跑全量。先跑局部能快速确认新用例是否把旧状态带脏,全量跑则用来发现跨组件的链接期 Mock 和内存泄漏问题。两条命令分开执行,失败时更容易判断是单个用例的问题还是构建入口的问题。
注意:测试运行器只放在宿主构建里,目标板固件不要链接
CommandLineTestRunner,否则工具链差异会把问题拖到链接阶段才暴露。
3. 测试用例组织:把 C 函数拆成可断言的 4 个动作
3.1 TEST_GROUP 的 setup/teardown 该放什么
setup 和 teardown 不是“随便写点初始化”的地方。我的习惯是:setup 只放每个用例都需要的干净起点,比如重置被测模块的全局状态、把输出缓冲区清成已知值、初始化 Mock 期望;teardown 只放清理动作,比如释放用例里分配的内存、清掉 Mock 期望、关闭测试替身打开的句柄。断言尽量写在 TEST 里,不要塞进 teardown,否则一个清理失败会把“业务断言失败”和“夹具清理失败”混在一起,排查时很难判断先改哪边。
TEST_GROUP 的 setup 和 teardown 在每个 TEST 前后各跑一次,所以它们必须能重复执行。不要把“只初始化一次”的硬件打开动作放进去,否则第二个用例会重复初始化,现象可能是第一次跑过、第二次跑挂。确实只需要一次的初始化,放到测试运行器的入口或者单独的测试套件初始化里;每个用例都要用的轻量状态,才放 setup。这个边界划清楚,后面加用例不会互相污染。
一个空组可以这样写,先让夹具结构立住:
cpp复制#include "CppUTest/TestHarness.h"
TEST_GROUP(SensorSample) {
void setup() {
// 每个用例都从已知状态开始
sensor_reset();
}
void teardown() {
// 这里只做清理,不做业务断言
}
};
sensor_reset() 是被测模块提供的复位入口,用来把内部状态恢复到初始值;如果模块没有这个入口,可以在 setup 里重新构造被测对象,或者把全局变量显式赋成初始值。teardown 里不要写 CHECK 一类的断言,清理动作失败应该在清理代码里返回错误,再由具体用例判断。这个结构看起来简单,但它决定了后面用例能不能独立重复跑。
3.2 断言选择:CHECK_EQUAL、LONGS_EQUAL、STRCMP_EQUAL 与 FAIL
断言不是越短越好,选错宏会让失败信息变得没用。布尔条件用 CHECK,整数比较用 LONGS_EQUAL 或 CHECK_EQUAL,字符串比较用 STRCMP_EQUAL,走到不该到的分支用 FAIL。LONGS_EQUAL 的参数顺序是期望值在前、实际值在后,失败时会直接给出两个值;如果把顺序写反,失败信息还能看,但排查时容易把期望和实际读反。对 C 代码里的 int、long、枚举值,我优先用 LONGS_EQUAL,避免类型提升带来的隐式转换看不清。
| 断言 | 适用场景 | 注意点 |
|---|---|---|
CHECK(condition) |
布尔条件、指针非空 | 失败信息只有表达式,复杂条件先拆变量 |
CHECK_EQUAL(expected, actual) |
支持相等比较的对象或整数 | 类型要能比较,失败信息较直观 |
LONGS_EQUAL(expected, actual) |
整型、枚举、返回码 | 期望在前、实际在后 |
STRCMP_EQUAL(expected, actual) |
C 字符串 | 比较内容,不比较指针 |
FAIL("message") |
不该到达的分支 | 带上场景说明,方便定位 |
这张表不是让你背宏名,而是提醒断言要保留现场。比如一个函数返回错误码,用 LONGS_EQUAL(SENSOR_ERR_NULL, ret) 比 CHECK(ret != 0) 好,因为前者告诉你期望是空指针错误,后者只知道“非零”。字符串比较不要用 CHECK_EQUAL 去比 char*,那是在比指针地址,不是比内容;用 STRCMP_EQUAL 才能把字符串内容差异打出来。断言里也不要塞自增、函数调用这类有副作用的表达式,先存到局部变量再比较,失败时现场更干净。
3.3 一个传感器采集模块的测试骨架
下面用一个虚构的传感器采集模块做骨架,重点看用例怎么拆,不要照抄函数名。被测头文件通过 extern "C" 包进来,测试文件仍然按 C++ 编译:
cpp复制#include "CppUTest/TestHarness.h"
extern "C" {
#include "sensor_sample.h"
}
TEST_GROUP(SensorSample) {
void setup() {
sensor_reset();
}
void teardown() {
// 释放用例内分配的资源
}
};
TEST(SensorSample, converts_zero_raw_to_zero_milli_celsius) {
// 纯转换函数:输入 0,期望输出 0
LONGS_EQUAL(0, sensor_raw_to_milli_celsius(0));
}
TEST(SensorSample, rejects_null_output_buffer) {
// 输出缓冲区为空时,返回明确的错误码
LONGS_EQUAL(SENSOR_ERR_NULL, sensor_read(NULL, 0));
}
TEST(SensorSample, rejects_zero_length_read) {
uint8_t buffer[4] = {0};
LONGS_EQUAL(SENSOR_ERR_LENGTH, sensor_read(buffer, 0));
}
这段代码把被测函数拆成三类动作:纯转换、空指针边界、长度边界。sensor_raw_to_milli_celsius 不依赖硬件,适合放宿主测试;sensor_read 的输出缓冲区参数是典型 C 接口,空指针和零长度要分别断言,不能用一个 CHECK(ret != 0) 混过去。SENSOR_ERR_NULL 和 SENSOR_ERR_LENGTH 是模块对外暴露的错误码,测试里直接用它们,避免把魔数写进用例。buffer 初始化成 0 是为了让失败时的内存内容可预期,不是业务要求。
如果 sensor_read 内部依赖 I2C 读寄存器,先不要在这个用例里接真实硬件,下一步用 Mock 把 hal_i2c_read 替掉。测试骨架先保证接口边界清楚,再补依赖替身,顺序反过来容易写成“为了跑测试改业务代码”的循环。每个用例只验证一个行为,失败时能直接对应到一条边界,不要把转换、空指针、长度、硬件错误全塞进同一个 TEST。
4. 代码开发工具里的 Mock:把硬件依赖和内存泄漏一起按住
4.1 为什么 C 代码要用链接期替身而不是到处 ifdef
C 代码没有虚函数,给依赖做替身常见两种做法:在业务代码里到处写 #ifdef TEST,或者在测试构建里用链接期替身替换真实实现。前者短期快,长期会把测试分支带进量产代码;后者把替身放在测试目标里,业务代码不改。CppUTest 的 Mock 扩展适合后者:测试里写期望,替身实现里调用 mock().actualCall,真实硬件实现不参与测试链接。
链接期替身的关键是“测试目标链接的是替身,不是真实库”。比如业务代码调用 hal_i2c_read,测试构建里放一个同名函数,内部把参数转给 Mock;量产构建里链接真实 HAL。这样业务代码只依赖函数声明,不知道自己在测试还是量产。替身函数要用 extern "C" 保持 C 链接名,否则 C++ 编译器会把名字改编,链接时找不到业务代码里的调用点,现象就是“Mock 期望写了但一直没命中”。
4.2 CppUMock 的期望-调用-返回值三步
先写替身,把 C 函数调用转成 Mock 调用:
cpp复制#include "CppUTestExt/MockSupport.h"
extern "C" int hal_i2c_read(uint8_t addr, uint8_t reg, uint8_t* out) {
// 测试构建里的替身:把参数转给 Mock,并返回预设值
return mock().actualCall("hal_i2c_read")
.withIntParameter("addr", addr)
.withIntParameter("reg", reg)
.returnIntValue();
}
这个替身只存在于测试构建,actualCall("hal_i2c_read") 是 Mock 的调用点,withIntParameter 把地址和寄存器号带进期望匹配,returnIntValue() 从测试里预设的返回值取结果。真实实现里对 out 的写入被省略了,因为当前用例只验证“读温度时是否按正确地址和寄存器调用了一次”。如果业务逻辑依赖 out 的内容,替身里还要按测试预设写回缓冲区,不能只返回状态码。
测试侧写期望、触发业务函数、检查期望:
cpp复制#include "CppUTest/TestHarness.h"
#include "CppUTestExt/MockSupport.h"
extern "C" {
#include "temperature.h"
}
TEST_GROUP(Temperature) {
void teardown() {
// 每个用例后清掉未消费的期望,避免污染下一个用例
mock().clear();
}
};
TEST(Temperature, reads_register_once_and_returns_raw_value) {
mock().expectOneCall("hal_i2c_read")
.withIntParameter("addr", 0x48)
.withIntParameter("reg", 0x01)
.andReturnValue(25);
LONGS_EQUAL(25, read_temperature());
mock().checkExpectations();
}
expectOneCall 表示期望调用一次,withIntParameter 必须和替身里的参数名、参数值一致,andReturnValue(25) 是替身返回给业务代码的值。read_temperature() 是被测函数,它内部调用 hal_i2c_read;LONGS_EQUAL(25, ...) 验证业务函数把原始值透传出来;mock().checkExpectations() 确认期望被消费。teardown 里的 mock().clear() 很重要,某个用例失败后未消费的期望会留到下一个用例,现象是“单独跑能过、全量跑就挂”,排查时容易被误导。
4.3 内存泄漏检测:默认插件、失败现象与启用方式
CppUTest 默认带内存泄漏检测,测试运行结束时会报告未释放的 new 分配。C 代码里的 malloc/free 不一定被同一套机制覆盖,所以看到“测试通过但资源没释放”时,先确认分配走的是哪条路径。常见现象是:单个用例跑完报泄漏,但业务逻辑看起来没有 new;原因可能是测试夹具里构造了对象没析构,或者第三方库在第一次调用时分配了全局缓存。不要第一反应把检测关掉,先按组过滤,把范围缩到一个用例,再看 setup 和 teardown 里谁分配了资源。
启用方式不是重点,重点是失败后怎么定位。我的做法是先跑单组:
bash复制./test_runner -g Temperature
-g Temperature 只跑 Temperature 组,输出里会指出哪个用例结束后还有未释放分配。先把范围缩到单组,再缩到单个 TEST,然后检查 setup 里是否构造了对象、teardown 里是否按逆序释放。如果是第三方库的全局缓存,不要在每个用例里反复初始化;把初始化移到测试套件级,或者给这个库单独写一个受控的清理入口。确实需要关闭检测时,必须记录原因和范围,不能全局关掉,否则后面真正漏掉的业务分配也会被一起放过。
内存泄漏检测和 Mock 放在同一套测试里,最大的好处是失败现场完整:Mock 告诉你依赖调用对不对,泄漏检测告诉你资源管理有没有收尾。两者都失败时,先修 Mock 期望还是先修泄漏?我的顺序是先修 Mock,因为依赖调用不对时,业务路径可能根本没走到资源分配;等调用路径正确了,再看泄漏,才不会把“没执行到”误判成“没泄漏”。
注意:
mock().clear()放在teardown里,不要放在setup开头;失败用例留下的期望需要在下一个用例开始前就被清掉。
5. 避坑排查:CppUTest 在真实代码开发工具链里最容易翻车的 5 个点
5.1 测试一跑就报内存泄漏,但业务代码里没看到 new
现象是单个用例跑完就报未释放分配,业务函数里只看到 malloc 或根本没有显式分配。原因通常不在被测函数,而在测试夹具:setup 里构造了对象没析构,或者第三方库第一次调用时分配了全局缓存,测试结束时缓存还在。还有一种情况是 C 代码用 malloc 分配,CppUTest 默认的 new/delete 检测覆盖不到,误以为“没报就是没漏”。解决时先按组过滤,把范围缩到一个用例,再检查 setup 和 teardown 的配对;第三方库缓存不要在每个用例里反复初始化,移到测试套件级并写清楚清理入口;C 分配路径单独用计数器或封装函数验证,不要只依赖默认检测。关掉检测只能作为最后手段,而且要限定到具体组,不能全局关。
5.2 Mock 期望未满足,实际函数却明明被调用了
现象是 mock().checkExpectations() 失败,说期望的 hal_i2c_read 没被调用,但业务日志显示函数确实走了。原因常见于链接期替身没进测试目标,或者 C++ 编译把函数名改编了,业务代码调用的 C 符号和替身提供的符号对不上;也可能是链接顺序把真实 HAL 库排在替身前面,真实实现抢先被链进来。解决时先确认替身文件进了 TEST_SRC 或测试目标的源文件列表,再检查替身和业务声明是否都用 extern "C"。构建日志里看链接顺序,把替身目标文件放在真实库前面;如果还是不对,用符号表确认测试运行器里 hal_i2c_read 来自替身而不是真实库。不要靠改业务代码加 #ifdef 来绕,绕过去以后量产构建还会再踩一次。
5.3 宿主测试全绿,交叉编译目标板却链接失败
现象是宿主机器上 test_runner 跑得好好的,交叉编译目标板固件时出现未定义符号,常见的是标准库分配、异常或 RTTI 相关符号。原因是 CppUTest 的测试运行器按宿主环境构建,依赖宿主标准库和异常机制;目标板工具链可能关了异常和 RTTI,链接脚本也没有对应段。解决时把测试入口和 Mock 替身严格限制在宿主构建,目标板构建只链 src 里的实现;交叉编译前检查 CXXFLAGS 里异常和 RTTI 开关是否和测试构建混用,测试源文件不要进目标板源文件列表。目标板只保留少量冒烟用例,不要试图把全量 CppUTest 运行器搬上去。构建文件里把 test_runner 和 firmware 分成两个目标,比在命令行里手工删文件可靠。
5.4 teardown 清理顺序反了,下一个用例拿到悬空状态
现象是单个
