Qt Quick Test

简介

Qt Quick Test 是一个用于 QML 应用程序的单元测试框架。测试用例以 JavaScript 函数的形式编写，并封装在TestCase 类型中：

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 测试用例时，屏幕上总会显示一个窗口，即使测试代码中未涉及任何Quick UI也是如此。若要避免此情况，请使用-platform offscreen 运行测试可执行文件。

在 QML 测试之前执行 C++ 代码

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

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

名称用途 Since

void applicationAvailable() 在 QApplication 对象实例化后立即调用。使用此函数执行无需QQmlEngine 实例的初始化操作。 Qt 5.12

名称	用途	Since
`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 的包含路径基于.cpp 文件的文件名。例如，在上面的示例中，.cpp 文件名为src_qmltest_qquicktest.cpp 。如果文件名为MyTest.cpp ，则包含路径应为：

#include "MyTest.moc"

参考

许可证

Qt Quick Qt Test 由The Qt Company 提供商业许可。此外，它还提供自由软件许可。自 Qt 5.4 起，这些自由软件许可包括GNU 较少通用公共许可证第 3 版或GNU 通用公共许可证第 2 版。更多详细信息请参阅Qt 许可。

© 2026 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.