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 Represents a unit test case
  45     \ingroup qtquick-utility
  46     \since 4.8
  47     \ingroup qtest::qml
  48
  49     \section1 Introduction to QML test cases
  50
  51     Test cases are written as JavaScript functions within a TestCase
  52     element:
  53
  54     \code
  55     import QtQuick 2.0
  56     import QtTest 1.0
  57
  58     TestCase {
  59         name: "MathTests"
  60
  61         function test_math() {
  62             compare(2 + 2, 4, "2 + 2 = 4")
  63         }
  64
  65         function test_fail() {
  66             compare(2 + 2, 5, "2 + 2 = 5")
  67         }
  68     }
  69     \endcode
  70
  71     Functions whose names start with "test_" are treated as test cases
  72     to be executed.  The \l name property is used to prefix the functions
  73     in the output:
  74
  75     \code
  76     ********* Start testing of MathTests *********
  77     Config: Using QTest library 4.7.2, Qt 4.7.2
  78     PASS   : MathTests::initTestCase()
  79     FAIL!  : MathTests::test_fail() 2 + 2 = 5
  80        Actual (): 4
  81        Expected (): 5
  82        Loc: [/home/.../tst_math.qml(12)]
  83     PASS   : MathTests::test_math()
  84     PASS   : MathTests::cleanupTestCase()
  85     Totals: 3 passed, 1 failed, 0 skipped
  86     ********* Finished testing of MathTests *********
  87     \endcode
  88
  89     Because of the way JavaScript properties work, the order in which the
  90     test functions are found is unpredictable.  To assist with predictability,
  91     the test framework will sort the functions on ascending order of name.
  92     This can help when there are two tests that must be run in order.
  93
  94     Multiple TestCase elements can be supplied.  The test program will exit
  95     once they have all completed.  If a test case doesn't need to run
  96     (because a precondition has failed), then \l optional can be set to true.
  97
  98     \section1 Data-driven tests
  99
 100     Table data can be provided to a test using a function name that ends
 101     with "_data". Alternatively, the \c init_data() function can be used
 102     to provide default test data for all test functions in a TestCase element:
 103
 104
 105     \code
 106     import QtQuick 2.0
 107     import QtTest 1.0
 108
 109     TestCase {
 110         name: "DataTests"
 111
 112         function init_data() {
 113           return [
 114                {tag:"init_data_1", a:1, b:2, answer: 3},
 115                {tag:"init_data_2", a:2, b:4, answer: 6}
 116           ];
 117         }
 118
 119         function test_table_data() {
 120             return [
 121                 {tag: "2 + 2 = 4", a: 2, b: 2, answer: 4 },
 122                 {tag: "2 + 6 = 8", a: 2, b: 6, answer: 8 },
 123             ]
 124         }
 125
 126         function test_table(data) {
 127             //data comes from test_table_data
 128             compare(data.a + data.b, data.answer)
 129         }
 130
 131         function test__default_table(data) {
 132             //data comes from init_data
 133             compare(data.a + data.b, data.answer)
 134         }
 135     }
 136     \endcode
 137
 138     The test framework will iterate over all of the rows in the table
 139     and pass each row to the test function.  As shown, the columns can be
 140     extracted for use in the test.  The \c tag column is special - it is
 141     printed by the test framework when a row fails, to help the reader
 142     identify which case failed amongst a set of otherwise passing tests.
 143
 144     \section1 Benchmarks
 145
 146     Functions whose names start with "benchmark_" will be run multiple
 147     times with the Qt benchmark framework, with an average timing value
 148     reported for the runs.  This is equivalent to using the \c{QBENCHMARK}
 149     macro in the C++ version of QTestLib.
 150
 151     \code
 152     TestCase {
 153         id: top
 154         name: "CreateBenchmark"
 155
 156         function benchmark_create_component() {
 157             var component = Qt.createComponent("item.qml")
 158             var obj = component.createObject(top)
 159             obj.destroy()
 160             component.destroy()
 161         }
 162     }
 163
 164     RESULT : CreateBenchmark::benchmark_create_component:
 165          0.23 msecs per iteration (total: 60, iterations: 256)
 166     PASS   : CreateBenchmark::benchmark_create_component()
 167     \endcode
 168
 169     To get the effect of the \c{QBENCHMARK_ONCE} macro, prefix the test
 170     function name with "benchmark_once_".
 171
 172     \section1 Simulating keyboard and mouse events
 173
 174     The keyPress(), keyRelease(), and keyClick() methods can be used
 175     to simulate keyboard events within unit tests.  The events are
 176     delivered to the currently focused QML item.
 177
 178     \code
 179     Rectangle {
 180         width: 50; height: 50
 181         focus: true
 182
 183         TestCase {
 184             name: "KeyClick"
 185             when: windowShown
 186
 187             function test_key_click() {
 188                 keyClick(Qt.Key_Left)
 189                 ...
 190             }
 191         }
 192     }
 193     \endcode
 194
 195     The mousePress(), mouseRelease(), mouseClick(), mouseDoubleClick(),
 196     and mouseMove() methods can be used to simulate mouse events in a
 197     similar fashion.
 198
 199     \b{Note:} keyboard and mouse events can only be delivered once the
 200     main window has been shown.  Attempts to deliver events before then
 201     will fail.  Use the \l when and windowShown properties to track
 202     when the main window has been shown.
 203
 204     \sa SignalSpy
 205 */
 206
 207 /*!
 208     \qmlproperty string TestCase::name
 209
 210     This property defines the name of the test case for result reporting.
 211     The default is the empty string.
 212
 213     \code
 214     TestCase {
 215         name: "ButtonTests"
 216         ...
 217     }
 218     \endcode
 219 */
 220
 221 /*!
 222     \qmlproperty bool TestCase::when
 223
 224     This property should be set to true when the application wants
 225     the test cases to run.  The default value is true.  In the following
 226     example, a test is run when the user presses the mouse button:
 227
 228     \code
 229     Rectangle {
 230         id: foo
 231         width: 640; height: 480
 232         color: "cyan"
 233
 234         MouseArea {
 235             id: area
 236             anchors.fill: parent
 237         }
 238
 239         property bool bar: true
 240
 241         TestCase {
 242             name: "ItemTests"
 243             when: area.pressed
 244             id: test1
 245
 246             function test_bar() {
 247                 verify(bar)
 248             }
 249         }
 250     }
 251     \endcode
 252
 253     The test application will exit once all \l TestCase elements
 254     have been triggered and have run.  The \l optional property can
 255     be used to exclude a \l TestCase element.
 256
 257     \sa optional, completed
 258 */
 259
 260 /*!
 261     \qmlproperty bool TestCase::optional
 262
 263     Multiple \l TestCase elements can be supplied in a test application.
 264     The application will exit once they have all completed.  If a test case
 265     does not need to run (because a precondition has failed), then this
 266     property can be set to true.  The default value is false.
 267
 268     \code
 269     TestCase {
 270         when: false
 271         optional: true
 272         function test_not_run() {
 273             verify(false)
 274         }
 275     }
 276     \endcode
 277
 278     \sa when, completed
 279 */
 280
 281 /*!
 282     \qmlproperty bool TestCase::completed
 283
 284     This property will be set to true once the test case has completed
 285     execution.  Test cases are only executed once.  The initial value
 286     is false.
 287
 288     \sa running, when
 289 */
 290
 291 /*!
 292     \qmlproperty bool TestCase::running
 293
 294     This property will be set to true while the test case is running.
 295     The initial value is false, and the value will become false again
 296     once the test case completes.
 297
 298     \sa completed, when
 299 */
 300
 301 /*!
 302     \qmlproperty bool TestCase::windowShown
 303
 304     This property will be set to true after the QML viewing window has
 305     been displayed.  Normally test cases run as soon as the test application
 306     is loaded and before a window is displayed.  If the test case involves
 307     visual elements and behaviors, then it may need to be delayed until
 308     after the window is shown.
 309
 310     \code
 311     Button {
 312         id: button
 313         onClicked: text = "Clicked"
 314         TestCase {
 315             name: "ClickTest"
 316             when: windowShown
 317             function test_click() {
 318                 button.clicked();
 319                 compare(button.text, "Clicked");
 320             }
 321         }
 322     }
 323     \endcode
 324 */
 325
 326 /*!
 327     \qmlmethod TestCase::fail(message = "")
 328
 329     Fails the current test case, with the optional \a message.
 330     Similar to \c{QFAIL(message)} in C++.
 331 */
 332
 333 /*!
 334     \qmlmethod TestCase::verify(condition, message = "")
 335
 336     Fails the current test case if \a condition is false, and
 337     displays the optional \a message.  Similar to \c{QVERIFY(condition)}
 338     or \c{QVERIFY2(condition, message)} in C++.
 339 */
 340
 341 /*!
 342     \qmlmethod TestCase::compare(actual, expected, message = "")
 343
 344     Fails the current test case if \a actual is not the same as
 345     \a expected, and displays the optional \a message.  Similar
 346     to \c{QCOMPARE(actual, expected)} in C++.
 347
 348     \sa tryCompare(), fuzzyCompare
 349 */
 350
 351
 352 /*!
 353     \qmlmethod TestCase::fuzzyCompare(actual, expected, delta, message = "")
 354
 355     Fails the current test case if the difference betwen \a actual and \a expected
 356     is greater than \a delta, and displays the optional \a message.  Similar
 357     to \c{qFuzzyCompare(actual, expected)} in C++ but with a required \a delta value.
 358
 359     This funtion can also be used for color comparisons if both the \a actual and
 360     \a expected values can be converted into color values. If any of the differences
 361     for RGBA channel values are greater than \a delta, the test fails.
 362
 363     \sa tryCompare(), compare()
 364 */
 365
 366 /*!
 367     \qmlmethod TestCase::tryCompare(obj, property, expected, timeout = 5000)
 368
 369     Fails the current test case if the specified \a property on \a obj
 370     is not the same as \a expected.  The test will be retried multiple
 371     times until the \a timeout (in milliseconds) is reached.
 372
 373     This function is intended for testing applications where a property
 374     changes value based on asynchronous events.  Use compare() for testing
 375     synchronous property changes.
 376
 377     \code
 378     tryCompare(img, "status", BorderImage.Ready)
 379     compare(img.width, 120)
 380     compare(img.height, 120)
 381     compare(img.horizontalTileMode, BorderImage.Stretch)
 382     compare(img.verticalTileMode, BorderImage.Stretch)
 383     \endcode
 384
 385     SignalSpy::wait() provides an alternative method to wait for a
 386     signal to be emitted.
 387
 388     \sa compare(), SignalSpy::wait()
 389 */
 390
 391 /*!
 392     \qmlmethod object TestCase::grabImage(item)
 393
 394     Returns a snapshot image object of the given \a item.
 395
 396     The returned image object has the following methods:
 397     \list
 398     \li red(x, y) Returns the red channel value of the pixel at \a x, \a y position
 399     \li green(x, y) Returns the green channel value of the pixel at \a x, \a y position
 400     \li blue(x, y) Returns the blue channel value of the pixel at \a x, \a y position
 401     \li alpha(x, y) Returns the alpha channel value of the pixel at \a x, \a y position
 402     \li pixel(x, y) Returns the color value of the pixel at \a x, \a y position
 403     For example:
 404
 405     \code
 406     var image = grabImage(rect);
 407     compare(image.red(10, 10), 255);
 408     compare(image.pixel(20, 20), Qt.rgba(255, 0, 0, 255);
 409     \endcode
 410
 411     \endlist
 412
 413     \sa
 414 */
 415
 416 /*!
 417     \qmlmethod TestCase::skip(message = "")
 418
 419     Skips the current test case and prints the optional \a message.
 420     If this is a data-driven test, then only the current row is skipped.
 421     Similar to \c{QSKIP(message)} in C++.
 422 */
 423
 424 /*!
 425     \qmlmethod TestCase::expectFail(tag, message)
 426
 427     In a data-driven test, marks the row associated with \a tag as
 428     expected to fail.  When the fail occurs, display the \a message,
 429     abort the test, and mark the test as passing.  Similar to
 430     \c{QEXPECT_FAIL(tag, message, Abort)} in C++.
 431
 432     If the test is not data-driven, then \a tag must be set to
 433     the empty string.
 434
 435     \sa expectFailContinue()
 436 */
 437
 438 /*!
 439     \qmlmethod TestCase::expectFailContinue(tag, message)
 440
 441     In a data-driven test, marks the row associated with \a tag as
 442     expected to fail.  When the fail occurs, display the \a message,
 443     and then continue the test.  Similar to
 444     \c{QEXPECT_FAIL(tag, message, Continue)} in C++.
 445
 446     If the test is not data-driven, then \a tag must be set to
 447     the empty string.
 448
 449     \sa expectFail()
 450 */
 451
 452 /*!
 453     \qmlmethod TestCase::warn(message)
 454
 455     Prints \a message as a warning message.  Similar to
 456     \c{QWARN(message)} in C++.
 457
 458     \sa ignoreWarning()
 459 */
 460
 461 /*!
 462     \qmlmethod TestCase::ignoreWarning(message)
 463
 464     Marks \a message as an ignored warning message.  When it occurs,
 465     the warning will not be printed and the test passes.  If the message
 466     does not occur, then the test will fail.  Similar to
 467     \c{QTest::ignoreMessage(QtWarningMsg, message)} in C++.
 468
 469     \sa warn()
 470 */
 471
 472 /*!
 473     \qmlmethod TestCase::wait(ms)
 474
 475     Waits for \a ms milliseconds while processing Qt events.
 476
 477     \sa sleep()
 478 */
 479
 480 /*!
 481     \qmlmethod TestCase::sleep(ms)
 482
 483     Sleeps for \a ms milliseconds without processing Qt events.
 484
 485     \sa wait()
 486 */
 487
 488 /*!
 489     \qmlmethod TestCase::keyClick(key, modifiers = Qt.NoModifier, delay = -1)
 490
 491     Simulates clicking of \a key with an optional \a modifier on the currently
 492     focused item.  If \a delay is larger than 0, the test will wait for
 493     \a delay milliseconds.
 494
 495     \sa keyPress(), keyRelease()
 496 */
 497
 498 /*!
 499     \qmlmethod TestCase::keyPress(key, modifiers = Qt.NoModifier, delay = -1)
 500
 501     Simulates pressing a \a key with an optional \a modifier on the currently
 502     focused item.  If \a delay is larger than 0, the test will wait for
 503     \a delay milliseconds.
 504
 505     \b{Note:} At some point you should release the key using keyRelease().
 506
 507     \sa keyRelease(), keyClick()
 508 */
 509
 510 /*!
 511     \qmlmethod TestCase::keyRelease(key, modifiers = Qt.NoModifier, delay = -1)
 512
 513     Simulates releasing a \a key with an optional \a modifier on the currently
 514     focused item.  If \a delay is larger than 0, the test will wait for
 515     \a delay milliseconds.
 516
 517     \sa keyPress(), keyClick()
 518 */
 519
 520 /*!
 521     \qmlmethod TestCase::mousePress(item, x, y, button = Qt.LeftButton, modifiers = Qt.NoModifier, delay = -1)
 522
 523     Simulates pressing a mouse \a button with an optional \a modifier
 524     on an \a item.  The position is defined by \a x and \a y.  If \a delay is
 525     specified, the test will wait for the specified amount of milliseconds
 526     before the press.
 527
 528     The position given by \a x and \a y is transformed from the co-ordinate
 529     system of \a item into window co-ordinates and then delivered.
 530     If \a item is obscured by another item, or a child of \a item occupies
 531     that position, then the event will be delivered to the other item instead.
 532
 533     \sa mouseRelease(), mouseClick(), mouseDoubleClick(), mouseMove(), mouseDrag(), mouseWheel()
 534 */
 535
 536 /*!
 537     \qmlmethod TestCase::mouseRelease(item, x, y, button = Qt.LeftButton, modifiers = Qt.NoModifier, delay = -1)
 538
 539     Simulates releasing a mouse \a button with an optional \a modifier
 540     on an \a item.  The position of the release is defined by \a x and \a y.
 541     If \a delay is specified, the test will wait for the specified amount of
 542     milliseconds before releasing the button.
 543
 544     The position given by \a x and \a y is transformed from the co-ordinate
 545     system of \a item into window co-ordinates and then delivered.
 546     If \a item is obscured by another item, or a child of \a item occupies
 547     that position, then the event will be delivered to the other item instead.
 548
 549     \sa mousePress(), mouseClick(), mouseDoubleClick(), mouseMove(), mouseDrag(), mouseWheel()
 550 */
 551
 552 /*!
 553     \qmlmethod TestCase::mouseClick(item, x, y, button = Qt.LeftButton, modifiers = Qt.NoModifier, delay = -1)
 554
 555     Simulates clicking a mouse \a button with an optional \a modifier
 556     on an \a item.  The position of the click is defined by \a x and \a y.
 557     If \a delay is specified, the test will wait for the specified amount of
 558     milliseconds before pressing and before releasing the button.
 559
 560     The position given by \a x and \a y is transformed from the co-ordinate
 561     system of \a item into window co-ordinates and then delivered.
 562     If \a item is obscured by another item, or a child of \a item occupies
 563     that position, then the event will be delivered to the other item instead.
 564
 565     \sa mousePress(), mouseRelease(), mouseDoubleClick(), mouseMove(), mouseDrag(), mouseWheel()
 566 */
 567
 568 /*!
 569     \qmlmethod TestCase::mouseDoubleClick(item, x, y, button = Qt.LeftButton, modifiers = Qt.NoModifier, delay = -1)
 570
 571     Simulates double-clicking a mouse \a button with an optional \a modifier
 572     on an \a item.  The position of the click is defined by \a x and \a y.
 573     If \a delay is specified, the test will wait for the specified amount of
 574     milliseconds before pressing and before releasing the button.
 575
 576     The position given by \a x and \a y is transformed from the co-ordinate
 577     system of \a item into window co-ordinates and then delivered.
 578     If \a item is obscured by another item, or a child of \a item occupies
 579     that position, then the event will be delivered to the other item instead.
 580
 581     \sa mousePress(), mouseRelease(), mouseClick(), mouseMove(), mouseDrag(), mouseWheel()
 582 */
 583
 584 /*!
 585     \qmlmethod TestCase::mouseMove(item, x, y, delay = -1)
 586
 587     Moves the mouse pointer to the position given by \a x and \a y within
 588     \a item.  If a \a delay (in milliseconds) is given, the test will wait
 589     before moving the mouse pointer.
 590
 591     The position given by \a x and \a y is transformed from the co-ordinate
 592     system of \a item into window co-ordinates and then delivered.
 593     If \a item is obscured by another item, or a child of \a item occupies
 594     that position, then the event will be delivered to the other item instead.
 595
 596     \sa mousePress(), mouseRelease(), mouseClick(), mouseDoubleClick(), mouseDrag(), mouseWheel()
 597 */
 598
 599 /*!
 600     \qmlmethod TestCase::mouseDrag(item, x, y, dx, dy, button = Qt.LeftButton, modifiers = Qt.NoModifier, delay = -1)
 601
 602     Simulates dragging the mouse on an \a item with \a button pressed and an optional \a modifier.
 603     The initial drag position is defined by \a x and \a y,
 604     and drag distance is defined by \a dx and \a dy. If \a delay is specified,
 605     the test will wait for the specified amount of milliseconds before releasing the button.
 606
 607     The position given by \a x and \a y is transformed from the co-ordinate
 608     system of \a item into window co-ordinates and then delivered.
 609     If \a item is obscured by another item, or a child of \a item occupies
 610     that position, then the event will be delivered to the other item instead.
 611
 612     Note: this method does not imply a drop action, to make a drop, an additional
 613     mouseRelease(item, x + dx, y + dy) is needed.
 614
 615     \sa mousePress(), mouseClick(), mouseDoubleClick(), mouseMove(), mouseRelease(), mouseWheel()
 616 */
 617
 618 /*!
 619     \qmlmethod TestCase::mouseWheel(item, x, y, xDelta, yDelta, button = Qt.LeftButton, modifiers = Qt.NoModifier, delay = -1)
 620
 621     Simulates rotating the mouse wheel on an \a item with \a button pressed and an optional \a modifier.
 622     The position of the wheel event is defined by \a x and \a y.
 623     If \a delay is specified, the test will wait for the specified amount of milliseconds before releasing the button.
 624
 625     The position given by \a x and \a y is transformed from the co-ordinate
 626     system of \a item into window co-ordinates and then delivered.
 627     If \a item is obscured by another item, or a child of \a item occupies
 628     that position, then the event will be delivered to the other item instead.
 629
 630     The \a xDelta and \a yDelta contain the wheel rotation distance in eighths of a degree. see \l QWheelEvent::angleDelta() for more details.
 631
 632     \sa mousePress(), mouseClick(), mouseDoubleClick(), mouseMove(), mouseRelease(), mouseDrag(), QWheelEvent::angleDelta()
 633 */
 634
 635 /*!
 636     \qmlmethod TestCase::initTestCase()
 637
 638     This function is called before any other test functions in the
 639     \l TestCase element.  The default implementation does nothing.
 640     The application can provide its own implementation to perform
 641     test case initialization.
 642
 643     \sa cleanupTestCase(), init()
 644 */
 645
 646 /*!
 647     \qmlmethod TestCase::cleanupTestCase()
 648
 649     This function is called after all other test functions in the
 650     \l TestCase element have completed.  The default implementation
 651     does nothing.  The application can provide its own implementation
 652     to perform test case cleanup.
 653
 654     \sa initTestCase(), cleanup()
 655 */
 656
 657 /*!
 658     \qmlmethod TestCase::init()
 659
 660     This function is called before each test function that is
 661     executed in the \l TestCase element.  The default implementation
 662     does nothing.  The application can provide its own implementation
 663     to perform initialization before each test function.
 664
 665     \sa cleanup(), initTestCase()
 666 */
 667
 668 /*!
 669     \qmlmethod TestCase::cleanup()
 670
 671     This function is called after each test function that is
 672     executed in the \l TestCase element.  The default implementation
 673     does nothing.  The application can provide its own implementation
 674     to perform cleanup after each test function.
 675
 676     \sa init(), cleanupTestCase()
 677 */