1 /****************************************************************************
3 ** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
4 ** All rights reserved.
5 ** Contact: http://www.qt-project.org/
7 ** This file is part of the test suite of the Qt Toolkit.
9 ** $QT_BEGIN_LICENSE:LGPL$
10 ** GNU Lesser General Public License Usage
11 ** This file may be used under the terms of the GNU Lesser General Public
12 ** License version 2.1 as published by the Free Software Foundation and
13 ** appearing in the file LICENSE.LGPL included in the packaging of this
14 ** file. Please review the following information to ensure the GNU Lesser
15 ** General Public License version 2.1 requirements will be met:
16 ** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
18 ** In addition, as a special exception, Nokia gives you certain additional
19 ** rights. These rights are described in the Nokia Qt LGPL Exception
20 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
22 ** GNU General Public License Usage
23 ** Alternatively, this file may be used under the terms of the GNU General
24 ** Public License version 3.0 as published by the Free Software Foundation
25 ** and appearing in the file LICENSE.GPL included in the packaging of this
26 ** file. Please review the following information to ensure the GNU General
27 ** Public License version 3.0 requirements will be met:
28 ** http://www.gnu.org/copyleft/gpl.html.
31 ** Alternatively, this file may be used in accordance with the terms and
32 ** conditions contained in a signed written agreement between you and Nokia.
40 ****************************************************************************/
43 \qmlclass TestCase TestCase
44 \brief The TestCase item represents a unit test case.
48 \section1 Introduction to QML test cases
50 Test cases are written as JavaScript functions within a TestCase
55 import QtQuickTest 1.0
60 function test_math() {
61 compare(2 + 2, 4, "2 + 2 = 4")
64 function test_fail() {
65 compare(2 + 2, 5, "2 + 2 = 5")
70 Functions whose names start with "test_" are treated as test cases
71 to be executed. The \l name property is used to prefix the functions
75 ********* Start testing of MathTests *********
76 Config: Using QTest library 4.7.2, Qt 4.7.2
77 PASS : MathTests::initTestCase()
78 FAIL! : MathTests::test_fail() 2 + 2 = 5
81 Loc: [/home/.../tst_math.qml(12)]
82 PASS : MathTests::test_math()
83 PASS : MathTests::cleanupTestCase()
84 Totals: 3 passed, 1 failed, 0 skipped
85 ********* Finished testing of MathTests *********
88 Because of the way JavaScript properties work, the order in which the
89 test functions are found is unpredictable. To assist with predictability,
90 the test framework will sort the functions on ascending order of name.
91 This can help when there are two tests that must be run in order.
93 Multiple TestCase elements can be supplied. The test program will exit
94 once they have all completed. If a test case doesn't need to run
95 (because a precondition has failed), then \l optional can be set to true.
97 \section1 Data-driven tests
99 Table data can be provided to a test using a function name that ends
104 import QtQuickTest 1.0
109 function test_table_data() {
111 {tag: "2 + 2 = 4", a: 2, b: 2, answer: 4 },
112 {tag: "2 + 6 = 8", a: 2, b: 6, answer: 8 },
116 function test_table(data) {
117 compare(data.a + data.b, data.answer)
122 The test framework will iterate over all of the rows in the table
123 and pass each row to the test function. As shown, the columns can be
124 extracted for use in the test. The \c tag column is special - it is
125 printed by the test framework when a row fails, to help the reader
126 identify which case failed amongst a set of otherwise passing tests.
130 Functions whose names start with "benchmark_" will be run multiple
131 times with the Qt benchmark framework, with an average timing value
132 reported for the runs. This is equivalent to using the \c{QBENCHMARK}
133 macro in the C++ version of QTestLib.
138 name: "CreateBenchmark"
140 function benchmark_create_component() {
141 var component = Qt.createComponent("item.qml")
142 var obj = component.createObject(top)
148 RESULT : CreateBenchmark::benchmark_create_component:
149 0.23 msecs per iteration (total: 60, iterations: 256)
150 PASS : CreateBenchmark::benchmark_create_component()
153 To get the effect of the \c{QBENCHMARK_ONCE} macro, prefix the test
154 function name with "benchmark_once_".
156 \section1 Simulating keyboard and mouse events
158 The keyPress(), keyRelease(), and keyClick() methods can be used
159 to simulate keyboard events within unit tests. The events are
160 delivered to the currently focused QML item.
164 width: 50; height: 50
171 function test_key_click() {
172 keyClick(Qt.Key_Left)
179 The mousePress(), mouseRelease(), mouseClick(), mouseDoubleClick(),
180 and mouseMove() methods can be used to simulate mouse events in a
183 \bold{Note:} keyboard and mouse events can only be delivered once the
184 main window has been shown. Attempts to deliver events before then
185 will fail. Use the \l when and windowShown properties to track
186 when the main window has been shown.
192 \qmlproperty string TestCase::name
194 This property defines the name of the test case for result reporting.
195 The default is the empty string.
206 \qmlproperty bool TestCase::when
208 This property should be set to true when the application wants
209 the test cases to run. The default value is true. In the following
210 example, a test is run when the user presses the mouse button:
215 width: 640; height: 480
223 property bool bar: true
230 function test_bar() {
237 The test application will exit once all \l TestCase elements
238 have been triggered and have run. The \l optional property can
239 be used to exclude a \l TestCase element.
241 \sa optional, completed
245 \qmlproperty bool TestCase::optional
247 Multiple \l TestCase elements can be supplied in a test application.
248 The application will exit once they have all completed. If a test case
249 does not need to run (because a precondition has failed), then this
250 property can be set to true. The default value is false.
256 function test_not_run() {
266 \qmlproperty bool TestCase::completed
268 This property will be set to true once the test case has completed
269 execution. Test cases are only executed once. The initial value
276 \qmlproperty bool TestCase::running
278 This property will be set to true while the test case is running.
279 The initial value is false, and the value will become false again
280 once the test case completes.
286 \qmlproperty bool TestCase::windowShown
288 This property will be set to true after the QML viewing window has
289 been displayed. Normally test cases run as soon as the test application
290 is loaded and before a window is displayed. If the test case involves
291 visual elements and behaviors, then it may need to be delayed until
292 after the window is shown.
297 onClicked: text = "Clicked"
301 function test_click() {
303 compare(button.text, "Clicked");
311 \qmlmethod TestCase::fail(message = "")
313 Fails the current test case, with the optional \a message.
314 Similar to \c{QFAIL(message)} in C++.
318 \qmlmethod TestCase::verify(condition, message = "")
320 Fails the current test case if \a condition is false, and
321 displays the optional \a message. Similar to \c{QVERIFY(condition)}
322 or \c{QVERIFY2(condition, message)} in C++.
326 \qmlmethod TestCase::compare(actual, expected, message = "")
328 Fails the current test case if \a actual is not the same as
329 \a expected, and displays the optional \a message. Similar
330 to \c{QCOMPARE(actual, expected)} in C++.
336 \qmlmethod TestCase::tryCompare(obj, property, expected, timeout = 5000)
338 Fails the current test case if the specified \a property on \a obj
339 is not the same as \a expected. The test will be retried multiple
340 times until the \a timeout (in milliseconds) is reached.
342 This function is intended for testing applications where a property
343 changes value based on asynchronous events. Use compare() for testing
344 synchronous property changes.
347 tryCompare(img, "status", BorderImage.Ready)
348 compare(img.width, 120)
349 compare(img.height, 120)
350 compare(img.horizontalTileMode, BorderImage.Stretch)
351 compare(img.verticalTileMode, BorderImage.Stretch)
354 SignalSpy::wait() provides an alternative method to wait for a
355 signal to be emitted.
357 \sa compare(), SignalSpy::wait()
361 \qmlmethod TestCase::skip(message = "")
363 Skips the current test case and prints the optional \a message.
364 If this is a data-driven test, then only the current row is skipped.
365 Similar to \c{QSKIP(message)} in C++.
369 \qmlmethod TestCase::expectFail(tag, message)
371 In a data-driven test, marks the row associated with \a tag as
372 expected to fail. When the fail occurs, display the \a message,
373 abort the test, and mark the test as passing. Similar to
374 \c{QEXPECT_FAIL(tag, message, Abort)} in C++.
376 If the test is not data-driven, then \a tag must be set to
379 \sa expectFailContinue()
383 \qmlmethod TestCase::expectFailContinue(tag, message)
385 In a data-driven test, marks the row associated with \a tag as
386 expected to fail. When the fail occurs, display the \a message,
387 and then continue the test. Similar to
388 \c{QEXPECT_FAIL(tag, message, Continue)} in C++.
390 If the test is not data-driven, then \a tag must be set to
397 \qmlmethod TestCase::warn(message)
399 Prints \a message as a warning message. Similar to
400 \c{QWARN(message)} in C++.
406 \qmlmethod TestCase::ignoreWarning(message)
408 Marks \a message as an ignored warning message. When it occurs,
409 the warning will not be printed and the test passes. If the message
410 does not occur, then the test will fail. Similar to
411 \c{QTest::ignoreMessage(QtWarningMsg, message)} in C++.
417 \qmlmethod TestCase::wait(ms)
419 Waits for \a ms milliseconds while processing Qt events.
425 \qmlmethod TestCase::sleep(ms)
427 Sleeps for \a ms milliseconds without processing Qt events.
433 \qmlmethod TestCase::keyClick(key, modifiers = Qt.NoModifier, delay = -1)
435 Simulates clicking of \a key with an optional \a modifier on the currently
436 focused item. If \a delay is larger than 0, the test will wait for
437 \a delay milliseconds.
439 \sa keyPress(), keyRelease()
443 \qmlmethod TestCase::keyPress(key, modifiers = Qt.NoModifier, delay = -1)
445 Simulates pressing a \a key with an optional \a modifier on the currently
446 focused item. If \a delay is larger than 0, the test will wait for
447 \a delay milliseconds.
449 \bold{Note:} At some point you should release the key using keyRelease().
451 \sa keyRelease(), keyClick()
455 \qmlmethod TestCase::keyRelease(key, modifiers = Qt.NoModifier, delay = -1)
457 Simulates releasing a \a key with an optional \a modifier on the currently
458 focused item. If \a delay is larger than 0, the test will wait for
459 \a delay milliseconds.
461 \sa keyPress(), keyClick()
465 \qmlmethod TestCase::mousePress(item, x, y, button = Qt.LeftButton, modifiers = Qt.NoModifier, delay = -1)
467 Simulates pressing a mouse \a button with an optional \a modifier
468 on an \a item. The position is defined by \a x and \a y. If \a delay is
469 specified, the test will wait for the specified amount of milliseconds
472 The position given by \a x and \a y is transformed from the co-ordinate
473 system of \a item into window co-ordinates and then delivered.
474 If \a item is obscured by another item, or a child of \a item occupies
475 that position, then the event will be delivered to the other item instead.
477 \sa mouseRelease(), mouseClick(), mouseDoubleClick(), mouseMove()
481 \qmlmethod TestCase::mouseRelease(item, x, y, button = Qt.LeftButton, modifiers = Qt.NoModifier, delay = -1)
483 Simulates releasing a mouse \a button with an optional \a modifier
484 on an \a item. The position of the release is defined by \a x and \a y.
485 If \a delay is specified, the test will wait for the specified amount of
486 milliseconds before releasing the button.
488 The position given by \a x and \a y is transformed from the co-ordinate
489 system of \a item into window co-ordinates and then delivered.
490 If \a item is obscured by another item, or a child of \a item occupies
491 that position, then the event will be delivered to the other item instead.
493 \sa mousePress(), mouseClick(), mouseDoubleClick(), mouseMove()
497 \qmlmethod TestCase::mouseClick(item, x, y, button = Qt.LeftButton, modifiers = Qt.NoModifier, delay = -1)
499 Simulates clicking a mouse \a button with an optional \a modifier
500 on an \a item. The position of the click is defined by \a x and \a y.
501 If \a delay is specified, the test will wait for the specified amount of
502 milliseconds before pressing and before releasing the button.
504 The position given by \a x and \a y is transformed from the co-ordinate
505 system of \a item into window co-ordinates and then delivered.
506 If \a item is obscured by another item, or a child of \a item occupies
507 that position, then the event will be delivered to the other item instead.
509 \sa mousePress(), mouseRelease(), mouseDoubleClick(), mouseMove()
513 \qmlmethod TestCase::mouseDoubleClick(item, x, y, button = Qt.LeftButton, modifiers = Qt.NoModifier, delay = -1)
515 Simulates double-clicking a mouse \a button with an optional \a modifier
516 on an \a item. The position of the click is defined by \a x and \a y.
517 If \a delay is specified, the test will wait for the specified amount of
518 milliseconds before pressing and before releasing the button.
520 The position given by \a x and \a y is transformed from the co-ordinate
521 system of \a item into window co-ordinates and then delivered.
522 If \a item is obscured by another item, or a child of \a item occupies
523 that position, then the event will be delivered to the other item instead.
525 \sa mousePress(), mouseRelease(), mouseClick(), mouseMove()
529 \qmlmethod TestCase::mouseMove(item, x, y, delay = -1)
531 Moves the mouse pointer to the position given by \a x and \a y within
532 \a item. If a \a delay (in milliseconds) is given, the test will wait
533 before moving the mouse pointer.
535 The position given by \a x and \a y is transformed from the co-ordinate
536 system of \a item into window co-ordinates and then delivered.
537 If \a item is obscured by another item, or a child of \a item occupies
538 that position, then the event will be delivered to the other item instead.
540 \sa mousePress(), mouseRelease(), mouseClick(), mouseDoubleClick()
544 \qmlmethod TestCase::initTestCase()
546 This function is called before any other test functions in the
547 \l TestCase element. The default implementation does nothing.
548 The application can provide its own implementation to perform
549 test case initialization.
551 \sa cleanupTestCase(), init()
555 \qmlmethod TestCase::cleanupTestCase()
557 This function is called after all other test functions in the
558 \l TestCase element have completed. The default implementation
559 does nothing. The application can provide its own implementation
560 to perform test case cleanup.
562 \sa initTestCase(), cleanup()
566 \qmlmethod TestCase::init()
568 This function is called before each test function that is
569 executed in the \l TestCase element. The default implementation
570 does nothing. The application can provide its own implementation
571 to perform initialization before each test function.
573 \sa cleanup(), initTestCase()
577 \qmlmethod TestCase::cleanup()
579 This function is called after each test function that is
580 executed in the \l TestCase element. The default implementation
581 does nothing. The application can provide its own implementation
582 to perform cleanup after each test function.
584 \sa init(), cleanupTestCase()