QTest单元测试工程实践：CMake接入、断言数据驱动与测试替身避坑

简介：这份演示工程围绕Qt的QTest框架展开，面向已具备C++与Qt基础、希望为普通应用程序及动态链接库补齐单元测试的开发者，重点解决类方法与DLL内部非导出类方法难以独立验证的问题。压缩包为zip格式，共13个文件，以5个cpp源文件、4个头文件和4个pro工程文件为主，源码、声明与构建配置相互配套，整体约6KB，体量轻便，便于快速查阅和二次改造。目前已有1467人学习，说明其示例思路具有一定参考价值。内容覆盖测试类组织、数据驱动测试、QVERIFY等断言使用，以及针对DLL非导出方法的友元测试类和测试专用导出接口两种策略，并保留普通应用与简单DLL两条示例线。读者可据此理解QTest测试用例的分层组织方式，对照工程结构搭建自己的测试骨架，并借鉴内部方法可测性与封装之间的取舍思路。

1. 从“测试跑绿了但Bug还在”说起：QTest Demo到底测什么

把 QTest 接进一个已有模块，最反直觉的体验是：测试全绿不代表代码没问题，只代表你问的问题它答对了。这份利用 QTest 进行单元测试的 Demo，重点不在教你写几个 QVERIFY，而是把测试目标怎么建、断言怎么选、信号怎么等、桩对象怎么插这四件事串成一条可复现的线。它适合已经能写 C++ 类、但测试长期靠手工点界面的开发者，也适合想把回归测试塞进构建流程的维护者。下面按实际拆包顺序讲，不铺概念，直接落到能编译、能跑、能定位失败的细节上。

2. QTest工程骨架：CMake目标、QTEST_MAIN与moc怎么接上

2.1 先拆目录：业务库、测试目标与构建脚本三层

拿到一份 QTest Demo，先别急着看断言写法，先看目录里谁依赖谁。常见做法是把被测逻辑编成静态库或对象库，测试可执行文件只负责链接这个库和 Qt Test 模块。这样测试目标不会把业务源码重复编译一遍，后面加第二个、第三个测试文件时也不会互相牵扯。业务库里不要出现QTest头文件，测试宏只留在tests目录，这是保持依赖方向干净的第一条线。

示例里的Calculator只是占位名，换成你工程里的解析器、状态机、协议拆包器都行。关键是让测试目标通过target_link_libraries拿到业务库，而不是用#include "../src/xxx.cpp"这种把实现直接拖进测试文件的做法。后者在单文件 Demo 里能跑，一旦被测类带Q_OBJECT或静态初始化，就会出现重复符号和 moc 找不到的问题。

2.2 CMake里把QTest接上：find_package、AUTOMOC与add_test

QTest 的构建接入不复杂，难在几个开关要同时打开：找 Qt Test 组件、开启 AUTOMOC、注册 ctest。下面这段 CMake 是常见骨架，find_package同时兼容 Qt6 和 Qt5 的写法，实际环境只命中一个主版本。add_test里的命令直接写测试目标名，CMake 会替换成生成后的可执行文件路径。

cmake_minimum_required(VERSION 3.16) project(qtest_demo LANGUAGES CXX) set(CMAKE_CXX_STANDARD 17) set(CMAKE_CXX_STANDARD_REQUIRED ON) set(CMAKE_AUTOMOC ON) # 测试类里的 Q_OBJECT 依赖 moc 处理 find_package(QT NAMES Qt6 Qt5 REQUIRED COMPONENTS Core Test) find_package(Qt${QT_VERSION_MAJOR} REQUIRED COMPONENTS Core Test) add_library(demo_core STATIC src/calculator.cpp ) target_include_directories(demo_core PUBLIC src) target_link_libraries(demo_core PUBLIC Qt${QT_VERSION_MAJOR}::Core) enable_testing() add_executable(tst_calculator tests/tst_calculator.cpp) target_link_libraries(tst_calculator PRIVATE demo_core Qt${QT_VERSION_MAJOR}::Test ) add_test(NAME tst_calculator COMMAND tst_calculator)

这段脚本里，CMAKE_AUTOMOC ON决定测试类里的Q_OBJECT能不能被扫描到；如果关掉它，编译期通常报undefined reference to vtable for TestCalculator，不是链接器坏了，是 moc 没生成。find_package里的Core和Test要同时出现，测试目标链接Qt::Test，业务库只需要Qt::Core。add_test的NAME是 ctest 里显示的名字，COMMAND是测试可执行文件；不写add_test时，ctest列表为空，但直接运行测试程序仍然能跑，这个差异很容易让人误判“测试已经接进构建”。

参数上，target_include_directories(demo_core PUBLIC src)让测试目标能直接#include "calculator.h"，不用写相对路径。target_link_libraries的PRIVATE表示测试可执行文件自己用 Qt Test，不向业务库传播测试依赖。若你的工程用 qmake，对应做法是把QT += testlib写进测试.pro，再通过CONFIG += testcase注册，但目录拆分和依赖方向不变。CMake 这边还有一个细节：测试目标链接业务库时，业务库如果是STATIC，测试程序会把它整块链进去；如果是SHARED，运行时动态库路径要能被找到，CI 上常见失败是ctest报找不到共享库，而不是断言失败。

2.3 测试类骨架：Q_OBJECT、private slots与QTEST_MAIN

测试类的骨架比业务类短，但每个关键字都有作用。Q_OBJECT让 moc 生成元对象信息，private slots里的槽函数会被 QTest 当成测试用例或生命周期钩子，QTEST_MAIN展开出一个main，里面调用QTest::qExec。下面这个测试类覆盖了初始化、数据驱动用例、普通断言和信号断言，类名和文件名要能对上测试目标。

#include <QtTest> #include "calculator.h" class TestCalculator : public QObject { Q_OBJECT private slots: void initTestCase(); // 整个测试类开始前执行一次 void add_handlesPositiveAndNegative_data(); // 数据驱动：准备表格 void add_handlesPositiveAndNegative(); // 数据驱动：按行执行 void divide_byZeroReturnsError(); // 普通用例 void emitsResultChanged(); // 信号用例 }; void TestCalculator::initTestCase() { qInfo() << "测试开始前只执行一次，适合准备只读资源"; } void TestCalculator::add_handlesPositiveAndNegative_data() { QTest::addColumn<int>("a"); QTest::addColumn<int>("b"); QTest::addColumn<int>("expected"); QTest::newRow("正数相加") << 2 << 3 << 5; QTest::newRow("正负相加") << 7 << -2 << 5; QTest::newRow("零值边界") << 0 << 0 << 0; } void TestCalculator::add_handlesPositiveAndNegative() { QFETCH(int, a); QFETCH(int, b); QFETCH(int, expected); Calculator calc; QCOMPARE(calc.add(a, b), expected); } void TestCalculator::divide_byZeroReturnsError() { Calculator calc; const auto result = calc.divide(10, 0); QVERIFY(!result.ok); QCOMPARE(result.error, QStringLiteral("division by zero")); } void TestCalculator::emitsResultChanged() { Calculator calc; QSignalSpy spy(&calc, &Calculator::resultChanged); calc.add(1, 2); QCOMPARE(spy.count(), 1); QCOMPARE(spy.takeFirst().at(0).toInt(), 3); } QTEST_MAIN(TestCalculator) #include "tst_calculator.moc"

QTEST_MAIN(TestCalculator)里的类名必须和继承QObject的测试类一致，宏会生成入口并执行所有private slots。文件末尾的#include "tst_calculator.moc"是单文件测试的常见写法，文件名要和源文件名对应；如果工程把测试类拆成头文件和实现文件，moc 的包含位置要跟着调整，否则会出现“类声明了但用例没被发现”。initTestCase只跑一次，适合准备只读数据；每个用例前的清理用init，每个用例后的清理用cleanup，不要把所有重置逻辑都塞进initTestCase，否则第二个用例会拿到第一个用例留下的状态。

参数上，QFETCH(int, a)的变量名必须与addColumn的列名完全一致，类型也要一致；列名写"expected"，取的时候写成expectedValue就会在运行期报找不到列。QSignalSpy spy(&calc, &Calculator::resultChanged)第二个参数是信号成员指针，信号参数会按顺序存进QVariantList，所以spy.takeFirst().at(0).toInt()取的是第一个信号参数。这个骨架跑通后，再谈断言选择才有意义。

3. 断言与数据驱动：QCOMPARE类型边界、_data()和QSignalSpy时序

3.1 断言不是越多越好：QVERIFY、QCOMPARE、QTRY_*的取舍

QVERIFY 只回答“真不真”，QCOMPARE 会打印实际值和期望值，定位失败时后者更省时间。我的习惯是：前置条件用 QVERIFY，比如指针非空、文件能打开；结果比对用 QCOMPARE，尤其是整数、字符串、枚举。浮点数不要直接 QCOMPARE，用qFuzzyCompare或QVERIFY(std::abs(a-b) < eps)，否则打印出来一堆小数位，人眼也判断不了是精度问题还是逻辑问题。

void TestParser::parseHeader() { Parser parser; const Header header = parser.parseHeader("A:1\r\nB:2\r\n"); QVERIFY(!header.fields.isEmpty()); // 前置条件：至少解析出字段 QCOMPARE(header.fields.value("A"), 1); // 结果比对：显示实际/期望 QCOMPARE(header.fields.value("B"), 2); }

这段代码里，QVERIFY失败会直接结束当前用例，后面的 QCOMPARE 不再执行；如果字段为空是预期内的分支，就不该用它当前置条件。QCOMPARE(header.fields.value("A"), 1)的两个参数类型要能比较，QMap<QString,int>::value返回int，和字面量1对得上；如果左边返回QString，右边写"1"，某些编译器下会退化成指针比较或直接编译失败。字符串比较统一用QStringLiteral("...")，枚举比较保证两边同类型，自定义结构体要么提供operator==，要么在失败时补一个QTest::toString特化，不然报错信息只有“实际值不等于期望值”，排查时像看黑匣子。

异步逻辑不要用QTest::qWait(500)硬等。固定睡眠在本地可能过，在 CI 上会因为机器慢而翻车；QTest 提供了QTRY_VERIFY、QTRY_COMPARE和带超时的QTRY_COMPARE_WITH_TIMEOUT，它们会反复处理事件循环直到条件成立或超时。超时值不是越长越好，一般按业务上限给 1 到 3 秒，失败时能快速暴露问题，而不是把测试拖成几分钟。

3.2 数据驱动：_data()槽与QTest::addColumn的类型对齐

数据驱动测试适合输入输出关系明确、边界值多的函数。_data()后缀不是装饰，QTest 会自动把xxx_data()和xxx()关联起来，每一行newRow都会单独执行一次xxx()，失败信息里带行名，定位比循环断言清楚。下面这段用三列描述输入、期望输出和是否应产生告警，行名写清楚场景，后面看日志时不用猜。

void TestNormalizer::normalize_data() { QTest::addColumn<QString>("input"); QTest::addColumn<QString>("expected"); QTest::addColumn<bool>("shouldWarn"); QTest::newRow("空串") << QStringLiteral("") << QStringLiteral("") << false; QTest::newRow("前后空格") << QStringLiteral(" 42 ") << QStringLiteral("42") << false; QTest::newRow("非法字符") << QStringLiteral("4x2") << QStringLiteral("4x2") << true; } void TestNormalizer::normalize() { QFETCH(QString, input); QFETCH(QString, expected); QFETCH(bool, shouldWarn); QString warning; const QString actual = normalizeInput(input, &warning); QCOMPARE(actual, expected); QCOMPARE(!warning.isEmpty(), shouldWarn); }

addColumn<QString>和QFETCH(QString, input)必须成对，列名大小写也要一致。newRow的第一个参数是行名，重复行名不会阻止编译，但失败输出会混淆，所以行名要带场景，比如“空串”“前后空格”“非法字符”。如果列类型是自定义结构体，先Q_DECLARE_METATYPE，再让类型支持拷贝和比较；否则QTest::addColumn那一步就会编译失败。数据驱动不是把所有用例都塞进一张大表，表太大的时候拆成多个_data()，每个表只覆盖一类边界，维护成本更低。

3.3 信号与异步：QSignalSpy::wait、QTRY_COMPARE_WITH_TIMEOUT

信号测试最容易翻车的地方是“信号什么时候发”。同步发射的信号，构造 QSignalSpy 后调用被测函数，再查count()就够了；异步发射的信号，要等事件循环跑起来。QSignalSpy::wait(ms)会阻塞等待指定信号，返回 false 表示超时；QTRY_COMPARE_WITH_TIMEOUT则适合轮询某个状态，直到它等于期望值。

void TestWorker::finishedOnce() { Worker worker; QSignalSpy spy(&worker, &Worker::finished); QTimer::singleShot(0, &worker, &Worker::start); QVERIFY(spy.wait(2000)); // 等信号，不在测试里写固定 sleep QCOMPARE(spy.count(), 1); // 只允许完成一次 } void TestWorker::stateBecomesReady() { Worker worker; worker.startAsync(); QTRY_COMPARE_WITH_TIMEOUT(worker.state(), Worker::Ready, 2000); }

spy.wait(2000)的参数是毫秒，超时后返回 false，后面的QCOMPARE不会执行；如果信号是同步发射的，wait可能直接返回 false，因为信号已经过去了，所以同步场景不要硬套wait。QTRY_COMPARE_WITH_TIMEOUT的第三个参数同样是毫秒，它会在超时前反复处理事件，适合状态机、网络回调、定时器触发这类没有单一信号可等的场景。测试里出现QTest::qWait(1000)时，先问自己：我等的到底是哪个信号或哪个状态？能落到信号就用 QSignalSpy，能落到状态就用 QTRY，固定睡眠只留给你确实无法观察的外部进程。

4. 测试替身落地：接口隔离、手写Fake与QSignalSpy的分工

4.1 先让类可测：构造函数注入与接口最小化

很多类不是“难测”，而是“没法在测试里构造”。构造函数里直接 new 数据库连接、直接读系统时间、直接发网络请求，测试就只能连真实环境，跑一次慢一次，失败还不可复现。常见做法是把外部依赖抽成一个最小接口，通过构造函数传入；业务类只依赖接口，不依赖具体实现。这样测试里可以塞一个手写 Fake，生产代码里塞真实实现，依赖方向从“业务类自己造依赖”变成“调用方注入依赖”。

struct Clock { virtual ~Clock() = default; virtual qint64 nowMs() const = 0; }; class ExpiryService { public: explicit ExpiryService(Clock* clock) : m_clock(clock) {} bool isExpired(qint64 deadlineMs) const { return m_clock->nowMs() > deadlineMs; } private: Clock* m_clock; };

Clock只暴露nowMs()，不把整个时间库搬进来；ExpiryService的构造函数只收一个Clock*，不自己在内部取当前时间。参数上，deadlineMs用毫秒时间戳，测试里可以精确控制“刚好等于截止时间”和“超过 1 毫秒”两个边界。接口越小，Fake 越好写；如果接口里有十个方法，测试类就得实现十个空函数，最后 Fake 本身变成维护负担。

4.2 手写Fake的边界：只模拟你控制不了的东西

Qt 工程里没有强制绑定某个 Mock 框架，手写 Fake 是最常见的落地方式。Fake 不是“假数据生成器”，它要能按测试需要推进状态，比如时钟向前拨、队列里塞一条消息。下面这个 FakeClock 只做一件事：保存当前毫秒数，并允许测试推进时间。

class FakeClock : public Clock { public: explicit FakeClock(qint64 now) : m_now(now) {} qint64 nowMs() const override { return m_now; } void advance(qint64 delta) { m_now += delta; } private: qint64 m_now; }; void TestExpiryService::expiresAfterDeadline() { FakeClock clock(1000); ExpiryService service(&clock); QVERIFY(!service.isExpired(1200)); // 1000 未超过 1200 clock.advance(201); QVERIFY(service.isExpired(1200)); // 1201 超过 1200 }

FakeClock(1000)的初始时间由测试指定，advance(201)把时间推到 1201，正好跨过截止时间。这里没有真实等待，也没有qWait，测试执行时间是毫秒级。Fake 的边界要守住：只模拟业务真正依赖的行为，不要在 Fake 里复刻真实实现的全部逻辑；如果 Fake 越写越像生产代码，说明接口切得不对，应该回到 4.1 重新拆依赖。

4.3 Fake、Stub、Spy、Mock怎么选：一张表落地

QSignalSpy 是 Qt 测试里最顺手的 Spy，不需要额外依赖，能记录信号次数和参数。Mock 不是越多越好，验证“某方法被调用了几次”往往让测试和实现绑死，重构时一改就红。我的取舍是：能通过返回值或最终状态判断的，不用 Mock；需要观察信号和回调的，用 QSignalSpy；需要控制时间的，用 Fake；只有跨模块协议、必须验证调用顺序时，才考虑 Mock。

5. QTest避坑排查：五个从“用例消失”到“进程闪退”的翻车点

5.1 构建能过但 ctest 列表为空：测试目标没注册

现象是测试可执行文件编译成功，手动运行也能跑，但ctest显示没有测试。原因通常是 CMake 里只写了add_executable，漏了enable_testing()或add_test。先跑ctest -N看列表，再检查顶层 CMakeLists 是否在add_subdirectory(tests)之前调用了enable_testing()。解决方式是把enable_testing()放在顶层，add_test(NAME tst_calculator COMMAND tst_calculator)放在测试目标定义之后，然后用ctest --output-on-failure跑一遍。

ctest -N ctest --output-on-failure ./tst_calculator -functions

ctest -N只列不跑，适合确认注册是否生效；--output-on-failure让失败用例的输出直接打到终端；-functions列出测试类里被识别到的槽函数，用例“消失”时先看这个列表，比反复改断言快。

5.2 QCOMPARE 类型不匹配：编译失败或输出看不懂

现象是 QCOMPARE 那一行编译不过，或者失败时只打印两个看不出差别的值。原因常见于QString和const char*混比、枚举和整数混比、自定义结构体没有operator==。解决方式是统一类型：字符串用QStringLiteral，枚举两边保持同类型，自定义类型先提供比较运算符；浮点数改用qFuzzyCompare或带容差的 QVERIFY。不要用强制转换把类型问题压过去，转换后失败信息会更难读。

5.3 单例与全局状态污染：单独跑过，全量跑挂

现象是某个用例单独运行通过，和别的用例一起跑就失败。原因多半是单例、静态缓存、全局配置没有在每个用例后重置。initTestCase只执行一次，不能承担“每个用例都清理”的职责；要用cleanup()或init()把状态恢复到基线。更彻底的做法是让测试目标一次只跑一个测试类，或者用QTest::qExec分别执行多个测试对象，减少共享状态的影响。

5.4 信号测试的时序坑：processEvents 与 wait 用错

现象是本地跑绿，CI 上偶发失败，日志里信号次数是 0。原因是用固定qWait等异步信号，机器一慢就超时；或者信号已经同步发射，却又调用spy.wait()等一个已经过去的信号。解决方式是先判断信号是同步还是异步：同步信号直接查count()，异步信号用spy.wait(ms)或QTRY_COMPARE_WITH_TIMEOUT。测试里尽量不写“等 500 毫秒”，而是写“等到某个条件成立，最多 2 秒”。

5.5 崩溃没有失败用例：进程直接退出

现象是测试进程闪退，ctest 只报一个非零退出码，看不到具体是哪个用例挂了。原因可能是空指针、数组越界、断言里解引用了无效对象，或者异常跨出了测试槽。解决方式先用-functions缩小范围，再用-v2看最后执行的用例；编译时打开地址检查工具，把崩溃点定位到行。测试里对可能为空的返回值先用QVERIFY拦住，不要让解引用发生在断言之前，否则 QTest 还没来得及记录失败，进程已经没了。

./tst_calculator -v2 -o result.txt,txt ./tst_calculator divide_byZeroReturnsError

-v2输出每个用例的执行细节，-o result.txt,txt把结果写到文件，单个用例名可以直接作为参数只跑那一个。先定位再修，比在几十个用例里猜快得多。

6. 进阶跑法：测试套件、-v2日志与一次通过前的检查表

测试文件多起来后，不要把所有用例塞进一个可执行文件。常见做法是按模块拆成多个测试目标，每个目标链接自己的业务库，ctest 里用-R按名字筛，CI 上并行跑。日志方面，本地排查用-v2，CI 上保留-o输出文件，失败时直接看文件里的实际值、期望值和行号。QTest 的参数不花哨，但组合起来能省很多来回。

还有一个容易忽略的技巧：给测试目标加编译选项，把警告当错误处理，尤其是未使用变量和类型转换警告。QTest 的QCOMPARE模板在类型不匹配时给出的编译信息很长，提前把警告暴露出来，比在 CI 日志里翻半天强。需要对照源码时，先看tests目录里的测试类，再回到CMakeLists.txt对目标名和链接项，顺序反过来容易在构建脚本里迷路。

从那以后我每次新增一个 QTest 用例，都会先跑一遍tst_xxx -functions和ctest --output-on-failure，确认用例真的被识别、失败信息真的能读，再动业务代码。希望帮到你。

本文还有配套的精品资源，点击获取