简介面向Qt图形界面开发者的实战项目包聚焦QGraphicsView与QGraphicsScene两大核心模块演示从自定义图元到鼠标交互的完整实现。功能上支持以鼠标为中心的滚轮缩放、图元拖拽、旋转操作并可通过render方法将场景渲染成图像完成截取链路完整。压缩包共82个文件包含14个cpp源文件与7个头文件以及编译生成的exe可执行程序、obj中间文件、调试日志和VS工程配置整体大小14.13MB文件覆盖源码阅读、编译验证到运行调试的完整环节适合对照源码理解工程组织。项目代码按图形项、场景、视图分层封装涉及QGraphicsItem继承重写、事件系统处理以及视图缩放策略等关键知识点功能模块可复用便于二次改造。已有662人学习或下载从工程搭建到交互实现均有据可循适合正在练习Qt二维图形编程的开发者参考借鉴。1. 手上一个 QtAppTest220104.zip先别解压先想清楚它该是什么拿到命名为 QtAppTest220104.zip 的压缩包时大多数人的第一反应是双击解压第二反应才轮到怀疑。这种命名在 Qt 团队里很常见QtAppTest 表示内容是某个 Qt 应用的测试相关产物220104 是归档日期zip 是跨平台分发格式。它背后通常对应三种场景一套待评审的测试工程源码、一批已经跑完的测试报告或者一个用于复现问题的最小工程。这篇文章不猜包里具体装了哪些文件——那份事实只有你本机解开后才能确认——而是把这一类包背后的 Qt 应用测试落地路径讲清楚拿到包后怎么拆、怎么搭最小测试框架、怎么把用例写厚、以及五个高频雷区为什么炸、怎么绕。适合接手这类包的人、想补 Qt Test 的人以及准备搭建回归体系的一线开发者。2. 拆包前先建模Qt 应用测试工程的标准骨架很多人拿到 QtAppTest220104.zip 的第一件事是双击解压我习惯先停一下想清楚这个包里大概率装了什么再动手。因为在 Qt Test 的世界里“测试工程”和“测试产物”的组织方式有规律可循。提前建模的好处是你可以少做几步无效操作也能更快判断这个包是不是你想要的。2.1 压缩包里最常出现的四类内容按文件名辨别用途在解压之前先看一下 zip 包内部的顶层条目是必要的。我一般用解压工具的“预览”功能或者命令行unzip -l扫一遍这能避免把纯报告包当成源码工程来读。这类以日期命名的测试包内容通常逃不出下面四类类别常见文件用途收到后怎么处理测试源码tst_xxx.cpp、.pro、CMakeLists.txt单测用例入口构建、运行、扩展被测代码src/ 下的 .cpp/.h 或编译好的静态库测试要链接的对象纳入构建路径资源与测试数据.qrc、testdata/.json、.csv用例运行时读取的输入确认已编译进资源构建脚本与说明build.sh、run_tests.bat、README.md记录环境依赖和构建顺序按说明复现但别轻信版本号一个很容易踩的坑是压缩包里混进了 build/ 目录里面是一堆编译中间文件和 CMakeCache.txt。这种包通常是开发者直接从工作目录打包的没做清理。收到这种包后构建前最好把 build 目录删掉或重命名否则 CMake 缓存了旧机器的绝对路径换个目录解压后配置阶段就会报错。我一般先看有没有顶层独立目录——有就cd进去再构建没有就直接在当前目录构建。2.2 构建体系二选一.pro 和 CMakeLists.txt 决定后续命令打开包里的工程配置文件基本能一眼看出这个测试工程走的是 qmake 还是 CMake。这两套构建体系的取舍很清楚qmake 简单直接三四行就能描述一个测试目标适合小工程和快速复现CMake 配置稍长但和 CI、IDE 的集成更顺适合作为团队长期维护的方案。qmake 的测试工程 .pro 文件常见写法是# 文件: tst_main.pro QT testlib widgets CONFIG testcase console CONFIG - app_bundle TARGET tst_main SOURCES tst_main.cpp # 如果被测代码在同目录的 src 下可以这么加 INCLUDEPATH ./src LIBS -L./build -lappcoreCONFIG testcase是关键它让 qmake 生成make check目标运行 make check 就能执行测试并汇总结果。console让输出走标准输出而不是 Qt 的日志系统这在 CI 抓日志时很有用。app_bundle只在 macOS 上有意义关掉是为了避免生成 .app 目录结构。CMake 版本的最小形态长这样# 文件: CMakeLists.txt cmake_minimum_required(VERSION 3.16) project(qtapptest LANGUAGES CXX) set(CMAKE_CXX_STANDARD 17) set(CMAKE_CXX_STANDARD_REQUIRED ON) set(CMAKE_AUTOMOC ON) # 关键自动处理 Q_OBJECT 的 moc 步骤 find_package(Qt6 REQUIRED COMPONENTS Test Widgets) enable_testing() add_executable(tst_main tst_main.cpp) target_link_libraries(tst_main PRIVATE Qt6::Test Qt6::Widgets) add_test(NAME tst_main COMMAND tst_main)enable_testing()必须写否则ctest不识别这个测试目标。CMAKE_AUTOMOC也必须开——测试类里几乎都带 Q_OBJECT 宏不开的话 moc 文件不会生成链接阶段会报一堆未定义引用。如果包里的 CMakeLists 用的还是qt5_add_resources这类旧函数说明工程可能是从 Qt 5 迁过来的构建前先确认本机 Qt 版本兼容。2.3 三个入口宏QTEST_MAIN 和它的两个兄弟Qt Test 提供三个入口宏作用完全不同选错会导致测试启动慢或者干脆起不来。它们的区别体现在“创建了什么应用对象”上宏创建的应用对象适用场景启动速度QTEST_APPLESS_MAIN什么都不创建纯函数逻辑测试最快QTEST_GUILESS_MAINQCoreApplication需要事件循环、信号槽较快QTEST_MAINQApplicationQWidget 界面测试最慢常见误用是把需要事件循环的测试写成QTEST_APPLESS_MAIN结果QSignalSpy永远等不到信号、QTimer不触发。反过来纯算法测试用QTEST_MAIN也没什么错就是白白多创建了一套 GUI 应用环境在 CI 无显示环境下还会触发平台插件加载。一个完整的测试类通常是这样的骨架// tst_main.cpp #include QtTest class TestMain : public QObject { Q_OBJECT private slots: void initTestCase(); void cleanupTestCase(); void alwaysPass(); }; void TestMain::initTestCase() { qDebug() start test; } void TestMain::cleanupTestCase() { qDebug() end test; } void TestMain::alwaysPass() { QVERIFY(true); } // 三选一 // QTEST_APPLESS_MAIN(TestMain) // 纯逻辑测试用这个 // QTEST_GUILESS_MAIN(TestMain) // 事件循环测试用这个 QTEST_MAIN(TestMain) // 界面测试用这个QTEST_MAIN(TestMain)会展开成包含 main() 函数的完整代码段所以测试 .cpp 里不能再写自己的 main()。initTestCase和cleanupTestCase在整个测试类运行前后各执行一次适合做公共环境的准备和清理。3. 解压验证从 zip 到第一条 PASS 输出建模做完了回到 QtAppTest220104.zip 本身。这个阶段的目标只有一个把它跑起来看到第一条 PASS。整个过程拆成三步先侦察包结构再按构建体系选命令最后读测试输出判断结果。这三步做完你对这个包就有了确切判断它能不能用、缺不缺东西、值不值得继续投入。3.1 不解压也能侦察unzip -l 先看结构解压是破坏性操作吗某种程度上是——一个包含几十个文件的 zip 解错目录后面清理起来很烦。所以我总是先列目录再决定怎么解开。unzip -l QtAppTest220104.zip | head -60unzip -l只列出压缩包内的文件清单不会真正落盘。head -60限制输出行数避免文件太多刷屏。这一步要重点看三件事第一顶层有没有独立目录决定解压后要不要cd第二有没有CMakeLists.txt或.pro文件决定走哪套构建命令第三有没有混入build/、.git/目录如果混入了先记下位置解压后单独清理。实际处理时常见两种情况包内文件全部散落在根目录这种直接在当前目录构建即可包内有一个顶层文件夹我一般unzip之后cd进这个文件夹再操作。顺便说一句如果你收到的包里连tst_*.cpp和构建配置文件都没有只有一堆 .log 和报告文件那它不是源码工程包而是打包好的测试产物没必要按下面的构建步骤走直接看报告文件内容就行。3.2 两种构建体系的最小跑通命令确定是源码工程包后构建命令取决于 2.2 里的探测结果。CMake 工程的完整流程mkdir -p ~/work/qttest cd ~/work/qttest unzip ~/Downloads/QtAppTest220104.zip cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPEDebug cmake --build build ctest --test-dir build --output-on-failure-S . -B build指定源码目录和构建目录分开这是 CMake 的推荐用法-G Ninja选 Ninja 生成器比默认的 Makefile 快不少--output-on-failure让 ctest 在用例失败时把完整日志打出来CI 里定位问题全靠这个参数。qmake 工程则是另一套命令qmake6 tst_main.pro make -j$(nproc) make checkmake check是CONFIG testcase生成的附加目标它会运行测试二进制并汇总结果。如果 .pro 没加 testcasemake check会报“没有这个目标”这时候直接运行生成的测试二进制也可以比如./tst_main。qmake6是 Qt 6 的 qmake 命令名某些发行版上仍然叫qmake运行时注意区分。构建过程如果报Q_OBJECT相关的链接错误多半是工程文件里漏了CONFIG ...或 CMake 的 AUTOMOC 没打开先检查工程配置不要急着改代码。3.3 读懂测试输出和退出码PASS、FAIL、SKIP 的含义跑通之后下一步就是读懂输出。Qt Test 的文本输出格式是固定的一段典型的全量输出./tst_main -v1-v1表示 verbose 级别 1会显示每个用例的完整名字和执行状态而不是只汇总结果。输出的大致样子是********* Start testing of TestMain ********* Config: Using QtTest library 6.4.2 PASS : TestMain::initTestCase() PASS : TestMain::alwaysPass() PASS : TestMain::cleanupTestCase() Totals: 3 passed, 0 failed, 0 skipped, 0 blacklisted ********* Finished testing of TestMain *********Totals 一行是判断成败的关键passed是通过的用例数failed是失败的skipped是被主动跳过的blacklisted是被临时排除的。用例失败时输出里会把实际值和期望值都打出来比如下面的形式FAIL! : TestMain::testSum() Compared values are not the same Actual (actualSum): 5 Expected (expectedSum): 6看到这种输出先别急着改代码。测试失败只说明“实际输出和预期不符”原因可能是被测代码有问题也可能是测试数据写错了。我是先确认期望值本身没错再去看被测代码——很多人在这里白调了半天 bug最后发现是测试数据抄错了。退出码在命令行里用echo $?查看。0 表示全部通过非 0 表示至少一个用例失败。这个机制让 Qt 测试可以无缝接入任何 CI 系统因为 CI 判断成功与否就是看退出码。4. 把用例写厚数据驱动、信号验证与界面模拟跑通一个空测试类只是起点。真正值得维护的 Qt 测试不是那种“打印一行日志然后 QVERIFY(true)”的占位用例而是覆盖了正常路径、边界值和异常输入的用例。这章讲三类我几乎天天在用的写法数据驱动把一函数测到吐、QSignalSpy 验证信号不靠肉眼、模拟输入覆盖交互路径。4.1 数据驱动测试_data 函数与 QFETCH 的配合实际项目里最简单的一类测试是“同一个函数喂不同输入断言不同输出”。如果每个输入都写一个测试函数代码会淹没在复制粘贴里。Qt Test 的数据驱动机制解决的就是这个问题一个测试函数配一个同名_data函数_data负责准备数据表测试函数从表里取数据执行。// 被测函数把逗号分隔的数字字符串求和 int sumCsv(const QString csv); void TestMain::sumCsv_data() { QTest::addColumnQString(csv); QTest::addColumnint(expected); QTest::newRow(empty string) QString() 0; QTest::newRow(single number) QString(42) 42; QTest::newRow(multiple numbers) QString(1,2,3) 6; QTest::newRow(trailing comma) QString(1,2,) 3; } void TestMain::sumCsv() { QFETCH(QString, csv); QFETCH(int, expected); QCOMPARE(sumCsv(csv), expected); }addColumn声明数据表的列名和类型newRow添加一行数据参数类型和顺序必须与addColumn完全对应。QFETCH把当前行的数据取到局部变量之后就是普通的断言写法。跑这个测试时每一行数据都算独立的用例输出里会用 newRow 的第一个参数标识PASS : TestMain::sumCsv(empty string)。哪个数据行挂了一目了然。这里有个细节_data函数的名字必须是“测试函数名 _data”少一个下划线都不生效Qt Test 不报错只是静默地只跑一次测试、数据为空。我在这上面吃过亏排查了很久才发现是命名拼错了。4.2 验证信号不靠肉眼QSignalSpy 的正确用法GUI 测试里最常见的需求是“执行一个操作然后等某个信号触发再检查信号带的参数”。新手喜欢用QTest::qWait(500)固定等半秒然后检查界面状态——这在高负载 CI 机器上非常不可靠。正确做法是用 QSignalSpy 挂在信号上等待并捕获参数。// 被测对象网络请求管理器 class NetworkManager : public QObject { Q_OBJECT public: void request(const QUrl url); signals: void finished(int statusCode); }; // 测试用例 void TestMain::requestFinished() { NetworkManager manager; QSignalSpy spy(manager, NetworkManager::finished); manager.request(QUrl(https://example.com/api)); // 关键用超时等待而不是固定等待 QTRY_VERIFY_WITH_TIMEOUT(spy.count() 1, 3000); QListQVariant arguments spy.takeFirst(); int status arguments.at(0).toInt(); QCOMPARE(status, 200); }QTRY_VERIFY_WITH_TIMEOUT(spy.count() 1, 3000)的含义是每 50ms 检查一次 spy 收到的信号数量直到满足条件或 3 秒超时。相比固定qWait它的优势是机器快就快跑、机器慢就多等一会用例不会因为调度抖动而随机失败。spy.takeFirst()取出第一次信号携带的参数列表按信号定义顺序排列这里finished带一个 int 状态码所以取arguments.at(0)。一个经常遇到的坑如果信号有重载比如finished(int)和finished(QString)直接写NetworkManager::finished会编译报错因为编译器不知道你要哪个。这时候要用qOverloadint(NetworkManager::finished)显式指定版本。4.3 模拟键盘和鼠标QTest::keyClick 与 mouseClick界面交互测试的下一层是模拟用户操作。Qt Test 提供了一套完整的输入模拟 API核心是两个函数QTest::keyClick和QTest::mouseClick。void TestMain::loginFlow() { QWidget window; auto *hostEdit new QLineEdit(window); hostEdit-setObjectName(hostEdit); auto *connectBtn new QPushButton(Connect, window); connectBtn-setObjectName(connectBtn); window.show(); // 模拟在 QLineEdit 里输入文本 QTest::keyClick(hostEdit, Qt::Key_H); QTest::keyClicks(hostEdit, ostName); // 模拟点击按钮 QTest::mouseClick(connectBtn, Qt::LeftButton); }keyClick是单击一个按键keyClicks是连续输入一串字符适合输入主机名这类文本。注意keyClick的第三个参数是修饰键比如Qt::ShiftModifier可以输入大写。mouseClick的默认点击位置是控件中心如果你的控件在边缘区域才有响应需要显式传入坐标点比如button-rect().center()。这种测试能在 CI 上跑的前提是测试类使用了QTEST_MAIN因为模拟输入依赖真实的 QApplication 事件循环。如果你用QTEST_GUILESS_MAIN创建测试窗口运行时大概率会崩溃或事件不生效。另外有个实际经验模拟输入之前控件必须show()并进入事件循环否则点击坐标计算会出问题。4.4 浮点比较和异常断言QCOMPARE 的边界之外QCOMPARE 好用但不是万能的。两个最容易出事的地方是浮点比较和异常断言。// 浮点比较不要直接 QCOMPARE double ratio calculateRatio(); QVERIFY(qAbs(ratio - 3.14) 1e-5); // 异常断言确定会抛异常的场景 QVERIFY_EXCEPTION_THROWN(parseBadInput(), ParseException);浮点数的二进制表示决定了3.14 3.14可能为 false直接 QCOMPARE 会导致用例随机失败。常见的替代是qFuzzyCompare但它对接近 0 的值不友好——两个都接近 0 的数可能被误判为相等。我个人的习惯是用qAbs(actual - expected) epsilonepsilon 根据你的数据精度定1e-5 或 1e-6 是常用量级。QVERIFY_EXCEPTION_THROWN(expression, ExceptionType)的语义是如果表达式没抛异常用例失败如果抛了但类型不匹配也失败只有抛出的异常类型完全匹配才通过。这个宏在写解析器、配置加载器这类健壮性测试时是刚需。5. Qt 测试避坑五个雷区与排查路径Qt 测试框架本身不难但把它放到真实的工程环境里各种环境问题和状态污染问题就冒出来了。这一章写我踩过、也帮别人排查过的五个高频雷区按“现象 → 原因 → 解决”的路径讲你可以直接当排查手册用。5.1 GUI 测试在服务器上跑不起来xcb 插件加载失败现象测试编译正常但在无图形界面的服务器或 CI 容器里运行时报错退出错误信息类似qt.qpa.plugin: Could not find the Qt platform plugin xcb in 原因QTEST_MAIN创建的 QApplication 需要加载平台插件默认是 xcb。服务器上没有 X 服务也没装 Qt 的 xcb 平台插件包应用启动阶段就崩了根本不是测试代码的问题。解决测试环境不开图形界面时指定 offscreen 平台插件QT_QPA_PLATFORMoffscreen ./tst_main -v1offscreen是 Qt 自带的无头平台插件不依赖 X 服务适用于绝大多数 QWidget 测试。如果你的测试里涉及QOpenGLWidgetoffscreen 可能不够那时就得用xvfb-run ./tst_main起一个虚拟 X 服务来跑。排查顺序别搞反先试 offscreen不行再上 xvfb。还有一个相关坑本机能跑、服务器不能跑先检查服务器的 Qt 安装是否完整别上来就改测试代码。5.2 用例互相污染单独跑全过一起跑翻车现象./tst_main -v1 testOne单独跑一个用例通过./tst_main跑全部用例testOne 失败。或者反过来单独跑失败全量跑反而通过。原因测试类里可能定义了静态成员或全局单例某个用例改了状态但没还原下一个用例读到了脏数据。更隐蔽的是如果测试操作了文件系统或环境变量比如某个用例创建了临时文件但清理不干净后面的用例一读就炸。解决每个用例需要独立状态时用init()和cleanup()这两个特殊槽它们会在每个用例执行前后各跑一次initTestCase和cleanupTestCase只跑一次不要在里面放会被用例修改的状态。另外检查代码里是否有 static 局部变量该改成成员变量的就改。class 内 private slots 的执行顺序就是声明顺序所以别依赖用例之间的执行顺序每个用例都应该是自包含的。5.3 中文路径下 qmake 工程构建失败现象工程放在D:\测试工程\qtapptest\或/home/用户/测试目录/这类含非 ASCII 字符的路径下qmake 配置成功make 到一半报错或者生成的测试二进制运行异常。原因qmake 生成的 Makefile 对非 ASCII 路径的处理不够稳健源文件路径含中文时编译器的依赖规则可能生成错误的文件路径即使编译过了运行时 Qt 查找插件和资源的路径也可能因为编码问题错位。解决最省心的办法是构建前把工程统一放到纯英文、无空格的路径下比如/home/ci/work/qtapptest。这个习惯无论对 qmake 还是 CMake 都有用——CMake 对中文路径支持比 qmake 好一些但底下的编译器比如 MSVC对源文件路径的编码判断依然可能出问题。如果你在 Windows 上还有一个连锁坑构建目录里会生成大量中间文件路径过长也会触发“文件路径超长”错误所以解压路径尽量短顶层目录不要套好几层。5.4 固定等待随机超时用超时断言代替 qWait现象测试用例里用QTest::qWait(500)等待某个异步操作完成本机跑十次过十次CI 上跑十次挂三回错误全是超时或状态不对。原因qWait(500)的逻辑是“固定等 500ms不管事情做没做完”。CI 机器负载高500ms 可能不够本机性能好200ms 就完成了。固定等待的本质是把性能差异变成随机失败源。解决把“固定等待”改成“轮询条件”。用QTRY_VERIFY或QTRY_VERIFY_WITH_TIMEOUT替代// 不要这么写 QTest::qWait(500); QVERIFY(spy.count() 1); // 改成这样 QTRY_VERIFY_WITH_TIMEOUT(spy.count() 1, 3000);QTRY_VERIFY会每 50ms 检查一次条件默认超时是 5 秒带_WITH_TIMEOUT的版本可以自定义超时。这样机器慢就多等机器快就早退用例稳定性立刻上一个台阶。如果你等的是某个信号也可以直接用QSignalSpy::wait(ms)——它的返回值就告诉你信号是否在超时前到达比手工轮询更简洁。5.5 资源文件在测试里读不到qrc 没编译进去现象测试代码里写QFile file(:/testdata/config.json)运行时报文件不存在或者file.open()返回 false。但同样的代码在被测应用里跑得好好的。原因qrc 资源文件没有被编译进测试二进制。qmake 工程里 .pro 缺了RESOURCES xxx.qrcCMake 工程里缺了qt_add_resources或qt5_add_resources调用。Qt 资源系统是按目标编译的测试是一个独立可执行文件必须单独把资源加进去。解决先在构建日志里搜有没有rcc相关输出——rcc 是 Qt 资源编译器如果它根本没出现在日志里就是工程配置问题。qmake 工程检查 .proRESOURCES testdata.qrcCMake 工程在 CMakeLists.txt 里加qt_add_resources(tst_main testdata PREFIX / FILES ${CMAKE_CURRENT_SOURCE_DIR}/testdata/config.json )注意资源路径的构建规则.qrc文件里声明的路径是相对文件系统路径但运行时访问的路径是:/前缀加 qrc 里的 alias。一个调试小技巧进QTest::qExec前用QFileInfo(:/)列一下根路径能快速确认资源到底有没有进二进制。6. 让 220104 这类日期包变成团队资产快照清单与一键回归命名里带日期的 zip本质是一个快照。快照的价值在“时间切片上的可复现状态”某个版本的应用、某一天的测试代码、当时的环境都冻结在里面。但这个价值有一个前提——拿到包的人能快速重建环境并跑起来。否则包解开了测试也跑了但没人能说清这个包当时是怎么构建的值不值得信任。我自己的习惯是在工程根目录放一个 buildinfo.txt每次打包测试 zip 时顺手把关键信息写进去。内容不复杂就四行Qt版本: 6.4.2 编译器: GCC 11.2 构建系统: CMake 3.24 验证结果: 32 passed, 0 failed这个文件的作用是让两个月后的自己或新接手的人不用考古。220104 这个日期只能告诉你打包时间buildinfo.txt 才能告诉你“这个包在什么环境下验证过”。配合快照的另一个习惯是一键回归脚本把它放在包的顶层目录#!/usr/bin/env bash # 一键回归解压 - 配置 - 构建 - 测试 - 打印结果 set -euo pipefail ZIP$1 WORK${ZIP%.zip}-work unzip -q $ZIP -d $WORK cmake -S $WORK -B $WORK/build -G Ninja -DCMAKE_BUILD_TYPEDebug cmake --build $WORK/build ctest --test-dir $WORK/build --output-on-failureset -euo pipefail的作用是任一命令失败立即退出、变量必须预定义、管道中途出错不会静默没有这三条构建中途挂了脚本可能还报“成功”。脚本虽然短但它把“解压到哪、怎么配置、怎么跑”固化成了命令任何人拿到包都能复现而不是靠猜。我在这上面吃过一次亏某次线上问题需要反查旧版本行为当时找不到半年前的测试包对应环境只能凭印象重搭浪费了大半天。从那以后每次交付测试快照都强制带 buildinfo.txt 和一键脚本这个习惯一直保持到现在。希望这篇笔记能让你在拿到下一个 QtAppTest 开头的压缩包时少走几步弯路希望帮到你。本文还有配套的精品资源点击获取
绿色便携版：离线专业术语查取引擎)
