src/imports/testlib/testcase.qdoc

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
   4 ** Contact: http://www.qt-project.org/
   5 **
   6 ** This file is part of the test suite of the Qt Toolkit.
   7 **
   8 ** $QT_BEGIN_LICENSE:LGPL$
   9 ** GNU Lesser General Public License Usage
  10 ** This file may be used under the terms of the GNU Lesser General Public
  11 ** License version 2.1 as published by the Free Software Foundation and
  12 ** appearing in the file LICENSE.LGPL included in the packaging of this
  13 ** file. Please review the following information to ensure the GNU Lesser
  14 ** General Public License version 2.1 requirements will be met:
  15 ** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
  16 **
  17 ** In addition, as a special exception, Nokia gives you certain additional
  18 ** rights. These rights are described in the Nokia Qt LGPL Exception
  19 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
  20 **
  21 ** GNU General Public License Usage
  22 ** Alternatively, this file may be used under the terms of the GNU General
  23 ** Public License version 3.0 as published by the Free Software Foundation
  24 ** and appearing in the file LICENSE.GPL included in the packaging of this
  25 ** file. Please review the following information to ensure the GNU General
  26 ** Public License version 3.0 requirements will be met:
  27 ** http://www.gnu.org/copyleft/gpl.html.
  28 **
  29 ** Other Usage
  30 ** Alternatively, this file may be used in accordance with the terms and
  31 ** conditions contained in a signed written agreement between you and Nokia.
  32 **
  33 **
  34 **
  35 **
  36 **
  37 **
  38 ** $QT_END_LICENSE$
  39 **
  40 ****************************************************************************/
  41
  42 /*!
  43     \qmlclass TestCase TestCase
  44     \brief The TestCase item represents a unit test case.
  45     \since 4.8
  46     \ingroup qtest::qml
  47
  48     \section1 Introduction to QML test cases
  49
  50     Test cases are written as JavaScript functions within a TestCase
  51     element:
  52
  53     \code
  54     import QtQuick 1.0
  55     import QtQuickTest 1.0
  56
  57     TestCase {
  58         name: "MathTests"
  59
  60         function test_math() {
  61             compare(2 + 2, 4, "2 + 2 = 4")
  62         }
  63
  64         function test_fail() {
  65             compare(2 + 2, 5, "2 + 2 = 5")
  66         }
  67     }
  68     \endcode
  69
  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
  72     in the output:
  73
  74     \code
  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
  79        Actual (): 4
  80        Expected (): 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 *********
  86     \endcode
  87
  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.
  92
  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.
  96
  97     \section1 Data-driven tests
  98
  99     Table data can be provided to a test using a function name that ends
 100     with "_data":
 101
 102     \code
 103     import QtQuick 1.0
 104     import QtQuickTest 1.0
 105
 106     TestCase {
 107         name: "DataTests"
 108
 109         function test_table_data() {
 110             return [
 111                 {tag: "2 + 2 = 4", a: 2, b: 2, answer: 4 },
 112                 {tag: "2 + 6 = 8", a: 2, b: 6, answer: 8 },
 113             ]
 114         }
 115
 116         function test_table(data) {
 117             compare(data.a + data.b, data.answer)
 118         }
 119     }
 120     \endcode
 121
 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.
 127
 128     \section1 Benchmarks
 129
 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.
 134
 135     \code
 136     TestCase {
 137         id: top
 138         name: "CreateBenchmark"
 139
 140         function benchmark_create_component() {
 141             var component = Qt.createComponent("item.qml")
 142             var obj = component.createObject(top)
 143             obj.destroy()
 144             component.destroy()
 145         }
 146     }
 147
 148     RESULT : CreateBenchmark::benchmark_create_component:
 149          0.23 msecs per iteration (total: 60, iterations: 256)
 150     PASS   : CreateBenchmark::benchmark_create_component()
 151     \endcode
 152
 153     To get the effect of the \c{QBENCHMARK_ONCE} macro, prefix the test
 154     function name with "benchmark_once_".
 155
 156     \section1 Simulating keyboard and mouse events
 157
 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.
 161
 162     \code
 163     Rectangle {
 164         width: 50; height: 50
 165         focus: true
 166
 167         TestCase {
 168             name: "KeyClick"
 169             when: windowShown
 170
 171             function test_key_click() {
 172                 keyClick(Qt.Key_Left)
 173                 ...
 174             }
 175         }
 176     }
 177     \endcode
 178
 179     The mousePress(), mouseRelease(), mouseClick(), mouseDoubleClick(),
 180     and mouseMove() methods can be used to simulate mouse events in a
 181     similar fashion.
 182
 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.
 187
 188     \sa SignalSpy
 189 */
 190
 191 /*!
 192     \qmlproperty string TestCase::name
 193
 194     This property defines the name of the test case for result reporting.
 195     The default is the empty string.
 196
 197     \code
 198     TestCase {
 199         name: "ButtonTests"
 200         ...
 201     }
 202     \endcode
 203 */
 204
 205 /*!
 206     \qmlproperty bool TestCase::when
 207
 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:
 211
 212     \code
 213     Rectangle {
 214         id: foo
 215         width: 640; height: 480
 216         color: "cyan"
 217
 218         MouseArea {
 219             id: area
 220             anchors.fill: parent
 221         }
 222
 223         property bool bar: true
 224
 225         TestCase {
 226             name: "ItemTests"
 227             when: area.pressed
 228             id: test1
 229
 230             function test_bar() {
 231                 verify(bar)
 232             }
 233         }
 234     }
 235     \endcode
 236
 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.
 240
 241     \sa optional, completed
 242 */
 243
 244 /*!
 245     \qmlproperty bool TestCase::optional
 246
 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.
 251
 252     \code
 253     TestCase {
 254         when: false
 255         optional: true
 256         function test_not_run() {
 257             verify(false)
 258         }
 259     }
 260     \endcode
 261
 262     \sa when, completed
 263 */
 264
 265 /*!
 266     \qmlproperty bool TestCase::completed
 267
 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
 270     is false.
 271
 272     \sa running, when
 273 */
 274
 275 /*!
 276     \qmlproperty bool TestCase::running
 277
 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.
 281
 282     \sa completed, when
 283 */
 284
 285 /*!
 286     \qmlproperty bool TestCase::windowShown
 287
 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.
 293
 294     \code
 295     Button {
 296         id: button
 297         onClicked: text = "Clicked"
 298         TestCase {
 299             name: "ClickTest"
 300             when: windowShown
 301             function test_click() {
 302                 button.clicked();
 303                 compare(button.text, "Clicked");
 304             }
 305         }
 306     }
 307     \endcode
 308 */
 309
 310 /*!
 311     \qmlmethod TestCase::fail(message = "")
 312
 313     Fails the current test case, with the optional \a message.
 314     Similar to \c{QFAIL(message)} in C++.
 315 */
 316
 317 /*!
 318     \qmlmethod TestCase::verify(condition, message = "")
 319
 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++.
 323 */
 324
 325 /*!
 326     \qmlmethod TestCase::compare(actual, expected, message = "")
 327
 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++.
 331
 332     \sa tryCompare()
 333 */
 334
 335 /*!
 336     \qmlmethod TestCase::tryCompare(obj, property, expected, timeout = 5000)
 337
 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.
 341
 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.
 345
 346     \code
 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)
 352     \endcode
 353
 354     SignalSpy::wait() provides an alternative method to wait for a
 355     signal to be emitted.
 356
 357     \sa compare(), SignalSpy::wait()
 358 */
 359
 360 /*!
 361     \qmlmethod TestCase::skip(message = "")
 362
 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++.
 366 */
 367
 368 /*!
 369     \qmlmethod TestCase::expectFail(tag, message)
 370
 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++.
 375
 376     If the test is not data-driven, then \a tag must be set to
 377     the empty string.
 378
 379     \sa expectFailContinue()
 380 */
 381
 382 /*!
 383     \qmlmethod TestCase::expectFailContinue(tag, message)
 384
 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++.
 389
 390     If the test is not data-driven, then \a tag must be set to
 391     the empty string.
 392
 393     \sa expectFail()
 394 */
 395
 396 /*!
 397     \qmlmethod TestCase::warn(message)
 398
 399     Prints \a message as a warning message.  Similar to
 400     \c{QWARN(message)} in C++.
 401
 402     \sa ignoreWarning()
 403 */
 404
 405 /*!
 406     \qmlmethod TestCase::ignoreWarning(message)
 407
 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++.
 412
 413     \sa warn()
 414 */
 415
 416 /*!
 417     \qmlmethod TestCase::wait(ms)
 418
 419     Waits for \a ms milliseconds while processing Qt events.
 420
 421     \sa sleep()
 422 */
 423
 424 /*!
 425     \qmlmethod TestCase::sleep(ms)
 426
 427     Sleeps for \a ms milliseconds without processing Qt events.
 428
 429     \sa wait()
 430 */
 431
 432 /*!
 433     \qmlmethod TestCase::keyClick(key, modifiers = Qt.NoModifier, delay = -1)
 434
 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.
 438
 439     \sa keyPress(), keyRelease()
 440 */
 441
 442 /*!
 443     \qmlmethod TestCase::keyPress(key, modifiers = Qt.NoModifier, delay = -1)
 444
 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.
 448
 449     \bold{Note:} At some point you should release the key using keyRelease().
 450
 451     \sa keyRelease(), keyClick()
 452 */
 453
 454 /*!
 455     \qmlmethod TestCase::keyRelease(key, modifiers = Qt.NoModifier, delay = -1)
 456
 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.
 460
 461     \sa keyPress(), keyClick()
 462 */
 463
 464 /*!
 465     \qmlmethod TestCase::mousePress(item, x, y, button = Qt.LeftButton, modifiers = Qt.NoModifier, delay = -1)
 466
 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
 470     before the press.
 471
 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.
 476
 477     \sa mouseRelease(), mouseClick(), mouseDoubleClick(), mouseMove()
 478 */
 479
 480 /*!
 481     \qmlmethod TestCase::mouseRelease(item, x, y, button = Qt.LeftButton, modifiers = Qt.NoModifier, delay = -1)
 482
 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.
 487
 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.
 492
 493     \sa mousePress(), mouseClick(), mouseDoubleClick(), mouseMove()
 494 */
 495
 496 /*!
 497     \qmlmethod TestCase::mouseClick(item, x, y, button = Qt.LeftButton, modifiers = Qt.NoModifier, delay = -1)
 498
 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.
 503
 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.
 508
 509     \sa mousePress(), mouseRelease(), mouseDoubleClick(), mouseMove()
 510 */
 511
 512 /*!
 513     \qmlmethod TestCase::mouseDoubleClick(item, x, y, button = Qt.LeftButton, modifiers = Qt.NoModifier, delay = -1)
 514
 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.
 519
 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.
 524
 525     \sa mousePress(), mouseRelease(), mouseClick(), mouseMove()
 526 */
 527
 528 /*!
 529     \qmlmethod TestCase::mouseMove(item, x, y, delay = -1)
 530
 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.
 534
 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.
 539
 540     \sa mousePress(), mouseRelease(), mouseClick(), mouseDoubleClick()
 541 */
 542
 543 /*!
 544     \qmlmethod TestCase::initTestCase()
 545
 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.
 550
 551     \sa cleanupTestCase(), init()
 552 */
 553
 554 /*!
 555     \qmlmethod TestCase::cleanupTestCase()
 556
 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.
 561
 562     \sa initTestCase(), cleanup()
 563 */
 564
 565 /*!
 566     \qmlmethod TestCase::init()
 567
 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.
 572
 573     \sa cleanup(), initTestCase()
 574 */
 575
 576 /*!
 577     \qmlmethod TestCase::cleanup()
 578
 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.
 583
 584     \sa init(), cleanupTestCase()
 585 */