Qt Quick Test

导言

Qt Quick Test是 QML 应用程序的单元测试框架。测试用例以TestCase 类型中的 JavaScript 函数形式编写：

import QtQuick 2.3
import QtTest 1.0

TestCase {
    name: "MathTests"

    function test_math() {
        compare(2 + 2, 4, "2 + 2 = 4")
    }

    function test_fail() {
        compare(2 + 2, 5, "2 + 2 = 5")
    }
}

名称以test_ 开头的函数被视为要执行的测试用例。有关编写测试用例的更多信息，请参阅TestCase 和SignalSpy 类型的文档。

注意： Qt Quick Test 模块不保证二进制兼容。这意味着使用Qt Quick Test 的应用程序只能保证与开发时所使用的 Qt 版本兼容。不过，源代码兼容性是有保证的。

使用模块

QML API

Qt Quick Test 中的 QML 类型可通过QtTest 导入使用。要使用这些类型，请在 .qml 文件中添加以下导入语句：

import QtTest

C++ API

使用C++ API 需要直接或通过其他依赖关系与模块库链接。一些编译工具对此提供了专门支持，包括CMake和qmake。

使用 CMake 构建

使用find_package() 命令查找 Qt6 软件包中需要的模块组件：

find_package(Qt6 REQUIRED COMPONENTS QuickTest)
target_link_libraries(mytarget PRIVATE Qt6::QuickTest)

另请参阅使用 CMake 构建概述。

使用 qmake 构建

有两种方法可以链接到相应的 C++ 库。如果您的测试项目使用 QMLTestCase ，您的项目文件中应该已经有了下面一行：

CONFIG += qmltestcase

这将使测试链接到 C++ QtQuickTest 库。

如果您有一个纯 C++ 测试项目，您可以在项目文件中添加以下一行：

QT += qmltest

运行测试

测试用例由 C++ 线束启动，线束由以下代码组成：

#include <QtQuickTest>
QUICK_TEST_MAIN(example)

其中 "example "是唯一标识这组测试的标识符。

CMake qmake

配置 CMakeLists.txt 文件，并使用您喜欢的生成器构建项目。

cmake_minimum_required(VERSION 3.2)

project(tst_example LANGUAGES CXX)

enable_testing()

find_package(Qt6 REQUIRED COMPONENTS QuickTest Qml)

#[[The test harness scans the specified source directory recursively
for "tst_*.qml" files. By default, it looks in the current directory,
which is usually where the executable is. This command makes it look
in the project's source directory instead.]]
add_definitions(-DQUICK_TEST_SOURCE_DIR="${CMAKE_CURRENT_SOURCE_DIR}")

qt_standard_project_setup(REQUIRES 6.6)

add_executable(tst_example tst_example.cpp)

add_test(NAME tst_example COMMAND tst_example)

target_link_libraries(tst_example
    PRIVATE
    Qt6::QuickTest
    Qt6::Qml
)

在项目文件中添加CONFIG += qmltestcase ：

TEMPLATE = app
TARGET = tst_example
CONFIG += warn_on qmltestcase
SOURCES += tst_example.cpp

如果在 .pro 文件中指定了IMPORTPATH ，在使用 "make check "运行测试时，添加到IMPORTPATH 的每个导入路径都将作为命令行参数传递：

IMPORTPATH += $$PWD/../imports/my_module1 $$PWD/../imports/my_module2

测试工具会递归扫描指定的源代码目录，查找 "tst_*.qml "文件。如果未定义QUICK_TEST_SOURCE_DIR ，则运行线束时将扫描当前目录。测试使用的辅助 QML 组件可能会出现其他 *.qml 文件。

运行时可设置-input 命令行选项，以便从不同目录运行测试用例。在编译目录名指向主机的目标设备上运行测试时，可能需要这样做。例如

tst_example -input /mnt/SDCard/qmltests

也可以使用-input 选项运行单个文件。例如

tst_example -input data/test.qml

tst_example -input <full_path>/test.qml

注意： 例如，影子编译需要指定 qml 测试文件的完整路径。

如果您的测试用例需要 QML 导入，可以将其作为-import 选项添加到测试程序命令行中。

-functions 命令行选项将返回当前测试功能的列表。使用测试功能的名称作为参数，可以运行单个测试功能。例如

tst_example Test_Name::function1

-help 命令行选项将返回所有可用选项。

tst_example -help

注意： 运行Qt Quick 测试用例总是会在屏幕上显示一个窗口，即使测试代码不涉及任何快速用户界面。为避免出现这种情况，请使用-platform offscreen 运行测试可执行文件。

在 QML 测试前执行 C++

要在任何 QML 测试运行前执行 C++ 代码，可使用QUICK_TEST_MAIN_WITH_SETUP 宏。这对设置 QML 引擎的上下文属性等非常有用。

该宏与QUICK_TEST_MAIN 相同，只是多了一个类型参数。测试框架将调用具有以下名称的插槽和可调用函数：

名称名称自

void applicationAvailable() 在 QApplication 对象实例化后立即调用。使用该函数执行不需要QQmlEngine 实例的设置。 Qt 5.12

名称	名称	自
`void applicationAvailable()`	在 QApplication 对象实例化后立即调用。使用该函数执行不需要QQmlEngine 实例的设置。	Qt 5.12
`void qmlEngineAvailable(QQmlEngine *)`	当 QML 引擎可用时调用。此时，任何import paths 、plugin paths 和extra file selectors 都已在引擎上设置好。每个 QML 测试文件调用一次该函数，因此任何参数对该测试都是唯一的。例如，这意味着每个 QML 测试文件都有自己的 QML 引擎。此函数可用于注册 QML 类型和add import paths 等。	Qt 5.11
`void cleanupTestCase()`	测试执行结束后立即调用。使用此函数可在一切开始销毁前进行清理。	Qt 5.12

void qmlEngineAvailable(QQmlEngine *)

当 QML 引擎可用时调用。此时，任何import paths 、plugin paths 和extra file selectors 都已在引擎上设置好。

每个 QML 测试文件调用一次该函数，因此任何参数对该测试都是唯一的。例如，这意味着每个 QML 测试文件都有自己的 QML 引擎。

此函数可用于注册 QML 类型和add import paths 等。

Qt 5.11

void cleanupTestCase() 测试执行结束后立即调用。使用此函数可在一切开始销毁前进行清理。 Qt 5.12

下面的示例演示了如何使用宏在 QML 引擎上设置上下文属性：

// src_qmltest_qquicktest.cpp
#include <QtQuickTest>
#include <QQmlEngine>
#include <QQmlContext>
#include <QGuiApplication>

class Setup : public QObject
{
    Q_OBJECT

public:
    Setup() {}

public slots:
    void applicationAvailable()
    {
        // Initialization that only requires the QGuiApplication object to be available
    }

    void qmlEngineAvailable(QQmlEngine *engine)
    {
        // Initialization requiring the QQmlEngine to be constructed
        engine->rootContext()->setContextProperty("myContextProperty", QVariant(true));
    }

    void cleanupTestCase()
    {
        // Implement custom resource cleanup
    }
};

QUICK_TEST_MAIN_WITH_SETUP(mytest, Setup)

#include "src_qmltest_qquicktest.moc"

.moc include 基于.cpp 文件的文件名。例如，在上面的例子中，.cpp 文件的名称是src_qmltest_qquicktest.cpp 。如果文件名是MyTest.cpp ，include 就会是：

#include "MyTest.moc"

参考

许可证

Qt Quick Tests 可通过Qt Company 的商业许可获得。此外，它还可以在自由软件许可证下使用。自 Qt 5.4 起，这些自由软件许可证为GNU Lesser General Public License 第 3 版或GNU General Public License 第 2 版。更多详情，请参阅Qt 许可。

© 2025 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.