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.

See also running and when.

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

TestCase {
    name: "ButtonTests"
    ...
}

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

See also when and completed.

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.

See also completed and when.

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 type.

See also optional and completed.

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

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.

See also init() and 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.

See also initTestCase() and cleanup().

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++.

See also tryCompare() and fuzzyCompare.

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.

See also expectFailContinue().

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.

See also expectFail().

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

Returns the first child of parent with objectName, or 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.

Fails the current test case if the difference betwen actual and expected is greater than delta, and displays the optional message. Similar to qFuzzyCompare(actual, expected) in C++ but with a required delta value.

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.

See also tryCompare() and compare().

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 position
• green(x, y) Returns the green channel value of the pixel at x, y position
• blue(x, y) Returns the blue channel value of the pixel at x, y position
• alpha(x, y) Returns the alpha channel value of the pixel at x, y position
• pixel(x, y) Returns the color value of the pixel at x, y position
• equals(image) Returns true if this image is identical to image - see QImage::operator== (since 5.6)

  For example:

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

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++.

See also warn().

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.

See also cleanup() and 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.

See also cleanupTestCase() and init().

Simulates clicking of key with an optional modifier on the currently focused item. If delay is larger than 0, the test will wait for delay milliseconds.

The event will be sent to the TestCase window or, in case of multiple windows, to the current active window. See QGuiApplication::focusWindow() for more details.

See also keyPress() and keyRelease().

Simulates pressing a key with an optional modifier on the currently focused item. If delay is larger than 0, the test will wait for delay milliseconds.

The event will be sent to the TestCase window or, in case of multiple windows, to the current active window. See QGuiApplication::focusWindow() for more details.

Note: At some point you should release the key using keyRelease().

See also keyRelease() and keyClick().

Simulates releasing a key with an optional modifier on the currently focused item. If delay is larger than 0, the test will wait for delay milliseconds.

The event will be sent to the TestCase window or, in case of multiple windows, to the current active window. See QGuiApplication::focusWindow() for more details.

See also keyPress() and keyClick().

Simulates clicking a mouse button with an optional modifier on an item. The position of the click is defined by x and y. If x and y are not defined the position will be the center of item. If 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.

See also mousePress(), mouseRelease(), mouseDoubleClick(), mouseDoubleClickSequence(), mouseMove(), mouseDrag(), and mouseWheel().

Simulates double-clicking a mouse button with an optional modifier on an item. The position of the click is defined by x and y. If x and y are not defined the position will be the center of item. If 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.

See also mouseDoubleClickSequence(), mousePress(), mouseRelease(), mouseClick(), mouseMove(), mouseDrag(), and mouseWheel().

Simulates the full sequence of events generated by double-clicking a mouse button with an optional 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. If x and y are not defined the position will be the center of item. If 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.

See also mouseDoubleClick(), mousePress(), mouseRelease(), mouseClick(), mouseMove(), mouseDrag(), and mouseWheel().

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. If 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.

See also mousePress(), mouseClick(), mouseDoubleClick(), mouseDoubleClickSequence(), mouseMove(), mouseRelease(), and mouseWheel().

Moves the mouse pointer to the position given by x and y within 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.

See also mousePress(), mouseRelease(), mouseClick(), mouseDoubleClick(), mouseDoubleClickSequence(), mouseDrag(), and mouseWheel().

Simulates pressing a mouse button with an optional modifier on an item. The position is defined by x and y. If x or y are not defined the position will be the center of item. If 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.

See also mouseRelease(), mouseClick(), mouseDoubleClick(), mouseDoubleClickSequence(), mouseMove(), mouseDrag(), and mouseWheel().

Simulates releasing a mouse button with an optional modifier on an item. The position of the release is defined by x and y. If x or y are not defined the position will be the center of item. If 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.

See also mousePress(), mouseClick(), mouseDoubleClick(), mouseDoubleClickSequence(), mouseMove(), mouseDrag(), and mouseWheel().

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. If 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() for more details.

See also mousePress(), mouseClick(), mouseDoubleClick(), mouseDoubleClickSequence(), mouseMove(), mouseRelease(), mouseDrag(), and QWheelEvent::angleDelta().

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++.

Sleeps for ms milliseconds without processing Qt events.

See also wait() and waitForRendering().

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.

See also compare() and SignalSpy::wait().

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

This QML method was introduced in Qt 5.8.

See also verify(), compare(), tryCompare(), and SignalSpy::wait().

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

Waits for ms milliseconds while processing Qt events.

See also sleep() and waitForRendering().

Waits for 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.

See also sleep() and wait().

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

See also ignoreWarning().