内容

• 特性
• 方法
• 详细描述
• QML 测试案例介绍
• 数据驱动测试
• 基准测试
• 模拟键盘和鼠标事件
• 管理动态创建的测试对象

TestCase QML 类型

表示单元测试案例 更多...

import 语句：	import QtTest 1.1
Since:	Qt 4.8
继承：	Item

• 所有成员列表，包括继承成员

特性

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

方法

• cleanup ()
• cleanupTestCase ()
• compare ( actual , expected , message )
• 对象 createTemporaryObject (Component component , object parent , object properties )
• 对象 createTemporaryQmlObject (string qml , object parent , string filePath )
• expectFail ( tag , message )
• expectFailContinue ( tag , message )
• fail ( message )
• QtObject findChild ( parent , objectName )
• fuzzyCompare ( actual , expected , delta , message )
• 对象 grabImage ( item )
• ignoreWarning ( message )
• init ()
• initTestCase ()
• keyClick ( key , modifiers , delay )
• keyPress ( key , modifiers , delay )
• keyRelease ( key , modifiers , delay )
• mouseClick ( item , x , y , button , modifiers , delay )
• mouseDoubleClick ( 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 )
• 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 ( 条件 , message )
• wait ( ms )
• waitForRendering ( item , timeout )
• warn ( message )

详细描述

QML 测试案例介绍

Test cases are written as JavaScript functions within a TestCase 类型：

import QtQuick 2.0
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")
    }
}
					

Functions whose names start with "test_" are treated as test cases to be executed. The name property is used to prefix the functions in the output:

********* 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 *********
					

Because of the way JavaScript properties work, the order in which the test functions are found is unpredictable. To assist with predictability, the test framework will sort the functions on ascending order of name. This can help when there are two tests that must be run in order.

多 TestCase types can be supplied. The test program will exit once they have all completed. If a test case doesn't need to run (because a precondition has failed), then optional can be set to true.

数据驱动测试

Table data can be provided to a test using a function name that ends with " _data ". Alternatively, the init_data() function can be used to provide default test data for all test functions in a TestCase 类型：

import QtQuick 2.0
import QtTest 1.1
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)
    }
}
					

The test framework will iterate over all of the rows in the table and pass each row to the test function. As shown, the columns can be extracted for use in the test. The tag column is special - it is printed by the test framework when a row fails, to help the reader identify which case failed amongst a set of otherwise passing tests.

基准测试

Functions whose names start with "benchmark_" will be run multiple times with the Qt benchmark framework, with an average timing value reported for the runs. This is equivalent to using the QBENCHMARK macro in the C++ version of QTestLib .

TestCase {
    id: top
    name: "CreateBenchmark"
    function benchmark_create_component() {
        var component = Qt.createComponent("item.qml")
        var 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()
					

To get the effect of the QBENCHMARK_ONCE macro, prefix the test function name with "benchmark_once_".

模拟键盘和鼠标事件

The keyPress() , keyRelease() ，和 keyClick() methods can be used to simulate keyboard events within unit tests. The events are delivered to the currently focused QML item. You can pass either a Qt.Key enum value or a latin1 char (string of length one)

Rectangle {
    width: 50; height: 50
    focus: true
    TestCase {
        name: "KeyClick"
        when: windowShown
        function test_key_click() {
            keyClick(Qt.Key_Left)
            keyClick("a")
            ...
        }
    }
}
					

The mousePress() , mouseRelease() , mouseClick() , mouseDoubleClick() , mouseDoubleClickSequence() and mouseMove() methods can be used to simulate mouse events in a similar fashion.

注意： keyboard and mouse events can only be delivered once the main window has been shown. Attempts to deliver events before then will fail. Use the when and windowShown properties to track when the main window has been shown.

管理动态创建的测试对象

A typical pattern with QML tests is to dynamically create an item and then destroy it at the end of the test function:

TestCase {
    id: testCase
    name: "MyTest"
    when: windowShown
    function test_click() {
        var item = Qt.createQmlObject("import QtQuick 2.0; Item {}", testCase);
        verify(item);
        // Test item...
        item.destroy();
    }
}
					

The problem with this pattern is that any failures in the test function will cause the call to item.destroy() to be skipped, leaving the item hanging around in the scene until the test case has finished. This can result in interference with future tests; for example, by blocking input events or producing unrelated debug output that makes it difficult to follow the code's execution.

通过调用 createTemporaryQmlObject() instead, the object is guaranteed to be destroyed at the end of the test function:

TestCase {
    id: testCase
    name: "MyTest"
    when: windowShown
    function test_click() {
        var item = createTemporaryQmlObject("import QtQuick 2.0; Item {}", testCase);
        verify(item);
        // Test item...
        // Don't need to worry about destroying "item" here.
    }
}
					

For objects that are created via the createObject() function of Component ， createTemporaryObject() function can be used.

另请参阅 SignalSpy and Qt Quick Test Reference Documentation .

特性文档编制

completed : bool

This property will be set to true once the test case has completed execution. Test cases are only executed once. The initial value is false.

另请参阅 running and when .

name : string

This property defines the name of the test case for result reporting. The default value is an empty string.

TestCase {
    name: "ButtonTests"
    ...
}
							

optional : bool

多 TestCase types can be supplied in a test application. The application will exit once they have all completed. If a test case does not need to run (because a precondition has failed), then this property can be set to true. The default value is false.

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

另请参阅 when and completed .

running : bool

This property will be set to true while the test case is running. The initial value is false, and the value will become false again once the test case completes.

另请参阅 completed and when .

当 : bool

This property should be set to true when the application wants the test cases to run. The default value is true. In the following example, a test is run when the user presses the mouse button:

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)
        }
    }
}
										

The test application will exit once all TestCase types have been triggered and have run. The optional property can be used to exclude a TestCase 类型。

另请参阅 optional and completed .

windowShown : bool

This property will be set to true after the QML viewing window has been displayed. Normally test cases run as soon as the test application is loaded and before a window is displayed. If the test case involves visual types and behaviors, then it may need to be delayed until after the window is shown.

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

方法文档编制

cleanup ()

This function is called after each test function that is executed in the TestCase type. The default implementation does nothing. The application can provide its own implementation to perform cleanup after each test function.

另请参阅 init() and cleanupTestCase() .

cleanupTestCase ()

This function is called after all other test functions in the TestCase type have completed. The default implementation does nothing. The application can provide its own implementation to perform test case cleanup.

另请参阅 initTestCase() and cleanup() .

compare ( actual , expected , message = "")

Fails the current test case if actual is not the same as expected , and displays the optional message . Similar to QCOMPARE(actual, expected) in C++.

另请参阅 tryCompare() and fuzzyCompare .

对象 createTemporaryObject ( Component component , 对象 parent , 对象 properties )

This function dynamically creates a QML object from the given component with the specified optional parent and properties . The returned object will be destroyed (if it was not already) after cleanup() has finished executing, meaning that objects created with this function are guaranteed to be destroyed after each test, regardless of whether or not the tests fail.

If there was an error while creating the object, null 将被返回。

此函数调用 component.createObject() internally.

This QML method was introduced in Qt 5.9.

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

对象 createTemporaryQmlObject ( string qml , 对象 parent , string filePath )

This function dynamically creates a QML object from the given qml string with the specified parent . The returned object will be destroyed (if it was not already) after cleanup() has finished executing, meaning that objects created with this function are guaranteed to be destroyed after each test, regardless of whether or not the tests fail.

If there was an error while creating the object, null 将被返回。

若 filePath is specified, it will be used for error reporting for the created object.

此函数调用 Qt.createQmlObject() internally.

This QML method was introduced in Qt 5.9.

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

expectFail ( tag , message )

In a data-driven test, marks the row associated with tag as expected to fail. When the fail occurs, display the message , abort the test, and mark the test as passing. Similar to QEXPECT_FAIL(tag, message, Abort) in C++.

If the test is not data-driven, then tag must be set to an empty string.

另请参阅 expectFailContinue() .

expectFailContinue ( tag , message )

In a data-driven test, marks the row associated with tag as expected to fail. When the fail occurs, display the message , and then continue the test. Similar to QEXPECT_FAIL(tag, message, Continue) in C++.

If the test is not data-driven, then tag must be set to an empty string.

另请参阅 expectFail() .

fail ( message = "")

Fails the current test case, with the optional message . Similar to QFAIL(message) in C++.

QtObject findChild ( parent , objectName )

Returns the first child of parent with objectName ，或 null if no such item exists. Both visual and non-visual children are searched recursively, with visual children being searched first.

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

This QML method was introduced in Qt 5.4.

fuzzyCompare ( actual , expected , delta , message = "")

Fails the current test case if the difference betwen actual and expected 大于 delta , and displays the optional message . Similar to qFuzzyCompare(actual, expected) in C++ but with a required delta 值。

This function can also be used for color comparisons if both the actual and expected values can be converted into color values. If any of the differences for RGBA channel values are greater than delta , the test fails.

另请参阅 tryCompare() and compare() .

对象 grabImage ( item )

Returns a snapshot image object of the given item .

The returned image object has the following methods:

• red(x, y) Returns the red channel value of the pixel at x , y 位置
• green(x, y) Returns the green channel value of the pixel at x , y 位置
• blue(x, y) Returns the blue channel value of the pixel at x , y 位置
• alpha(x, y) Returns the alpha channel value of the pixel at x , y 位置
• pixel(x, y) Returns the color value of the pixel at x , y 位置
• equals(image) Returns true if this image is identical to image - see QImage::operator== (since 5.6)

  例如：

  var image = grabImage(rect);
  compare(image.red(10, 10), 255);
  compare(image.pixel(20, 20), Qt.rgba(255, 0, 0, 255));
  rect.width += 10;
  var newImage = grabImage(rect);
  verify(!newImage.equals(image));
  																								

ignoreWarning ( message )

Marks message as an ignored warning message. When it occurs, the warning will not be printed and the test passes. If the message does not occur, then the test will fail. Similar to QTest::ignoreMessage(QtWarningMsg, message) in C++.

另请参阅 warn() .

init ()

This function is called before each test function that is executed in the TestCase type. The default implementation does nothing. The application can provide its own implementation to perform initialization before each test function.

另请参阅 cleanup() and initTestCase() .

initTestCase ()

This function is called before any other test functions in the TestCase type. The default implementation does nothing. The application can provide its own implementation to perform test case initialization.

另请参阅 cleanupTestCase() and init() .

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

Simulates clicking of key 采用可选 modifier on the currently focused item. If delay is larger than 0, the test will wait for delay 毫秒。

The event will be sent to the TestCase window or, in case of multiple windows, to the current active window. See QGuiApplication::focusWindow() 了解更多细节。

另请参阅 keyPress() and keyRelease() .

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

Simulates pressing a key 采用可选 modifier on the currently focused item. If delay is larger than 0, the test will wait for delay 毫秒。

The event will be sent to the TestCase window or, in case of multiple windows, to the current active window. See QGuiApplication::focusWindow() 了解更多细节。

注意： At some point you should release the key using keyRelease() .

另请参阅 keyRelease() and keyClick() .

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

Simulates releasing a key 采用可选 modifier on the currently focused item. If delay is larger than 0, the test will wait for delay 毫秒。

The event will be sent to the TestCase window or, in case of multiple windows, to the current active window. See QGuiApplication::focusWindow() 了解更多细节。

另请参阅 keyPress() and keyClick() .

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

Simulates clicking a mouse button 采用可选 modifier on an item . The position of the click is defined by x and y 。若 x and y are not defined the position will be the center of item 。若 delay is specified, the test will wait for the specified amount of milliseconds before pressing and before releasing the button.

The position given by x and y is transformed from the co-ordinate system of item into window co-ordinates and then delivered. If item is obscured by another item, or a child of item occupies that position, then the event will be delivered to the other item instead.

另请参阅 mousePress() , mouseRelease() , mouseDoubleClick() , mouseDoubleClickSequence() , mouseMove() , mouseDrag() ，和 mouseWheel() .

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

Simulates double-clicking a mouse button 采用可选 modifier on an item . The position of the click is defined by x and y 。若 x and y are not defined the position will be the center of item 。若 delay is specified, the test will wait for the specified amount of milliseconds before pressing and before releasing the button.

The position given by x and y is transformed from the co-ordinate system of item into window co-ordinates and then delivered. If item is obscured by another item, or a child of item occupies that position, then the event will be delivered to the other item instead.

另请参阅 mouseDoubleClickSequence() , mousePress() , mouseRelease() , mouseClick() , mouseMove() , mouseDrag() ，和 mouseWheel() .

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

Simulates the full sequence of events generated by double-clicking a mouse button 采用可选 modifier on an item .

This method reproduces the sequence of mouse events generated when a user makes a double click: Press-Release-Press-DoubleClick-Release.

The position of the click is defined by x and y 。若 x and y are not defined the position will be the center of item 。若 delay is specified, the test will wait for the specified amount of milliseconds before pressing and before releasing the button.

The position given by x and y is transformed from the co-ordinate system of item into window co-ordinates and then delivered. If item is obscured by another item, or a child of item occupies that position, then the event will be delivered to the other item instead.

This QML method was introduced in Qt 5.5.

另请参阅 mouseDoubleClick() , mousePress() , mouseRelease() , mouseClick() , mouseMove() , mouseDrag() ，和 mouseWheel() .

mouseDrag ( item , x , y , dx , dy , button = Qt.LeftButton, modifiers = Qt.NoModifier, delay = -1)

Simulates dragging the mouse on an item with button pressed and an optional modifier . The initial drag position is defined by x and y , and drag distance is defined by dx and dy 。若 delay is specified, the test will wait for the specified amount of milliseconds before releasing the button.

The position given by x and y is transformed from the co-ordinate system of item into window co-ordinates and then delivered. If item is obscured by another item, or a child of item occupies that position, then the event will be delivered to the other item instead.

Note: this method does not imply a drop action, to make a drop, an additional mouseRelease (item, x + dx, y + dy) is needed.

另请参阅 mousePress() , mouseClick() , mouseDoubleClick() , mouseDoubleClickSequence() , mouseMove() , mouseRelease() ，和 mouseWheel() .

mouseMove ( item , x , y , delay = -1)

Moves the mouse pointer to the position given by x and y 在 item . If a delay (in milliseconds) is given, the test will wait before moving the mouse pointer.

The position given by x and y is transformed from the co-ordinate system of item into window co-ordinates and then delivered. If item is obscured by another item, or a child of item occupies that position, then the event will be delivered to the other item instead.

另请参阅 mousePress() , mouseRelease() , mouseClick() , mouseDoubleClick() , mouseDoubleClickSequence() , mouseDrag() ，和 mouseWheel() .

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

Simulates pressing a mouse button 采用可选 modifier on an item . The position is defined by x and y 。若 x or y are not defined the position will be the center of item 。若 delay is specified, the test will wait for the specified amount of milliseconds before the press.

The position given by x and y is transformed from the co-ordinate system of item into window co-ordinates and then delivered. If item is obscured by another item, or a child of item occupies that position, then the event will be delivered to the other item instead.

另请参阅 mouseRelease() , mouseClick() , mouseDoubleClick() , mouseDoubleClickSequence() , mouseMove() , mouseDrag() ，和 mouseWheel() .

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

Simulates releasing a mouse button 采用可选 modifier on an item . The position of the release is defined by x and y 。若 x or y are not defined the position will be the center of item 。若 delay is specified, the test will wait for the specified amount of milliseconds before releasing the button.

The position given by x and y is transformed from the co-ordinate system of item into window co-ordinates and then delivered. If item is obscured by another item, or a child of item occupies that position, then the event will be delivered to the other item instead.

另请参阅 mousePress() , mouseClick() , mouseDoubleClick() , mouseDoubleClickSequence() , mouseMove() , mouseDrag() ，和 mouseWheel() .

mouseWheel ( item , x , y , xDelta , yDelta , button = Qt.LeftButton, modifiers = Qt.NoModifier, delay = -1)

Simulates rotating the mouse wheel on an item with button pressed and an optional modifier . The position of the wheel event is defined by x and y 。若 delay is specified, the test will wait for the specified amount of milliseconds before releasing the button.

The position given by x and y is transformed from the co-ordinate system of item into window co-ordinates and then delivered. If item is obscured by another item, or a child of item occupies that position, then the event will be delivered to the other item instead.

The xDelta and yDelta contain the wheel rotation distance in eighths of a degree. see QWheelEvent::angleDelta() 了解更多细节。

另请参阅 mousePress() , mouseClick() , mouseDoubleClick() , mouseDoubleClickSequence() , mouseMove() , mouseRelease() , mouseDrag() ，和 QWheelEvent::angleDelta() .

skip ( message = "")

Skips the current test case and prints the optional message . If this is a data-driven test, then only the current row is skipped. Similar to QSKIP(message) in C++.

sleep ( ms )

Sleeps for ms milliseconds without processing Qt events.

另请参阅 wait() and waitForRendering() .

TouchEventSequence touchEvent ( 对象 item )

Begins a sequence of touch events through a simulated QTouchDevice::TouchScreen . Events are delivered to the window containing item .

The returned object is used to enumerate events to be delivered through a single QTouchEvent . Touches are delivered to the window containing the TestCase unless otherwise specified.

Rectangle {
    width: 640; height: 480
    MultiPointTouchArea {
        id: area
        anchors.fill: parent
        property bool touched: false
        onPressed: touched = true
    }
    TestCase {
        name: "ItemTests"
        when: area.pressed
        id: test1
        function test_touch() {
            var touch = touchEvent(area);
            touch.press(0, area, 10, 10);
            touch.commit();
            verify(area.touched);
        }
    }
}
																																							

This QML method was introduced in Qt 5.9.

另请参阅 TouchEventSequence::press() , TouchEventSequence::move() , TouchEventSequence::release() , TouchEventSequence::stationary() , TouchEventSequence::commit() ，和 QTouchDevice::TouchScreen .

tryCompare ( obj , property , expected , timeout = 5000, message = "")

Fails the current test case if the specified property on obj is not the same as expected , and displays the optional message . The test will be retried multiple times until the timeout (in milliseconds) is reached.

This function is intended for testing applications where a property changes value based on asynchronous events. Use compare() for testing synchronous property changes.

tryCompare(img, "status", BorderImage.Ready)
compare(img.width, 120)
compare(img.height, 120)
compare(img.horizontalTileMode, BorderImage.Stretch)
compare(img.verticalTileMode, BorderImage.Stretch)
																																								

SignalSpy::wait() provides an alternative method to wait for a signal to be emitted.

另请参阅 compare() and SignalSpy::wait() .

tryVerify ( function , timeout = 5000, message = "")

Fails the current test case if function does not evaluate to true before the specified timeout (in milliseconds) has elapsed. The function is evaluated multiple times until the timeout is reached. An optional message is displayed upon failure.

This function is intended for testing applications where a condition changes based on asynchronous events. Use verify() for testing synchronous condition changes, and tryCompare() for testing asynchronous property changes.

For example, in the code below, it's not possible to use tryCompare() , because the currentItem property might be null for a short period of time:

tryCompare(listView.currentItem, "text", "Hello");
																																									

Instead, we can use tryVerify() to first check that currentItem isn't null , and then use a regular compare afterwards:

tryVerify(function(){ return listView.currentItem })
compare(listView.currentItem.text, "Hello")
																																									

该 QML 方法在 Qt 5.8 引入。

另请参阅 verify() , compare() , tryCompare() ，和 SignalSpy::wait() .

verify ( 条件 , message = "")

Fails the current test case if 条件 is false, and displays the optional message . Similar to QVERIFY(condition) or QVERIFY2(condition, message) in C++.

wait ( ms )

等待 ms milliseconds while processing Qt events.

另请参阅 sleep() and waitForRendering() .

waitForRendering ( item , timeout = 5000)

等待 timeout milliseconds or until the item is rendered by the renderer. Returns true if item is rendered in timeout milliseconds, otherwise returns false. The default timeout value is 5000.

另请参阅 sleep() and wait() .

warn ( message )

Prints message as a warning message. Similar to QWARN(message) in C++.

另请参阅 ignoreWarning() .