TestCase QML 类型

表示一个单元测试用例。更多信息...

导入语句	import QtTest
继承	Item

属性

completed : bool
name : string
optional : bool
running : bool
when : bool
windowShown : bool

方法

cleanup()
cleanupTestCase()
compare(actual, expected, message)
object createTemporaryObject(Component component, object parent, object properties)
object createTemporaryQmlObject(string qml, object parent, string filePath)
expectFail(tag, message)
expectFailContinue(tag, message)
fail(message)
failOnWarning(message) (自 6.3)
QtObject findChild(parent, objectName)
fuzzyCompare(actual, expected, delta, message)
object grabImage(item)
ignoreWarning(message)
init()
initTestCase()
bool isPolishScheduled(object itemOrWindow)
keyClick(key, modifiers, delay)
keyPress(key, modifiers, delay)
keyRelease(key, modifiers, delay)
keySequence(keySequence)
mouseClick(item, x, y, button, modifiers, delay)
mouseDoubleClickSequence(item, x, y, button, modifiers, delay)
mouseDrag(item, x, y, dx, dy, button, modifiers, delay)
mouseMove(item, x, y, delay, buttons)
mousePress(item, x, y, button, modifiers, delay)
mouseRelease(item, x, y, button, modifiers, delay)
mouseWheel(item, x, y, xDelta, yDelta, button, modifiers, delay)
skip(message)
sleep(ms)
TouchEventSequence touchEvent(object item)
tryCompare(obj, property, expected, timeout, message)
tryVerify(function, timeout, message)
verify(condition, message)
wait(ms)
bool waitForPolish(object windowOrItem, int timeout) (since 6.5)
waitForRendering(item, timeout)
warn(message)

详细描述

QML 测试用例简介

测试用例是以 TestCase 类型内嵌 JavaScript 函数的形式编写的。

import QtQuick 2.0
import QtTest 1.2

TestCase {
    name: "MathTests"

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

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

以 "test_" 开头的函数被视为要执行的测试用例。使用 name 属性作为输出函数的前缀。

********* Start testing of MathTests *********
Config: Using QTest library 4.7.2, Qt 4.7.2
PASS   : MathTests::initTestCase()
FAIL!  : MathTests::test_fail() 2 + 2 = 5
   Actual (): 4
   Expected (): 5
   Loc: [/home/.../tst_math.qml(12)]
PASS   : MathTests::test_math()
PASS   : MathTests::cleanupTestCase()
Totals: 3 passed, 1 failed, 0 skipped
********* Finished testing of MathTests *********

由于 JavaScript 属性的行为方式，测试函数的发现顺序是不可预测的。为了帮助提高可预测性，测试框架将函数按照名称的升序排序。这在有两个测试必须按顺序运行的情况下很有帮助。

可以提供多个 TestCase 类型。当所有测试用例都完成时，测试程序将退出。如果测试用例不需要运行（因为先决条件失败），则可以将 optional 设置为 true。

数据驱动测试

可以使用以 "_data" 结尾的函数名将表数据提供给测试。或者，可以使用 init_data() 函数为 TestCase 类型中的所有测试函数提供默认测试数据。

import QtQuick 2.0
import QtTest 1.2

TestCase {
    name: "DataTests"

    function init_data() {
      return [
           {tag:"init_data_1", a:1, b:2, answer: 3},
           {tag:"init_data_2", a:2, b:4, answer: 6}
      ];
    }

    function test_table_data() {
        return [
            {tag: "2 + 2 = 4", a: 2, b: 2, answer: 4 },
            {tag: "2 + 6 = 8", a: 2, b: 6, answer: 8 },
        ]
    }

    function test_table(data) {
        //data comes from test_table_data
        compare(data.a + data.b, data.answer)
    }

    function test__default_table(data) {
        //data comes from init_data
        compare(data.a + data.b, data.answer)
    }
}

测试框架将迭代表中的所有行，并将每一行传递给测试函数。如所示，可以将列提取出来在测试中使用。tag 列是特殊的 - 当行失败时，测试框架将其打印出来，帮助读者识别一组其他通过的测试中的哪个测试失败了。

基准测试

以 "benchmark_" 开头的函数将在 Qt 基准测试框架中运行多次，并报告运行的平均时间值。这相当于在 QTestLib 的 C++ 版本中使用 QBENCHMARK 宏。

TestCase {
    id: top
    name: "CreateBenchmark"

    function benchmark_create_component() {
        let component = Qt.createComponent("item.qml")
        let obj = component.createObject(top)
        obj.destroy()
        component.destroy()
    }
}

RESULT : CreateBenchmark::benchmark_create_component:
     0.23 msecs per iteration (total: 60, iterations: 256)
PASS   : CreateBenchmark::benchmark_create_component()

要获得 QBENCHMARK_ONCE 宏的效果，请在测试函数名称前加上 "benchmark_once_"。

模拟键盘和鼠标事件

可以使用 keyPress()、keyRelease() 和 keyClick() 方法在单元测试中模拟键盘事件。事件被传递到当前聚焦的 QML 元素。您可以通过传递 Qt.Key 枚举值或拉丁1 字符（长度为一的字符串）。

Rectangle {
    width: 50; height: 50
    focus: true

    TestCase {
        name: "KeyClick"
        when: windowShown

        function test_key_click() {
            keyClick(Qt.Key_Left)
            keyClick("a")
            ...
        }
    }
}

可以使用 mousePress()、mouseRelease()、mouseClick()、mouseDoubleClickSequence() 和 mouseMove() 方法以类似的方式在测试中模拟鼠标事件。

如果您的测试创建了其他窗口，这些窗口可能会成为激活窗口，从而从 TestCase 的窗口中夺取焦点。为确保 TestCase 的窗口是激活的，请使用以下代码：

testCase.Window.window.requestActivate()
tryCompare(testCase.Window.window, "active", true)

注意：键盘和鼠标事件只能在主窗口显示后传递。在那时之前尝试传递事件将失败。使用 `when` 和 `windowShown` 属性来跟踪主窗口何时显示。

管理动态创建的测试对象

QML 测试的典型模式是在测试函数结束时动态创建一个项目并销毁它。

TestCase {
    id: testCase
    name: "MyTest"
    when: windowShown

    function test_click() {
        let item = Qt.createQmlObject("import QtQuick 2.0; Item {}", testCase);
        verify(item);

        // Test item...

        item.destroy();
    }
}

这种模式的问题是，如果测试函数中发生任何错误，将会跳过对 item.destroy() 的调用，导致项目在场景中悬挂，直到测试案例结束。这可能会导致干扰后续测试；例如，通过阻塞输入事件或产生与代码执行无关的调试输出，使得代码执行难以跟踪。

通过调用 createTemporaryQmlObject() 来代替，可以保证对象在测试函数结束时被销毁。

TestCase {
    id: testCase
    name: "MyTest"
    when: windowShown

    function test_click() {
        let item = createTemporaryQmlObject("import QtQuick 2.0; Item {}", testCase);
        verify(item);

        // Test item...

        // Don't need to worry about destroying "item" here.
    }
}

对于通过 `Component` 的 createObject() 函数创建的对象，可以使用 createTemporaryObject() 函数。

将测试与应用程序逻辑分离

在大多数情况下，您会想将测试与应用程序逻辑分离，将它们拆分到不同的项目中并链接它们。

例如，您可以有以下项目结构

.
| — CMakeLists.txt
| - main.qml
| — src
    | — main.cpp
| — MyModule
    | — MyButton.qml
    | — CMakeLists.txt
| — tests
    | — tst_testqml.qml
    | — main.cpp
    | — setup.cpp
    | — setup.h

现在，要测试 MyModule/MyButton.qml，在 MyModule/CMakeLists.txt 中为 MyModule 创建库并将其链接到您的测试项目，tests/UnitQMLTests/CMakeLists.txt。

MyModule/CMakeLists.txttests/CMakeLists.txttests/main.cpptests/setup.cpptests/setup.hCMakeLists.txt

    ...
qt_add_library(MyModule STATIC)

qt6_add_qml_module(MyModule
    URI MyModule
    QML_FILES MyButton.qml
)
    ...

    ...
add_executable(TestMyApplication main.cpp
               setup.cpp setup.h)

add_test(NAME TestMyApplication COMMAND TestMyApplication)

target_link_libraries(TestMyApplication
    PRIVATE
        Qt6::QuickTest
        Qt6::Qml
        MyModule
        MyModuleplugin
)
    ...

#include <QtQuickTest/quicktest.h>
#include "setup.h"

QUICK_TEST_MAIN_WITH_SETUP(TestQML, Setup)

#include "setup.h"

void Setup::applicationAvailable()
{
    // custom code that doesn't require QQmlEngine
}

void Setup::qmlEngineAvailable(QQmlEngine *engine)
{
    // add import paths
}

void Setup::cleanupTestCase()
{
    // custom code to clean up before destruction starts
}

#ifndef SETUP_H
#define SETUP_H

#include <QObject>
#include <QQmlEngine>

class Setup : public QObject
{
    Q_OBJECT
public:
    Setup() = default;

public slots:
    void applicationAvailable();
    void qmlEngineAvailable(QQmlEngine *engine);
    void cleanupTestCase();
};

#endif // SETUP_H

    ...
add_subdirectory(MyModule)
add_subdirectory(tests)

qt_add_executable(MyApplication
    src/main.cpp
)

qt_add_qml_module(MyApplication
    URI MyApplication
    QML_FILES main.qml
)
    ...

然后，在 tests/tst_testqml.qml 中，您可以使用 MyModule/MyButton.qml。

tests/tst_testqml.qmlMyModule/MyButton.qml

import QtQuick
import QtQuick.Controls

import QtTest
import MyModule

Item {
    width: 800
    height: 600

    MyButton {
        id: myButton
        anchors.centerIn: parent
    }

    TestCase {
        name: "MyButton"
        when: windowShown

        function test_clickToExpand() {
            const widthBeforeClick = myButton.width;
            mouseClick(myButton);
            const widthAfterClick = myButton.width;
            verify(widthBeforeClick < widthAfterClick);
        }
    }
}

import QtQuick
import QtQuick.Controls

Button {
    width: 50
    height: 50
    onClicked: width = 100
}

另请参阅SignalSpy 和 Qt Quick Test。

属性说明

completed : bool

测试案例执行完成后，此属性将设置为 true。测试案例仅执行一次。初始值是 false。

另请参阅running 和 when。

name : string

此属性定义测试案例的名称以供结果报告使用。默认值是空字符串。

TestCase {
    name: "ButtonTests"
    ...
}

optional : bool

测试应用中可以提供多种测试用例类型。当所有测试用例都完成后，应用程序将退出。如果不需要运行测试用例（因为前置条件失败），则可以将此属性设置为 true。默认值是 false。

TestCase {
    when: false
    optional: true
    function test_not_run() {
        verify(false)
    }
}

另请参阅when和completed。

running : bool

在测试用例运行期间，此属性将被设置为 true。初始值是 false，当测试用例完成后，值将再次变为 false。

另请参阅completed和when。

when : bool

当应用程序希望运行测试用例时，应将此属性设置为 true。默认值是 true。以下示例中，当用户按下鼠标按钮时运行测试

Rectangle {
    id: foo
    width: 640; height: 480
    color: "cyan"

    MouseArea {
        id: area
        anchors.fill: parent
    }

    property bool bar: true

    TestCase {
        name: "ItemTests"
        when: area.pressed
        id: test1

        function test_bar() {
            verify(bar)
        }
    }
}

在所有 TestCase 类型的测试用例被触发并运行后，测试应用程序将退出。可以使用optional属性来排除一个TestCase类型。

另请参阅optional和completed。

windowShown : bool

此属性将在QML查看窗口显示后设置为 true。通常测试用例在测试应用程序加载并显示窗口之前立即运行。如果测试用例涉及视觉类型和行为，则可能需要在窗口显示后延迟运行。

Button {
    id: button
    onClicked: text = "Clicked"
    TestCase {
        name: "ClickTest"
        when: windowShown
        function test_click() {
            button.clicked();
            compare(button.text, "Clicked");
        }
    }
}

方法文档

cleanup()

此函数在执行TestCase类型中的每个测试函数后调用。默认实现不执行任何操作。应用程序可以提供自己的实现，在每个测试函数后执行清理。

另请参阅init()和cleanupTestCase。

cleanupTestCase()

当TestCase类型中的所有其他测试函数完成后，将调用此函数。默认实现不执行任何操作。应用程序可以提供自己的实现以执行测试用例清理。

另请参阅initTestCase()和cleanup。

compare(actual, expected, message = "")

如果actual与expected不同，则失败当前测试用例，并显示可选的message。类似于C++中的QCOMPARE(actual, expected)。

另请参阅tryCompare()和fuzzyCompare。

object createTemporaryObject(Component component, object parent, object properties)

此函数从给定的component动态创建QML对象，带有指定的可选parent和properties。在cleanup()执行完毕后，将销毁返回的对象（如果尚未销毁），这意味着使用此函数创建的物体确保在每次测试之后被销毁，无论测试是否失败。

如果在创建对象时发生错误，将返回null。

此函数内部调用component.createObject()。

另请参阅管理动态创建的测试对象。

object createTemporaryQmlObject(string qml, object parent, string filePath)

此函数从给定的qml字符串动态创建QML对象，指定了parent。在cleanup()执行完毕后，将销毁返回的对象（如果尚未销毁），这意味着该函数创建的对象 guaranteeed 在每次测试后销毁，无论测试是否失败。

如果在创建对象时发生错误，将返回null。

如果指定了filePath，它将用于创建对象的错误报告。

此函数内部调用Qt.createQmlObject()。

另请参阅管理动态创建的测试对象。

expectFail(tag, message)

在数据驱动的测试中，标记与tag关联的行预期会失败。当发生失败时，显示message，终止测试，并将测试标记为通过。类似于C++中的QEXPECT_FAIL(tag, message, Abort)。

如果测试不是数据驱动的，那么tag必须设置为空字符串。

另请参阅expectFailContinue。

expectFailContinue(tag, message)

在数据驱动的测试中，标记与tag关联的行预期会失败。当发生失败时，显示message然后继续测试。类似于C++中的QEXPECT_FAIL(tag, message, Continue)。

如果测试不是数据驱动的，那么tag必须设置为空字符串。

另请参阅expectFail。

fail(message = "")

用可选的message失败当前测试用例。类似于C++中的QFAIL(message)。

[since 6.3] failOnWarning(message)

将测试日志中的每个匹配message的警告添加为测试失败。当添加失败时，测试函数将继续执行。

message可以是字符串，也可以是提供消息模式的正则表达式。在后一种情况下，对于遇到的每个警告，第一个匹配的图案将导致失败，其余的图案将被忽略。

在每次测试函数结束时清除所有模式。

例如，以下片段将在产生具有文本“发生了不良事情”的警告时失败测试

failOnWarning("Something bad happened")

以下片段将在遇到匹配给定模式的任何警告时失败测试

failOnWarning(/[0-9]+ bad things happened/)

要使触发给定警告的每个测试都失败，请在init()中传递适当的正则表达式

function init() {
    failOnWarning(/.?/)
}

注意：尽管是JavaScript RegExp对象，但不会将其解释为正则表达式，而是将模式传递到QRegularExpression。

注意：ignoreMessage()优先于此函数，因此任何匹配给定的ignoreMessage()和failOnWarning()模式的警告都将被忽略。

此方法是在Qt 6.3中引入的。

另请参阅QTest::failOnWarning()和warn。

QtObject findChild(parent, objectName)

返回具有objectName的parent的第一个子项，如果不存在此类项，则返回null。递归搜索可视和非可视子项，首先搜索可视子项。

compare(findChild(item, "childObject"), expectedChildObject);

fuzzyCompare(实际值, 预期值, delta, message = "")

如果实际值和预期值的差异大于delta，将失败当前测试用例，并显示可选的message。类似于C++中的qFuzzyCompare(actual, expected)，但需要一个必须的delta值。

此函数还可以用于颜色比较，如果实际值和预期值都可以转换为颜色值。如果RGBA通道值之间的任何差异大于delta，则测试失败。

另请参阅tryCompare() 和 compare。

object grabImage(item)

返回给定item的快照图像对象。

返回的图像对象具有以下属性

width 返回底层图像的宽度（自5.10起）
height 返回底层图像的高度（自5.10起）
size 返回底层图像的大小（自5.10起）

此外，返回的图像对象还具有以下方法

red(x, y) 返回位于x，y位置的像素的红色通道值
green(x, y) 返回位于x，y位置的像素的绿色通道值
blue(x, y) 返回位于x，y位置的像素的蓝色通道值
alpha(x, y) 返回位于x，y位置的像素的alpha通道值
pixel(x, y) 返回位于x，y位置的像素的颜色值

equals(image) 如果此图像与image相同，则返回true - 请参阅QImage::operator==（自5.6起）

例如

let image = grabImage(rect);
compare(image.red(10, 10), 255);
compare(image.pixel(20, 20), Qt.rgba(255, 0, 0, 255));

rect.width += 10;
let newImage = grabImage(rect);
verify(!newImage.equals(image));

save(path) 将图像保存到指定的<(machine_name>path)。如果无法保存图像，则抛出异常。（自5.10起）
这对于对失败的测试进行事后分析很有用，例如
```
let image = grabImage(rect);
try {
    compare(image.width, 100);
} catch (ex) {
    image.save("debug.png");
    throw ex;
}
```

ignoreWarning(message)

将message标记为忽略的警告消息。当它出现时，警告不会打印，测试通过。如果消息没有出现，则测试失败。类似于C++中的 QTest::ignoreMessage(QtWarningMsg, message)。

从Qt 5.12开始，message可以是字符串，或者是一个正则表达式，它提供要忽略的消息的模式。

例如，以下代码片段将忽略一个字符串警告消息

ignoreWarning("Something sort of bad happened")

以下代码片段将忽略一个匹配多个可能的警告消息的正则表达式

ignoreWarning(new RegExp("[0-9]+ bad things happened"))

注意：尽管是JavaScript RegExp对象，但不会将其解释为正则表达式，而是将模式传递到QRegularExpression。

另请参阅warn。

init()

此函数在每个执行在< a href="qml-qttest-testcase.html" translate="no">TestCase类型的测试函数之前被调用。默认实现不执行任何操作。应用程序可以提供自己的实现以在每个测试函数之前执行初始化。

另请参阅cleanup() 和 initTestCase。

initTestCase()

此函数在每个TestCase类型的其他所有测试函数之前被调用。默认实现不执行任何操作。应用程序可以提供自己的实现以执行测试用例初始化。

另请参阅cleanupTestCase() 和 init。

bool isPolishScheduled(object itemOrWindow)

如果itemOrWindow是 Item，则此函数返回updatePolish()自polish()以来的最后一次调用上未在它上调用，否则返回false。

自Qt 6.5以来，如果 itemOrWindow 是一个窗口，则此函数会在自上一次对那些项目调用 updatePolish() 后，如果它管理的任何项都没有调用 polish()，则返回 true，否则返回 false。

在QML中分配属性值时，由于分配而产生布局变更可能不会立即生效，而是可以推迟到项被抛光时。在这些情况下，您可以使用此函数确保在测试继续执行之前项已经抛光。例如：

verify(isPolishScheduled(item))
verify(waitForItemPolished(item))

如果没有上面对 isPolishScheduled() 的调用，那么对 waitForItemPolished() 的调用可能会看到没有抛光预定并立即通过，假设项目已经抛光。此函数使得未抛光的原因显而易见，并允许在这样的情况下测试早点失败。

另请参阅waitForPolish、QQuickItem::polish 和 QQuickItem::updatePolish。

keyClick(key, modifiers = Qt.NoModifier, delay = -1)

在当前焦点项目中模拟 key 的点击，可带有可选的 modifiers。如果 delay 大于0，则测试将等待 delay 毫秒。

该事件将被发送到 TestCase 窗口或者在多个窗口的情况下，发送到当前活动的窗口。更多详情见 QGuiApplication::focusWindow。

另请参阅keyPress 和 keyRelease。

keyPress(key, modifiers = Qt.NoModifier, delay = -1)

在当前焦点项目中模拟 key 的按键，可带有可选的 modifiers。如果 delay 大于0，则测试将等待 delay 毫秒。

该事件将被发送到 TestCase 窗口或者在多个窗口的情况下，发送到当前活动的窗口。更多详情见 QGuiApplication::focusWindow。

注意： 在某个时刻，应该使用 keyRelease() 释放按键。

另请参阅keyRelease 和 keyClick。

keyRelease(key, modifiers = Qt.NoModifier, delay = -1)

在当前焦点项目中模拟 key 的释放，可带有可选的 modifiers。如果 delay 大于0，则测试将等待 delay 毫秒。

该事件将被发送到 TestCase 窗口或者在多个窗口的情况下，发送到当前活动的窗口。更多详情见 QGuiApplication::focusWindow。

另请参阅keyPress 和 keyClick。

keySequence(keySequence)

模拟输入 keySequence。键序列可以设置为标准键盘快捷键之一，或者可以用包含最多四个按键序列的字符串来描述。

每个事件都应发送到 TestCase 窗口或者在多个窗口的情况下，发送到当前活动的窗口。更多详情见 QGuiApplication::focusWindow。

另请参阅keyPress、keyRelease、GNU Emacs 风格键序列和快捷键.sequence。

mouseClick(item, x = item.width / 2, y = item.height / 2, button = Qt.LeftButton, modifiers = Qt.NoModifier, delay = -1)

模拟使用可选的 修饰符 在项上点击鼠标按钮。点击位置由 x 和 y 定义。如果未定义 x 和 y，则位置将是项的中心。如果指定了延迟，则测试将在按下和释放按钮之前等待指定数量的毫秒数。