← Back to branch summary

~loic.molinari/+junk/qtdeclarative-shadereffectsource-changes

« back to all changes in this revision

Viewing changes to src/imports/testlib/testcase.qdoc

  • Committer: Loïc Molinari
  • Date: 2012-04-21 17:59:51 UTC
  • Revision ID: loic.molinari@canonical.com-20120421175951-bqx68caaf5zrp76l
Initial import

Show diffs side-by-side

added added

removed removed

Lines of Context:
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 2.0
 
55
    import QtTest 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". Alternatively, the \c init_data() function can be used
 
101
    to provide default test data for all test functions in a TestCase element:
 
102
 
 
103
 
 
104
    \code
 
105
    import QtQuick 2.0
 
106
    import QtTest 1.0
 
107
 
 
108
    TestCase {
 
109
        name: "DataTests"
 
110
 
 
111
        function init_data() {
 
112
          return [
 
113
               {tag:"init_data_1", a:1, b:2, answer: 3},
 
114
               {tag:"init_data_2", a:2, b:4, answer: 6}
 
115
          ];
 
116
        }
 
117
 
 
118
        function test_table_data() {
 
119
            return [
 
120
                {tag: "2 + 2 = 4", a: 2, b: 2, answer: 4 },
 
121
                {tag: "2 + 6 = 8", a: 2, b: 6, answer: 8 },
 
122
            ]
 
123
        }
 
124
 
 
125
        function test_table(data) {
 
126
            //data comes from test_table_data
 
127
            compare(data.a + data.b, data.answer)
 
128
        }
 
129
 
 
130
        function test__default_table(data) {
 
131
            //data comes from init_data
 
132
            compare(data.a + data.b, data.answer)
 
133
        }
 
134
    }
 
135
    \endcode
 
136
 
 
137
    The test framework will iterate over all of the rows in the table
 
138
    and pass each row to the test function.  As shown, the columns can be
 
139
    extracted for use in the test.  The \c tag column is special - it is
 
140
    printed by the test framework when a row fails, to help the reader
 
141
    identify which case failed amongst a set of otherwise passing tests.
 
142
 
 
143
    \section1 Benchmarks
 
144
 
 
145
    Functions whose names start with "benchmark_" will be run multiple
 
146
    times with the Qt benchmark framework, with an average timing value
 
147
    reported for the runs.  This is equivalent to using the \c{QBENCHMARK}
 
148
    macro in the C++ version of QTestLib.
 
149
 
 
150
    \code
 
151
    TestCase {
 
152
        id: top
 
153
        name: "CreateBenchmark"
 
154
 
 
155
        function benchmark_create_component() {
 
156
            var component = Qt.createComponent("item.qml")
 
157
            var obj = component.createObject(top)
 
158
            obj.destroy()
 
159
            component.destroy()
 
160
        }
 
161
    }
 
162
 
 
163
    RESULT : CreateBenchmark::benchmark_create_component:
 
164
         0.23 msecs per iteration (total: 60, iterations: 256)
 
165
    PASS   : CreateBenchmark::benchmark_create_component()
 
166
    \endcode
 
167
 
 
168
    To get the effect of the \c{QBENCHMARK_ONCE} macro, prefix the test
 
169
    function name with "benchmark_once_".
 
170
 
 
171
    \section1 Simulating keyboard and mouse events
 
172
 
 
173
    The keyPress(), keyRelease(), and keyClick() methods can be used
 
174
    to simulate keyboard events within unit tests.  The events are
 
175
    delivered to the currently focused QML item.
 
176
 
 
177
    \code
 
178
    Rectangle {
 
179
        width: 50; height: 50
 
180
        focus: true
 
181
 
 
182
        TestCase {
 
183
            name: "KeyClick"
 
184
            when: windowShown
 
185
 
 
186
            function test_key_click() {
 
187
                keyClick(Qt.Key_Left)
 
188
                ...
 
189
            }
 
190
        }
 
191
    }
 
192
    \endcode
 
193
 
 
194
    The mousePress(), mouseRelease(), mouseClick(), mouseDoubleClick(),
 
195
    and mouseMove() methods can be used to simulate mouse events in a
 
196
    similar fashion.
 
197
 
 
198
    \b{Note:} keyboard and mouse events can only be delivered once the
 
199
    main window has been shown.  Attempts to deliver events before then
 
200
    will fail.  Use the \l when and windowShown properties to track
 
201
    when the main window has been shown.
 
202
 
 
203
    \sa SignalSpy
 
204
*/
 
205
 
 
206
/*!
 
207
    \qmlproperty string TestCase::name
 
208
 
 
209
    This property defines the name of the test case for result reporting.
 
210
    The default is the empty string.
 
211
 
 
212
    \code
 
213
    TestCase {
 
214
        name: "ButtonTests"
 
215
        ...
 
216
    }
 
217
    \endcode
 
218
*/
 
219
 
 
220
/*!
 
221
    \qmlproperty bool TestCase::when
 
222
 
 
223
    This property should be set to true when the application wants
 
224
    the test cases to run.  The default value is true.  In the following
 
225
    example, a test is run when the user presses the mouse button:
 
226
 
 
227
    \code
 
228
    Rectangle {
 
229
        id: foo
 
230
        width: 640; height: 480
 
231
        color: "cyan"
 
232
 
 
233
        MouseArea {
 
234
            id: area
 
235
            anchors.fill: parent
 
236
        }
 
237
 
 
238
        property bool bar: true
 
239
 
 
240
        TestCase {
 
241
            name: "ItemTests"
 
242
            when: area.pressed
 
243
            id: test1
 
244
 
 
245
            function test_bar() {
 
246
                verify(bar)
 
247
            }
 
248
        }
 
249
    }
 
250
    \endcode
 
251
 
 
252
    The test application will exit once all \l TestCase elements
 
253
    have been triggered and have run.  The \l optional property can
 
254
    be used to exclude a \l TestCase element.
 
255
 
 
256
    \sa optional, completed
 
257
*/
 
258
 
 
259
/*!
 
260
    \qmlproperty bool TestCase::optional
 
261
 
 
262
    Multiple \l TestCase elements can be supplied in a test application.
 
263
    The application will exit once they have all completed.  If a test case
 
264
    does not need to run (because a precondition has failed), then this
 
265
    property can be set to true.  The default value is false.
 
266
 
 
267
    \code
 
268
    TestCase {
 
269
        when: false
 
270
        optional: true
 
271
        function test_not_run() {
 
272
            verify(false)
 
273
        }
 
274
    }
 
275
    \endcode
 
276
 
 
277
    \sa when, completed
 
278
*/
 
279
 
 
280
/*!
 
281
    \qmlproperty bool TestCase::completed
 
282
 
 
283
    This property will be set to true once the test case has completed
 
284
    execution.  Test cases are only executed once.  The initial value
 
285
    is false.
 
286
 
 
287
    \sa running, when
 
288
*/
 
289
 
 
290
/*!
 
291
    \qmlproperty bool TestCase::running
 
292
 
 
293
    This property will be set to true while the test case is running.
 
294
    The initial value is false, and the value will become false again
 
295
    once the test case completes.
 
296
 
 
297
    \sa completed, when
 
298
*/
 
299
 
 
300
/*!
 
301
    \qmlproperty bool TestCase::windowShown
 
302
 
 
303
    This property will be set to true after the QML viewing window has
 
304
    been displayed.  Normally test cases run as soon as the test application
 
305
    is loaded and before a window is displayed.  If the test case involves
 
306
    visual elements and behaviors, then it may need to be delayed until
 
307
    after the window is shown.
 
308
 
 
309
    \code
 
310
    Button {
 
311
        id: button
 
312
        onClicked: text = "Clicked"
 
313
        TestCase {
 
314
            name: "ClickTest"
 
315
            when: windowShown
 
316
            function test_click() {
 
317
                button.clicked();
 
318
                compare(button.text, "Clicked");
 
319
            }
 
320
        }
 
321
    }
 
322
    \endcode
 
323
*/
 
324
 
 
325
/*!
 
326
    \qmlmethod TestCase::fail(message = "")
 
327
 
 
328
    Fails the current test case, with the optional \a message.
 
329
    Similar to \c{QFAIL(message)} in C++.
 
330
*/
 
331
 
 
332
/*!
 
333
    \qmlmethod TestCase::verify(condition, message = "")
 
334
 
 
335
    Fails the current test case if \a condition is false, and
 
336
    displays the optional \a message.  Similar to \c{QVERIFY(condition)}
 
337
    or \c{QVERIFY2(condition, message)} in C++.
 
338
*/
 
339
 
 
340
/*!
 
341
    \qmlmethod TestCase::compare(actual, expected, message = "")
 
342
 
 
343
    Fails the current test case if \a actual is not the same as
 
344
    \a expected, and displays the optional \a message.  Similar
 
345
    to \c{QCOMPARE(actual, expected)} in C++.
 
346
 
 
347
    \sa tryCompare()
 
348
*/
 
349
 
 
350
/*!
 
351
    \qmlmethod TestCase::tryCompare(obj, property, expected, timeout = 5000)
 
352
 
 
353
    Fails the current test case if the specified \a property on \a obj
 
354
    is not the same as \a expected.  The test will be retried multiple
 
355
    times until the \a timeout (in milliseconds) is reached.
 
356
 
 
357
    This function is intended for testing applications where a property
 
358
    changes value based on asynchronous events.  Use compare() for testing
 
359
    synchronous property changes.
 
360
 
 
361
    \code
 
362
    tryCompare(img, "status", BorderImage.Ready)
 
363
    compare(img.width, 120)
 
364
    compare(img.height, 120)
 
365
    compare(img.horizontalTileMode, BorderImage.Stretch)
 
366
    compare(img.verticalTileMode, BorderImage.Stretch)
 
367
    \endcode
 
368
 
 
369
    SignalSpy::wait() provides an alternative method to wait for a
 
370
    signal to be emitted.
 
371
 
 
372
    \sa compare(), SignalSpy::wait()
 
373
*/
 
374
 
 
375
/*!
 
376
    \qmlmethod TestCase::skip(message = "")
 
377
 
 
378
    Skips the current test case and prints the optional \a message.
 
379
    If this is a data-driven test, then only the current row is skipped.
 
380
    Similar to \c{QSKIP(message)} in C++.
 
381
*/
 
382
 
 
383
/*!
 
384
    \qmlmethod TestCase::expectFail(tag, message)
 
385
 
 
386
    In a data-driven test, marks the row associated with \a tag as
 
387
    expected to fail.  When the fail occurs, display the \a message,
 
388
    abort the test, and mark the test as passing.  Similar to
 
389
    \c{QEXPECT_FAIL(tag, message, Abort)} in C++.
 
390
 
 
391
    If the test is not data-driven, then \a tag must be set to
 
392
    the empty string.
 
393
 
 
394
    \sa expectFailContinue()
 
395
*/
 
396
 
 
397
/*!
 
398
    \qmlmethod TestCase::expectFailContinue(tag, message)
 
399
 
 
400
    In a data-driven test, marks the row associated with \a tag as
 
401
    expected to fail.  When the fail occurs, display the \a message,
 
402
    and then continue the test.  Similar to
 
403
    \c{QEXPECT_FAIL(tag, message, Continue)} in C++.
 
404
 
 
405
    If the test is not data-driven, then \a tag must be set to
 
406
    the empty string.
 
407
 
 
408
    \sa expectFail()
 
409
*/
 
410
 
 
411
/*!
 
412
    \qmlmethod TestCase::warn(message)
 
413
 
 
414
    Prints \a message as a warning message.  Similar to
 
415
    \c{QWARN(message)} in C++.
 
416
 
 
417
    \sa ignoreWarning()
 
418
*/
 
419
 
 
420
/*!
 
421
    \qmlmethod TestCase::ignoreWarning(message)
 
422
 
 
423
    Marks \a message as an ignored warning message.  When it occurs,
 
424
    the warning will not be printed and the test passes.  If the message
 
425
    does not occur, then the test will fail.  Similar to
 
426
    \c{QTest::ignoreMessage(QtWarningMsg, message)} in C++.
 
427
 
 
428
    \sa warn()
 
429
*/
 
430
 
 
431
/*!
 
432
    \qmlmethod TestCase::wait(ms)
 
433
 
 
434
    Waits for \a ms milliseconds while processing Qt events.
 
435
 
 
436
    \sa sleep()
 
437
*/
 
438
 
 
439
/*!
 
440
    \qmlmethod TestCase::sleep(ms)
 
441
 
 
442
    Sleeps for \a ms milliseconds without processing Qt events.
 
443
 
 
444
    \sa wait()
 
445
*/
 
446
 
 
447
/*!
 
448
    \qmlmethod TestCase::keyClick(key, modifiers = Qt.NoModifier, delay = -1)
 
449
 
 
450
    Simulates clicking of \a key with an optional \a modifier on the currently
 
451
    focused item.  If \a delay is larger than 0, the test will wait for
 
452
    \a delay milliseconds.
 
453
 
 
454
    \sa keyPress(), keyRelease()
 
455
*/
 
456
 
 
457
/*!
 
458
    \qmlmethod TestCase::keyPress(key, modifiers = Qt.NoModifier, delay = -1)
 
459
 
 
460
    Simulates pressing a \a key with an optional \a modifier on the currently
 
461
    focused item.  If \a delay is larger than 0, the test will wait for
 
462
    \a delay milliseconds.
 
463
 
 
464
    \b{Note:} At some point you should release the key using keyRelease().
 
465
 
 
466
    \sa keyRelease(), keyClick()
 
467
*/
 
468
 
 
469
/*!
 
470
    \qmlmethod TestCase::keyRelease(key, modifiers = Qt.NoModifier, delay = -1)
 
471
 
 
472
    Simulates releasing a \a key with an optional \a modifier on the currently
 
473
    focused item.  If \a delay is larger than 0, the test will wait for
 
474
    \a delay milliseconds.
 
475
 
 
476
    \sa keyPress(), keyClick()
 
477
*/
 
478
 
 
479
/*!
 
480
    \qmlmethod TestCase::mousePress(item, x, y, button = Qt.LeftButton, modifiers = Qt.NoModifier, delay = -1)
 
481
 
 
482
    Simulates pressing a mouse \a button with an optional \a modifier
 
483
    on an \a item.  The position is defined by \a x and \a y.  If \a delay is
 
484
    specified, the test will wait for the specified amount of milliseconds
 
485
    before the press.
 
486
 
 
487
    The position given by \a x and \a y is transformed from the co-ordinate
 
488
    system of \a item into window co-ordinates and then delivered.
 
489
    If \a item is obscured by another item, or a child of \a item occupies
 
490
    that position, then the event will be delivered to the other item instead.
 
491
 
 
492
    \sa mouseRelease(), mouseClick(), mouseDoubleClick(), mouseMove()
 
493
*/
 
494
 
 
495
/*!
 
496
    \qmlmethod TestCase::mouseRelease(item, x, y, button = Qt.LeftButton, modifiers = Qt.NoModifier, delay = -1)
 
497
 
 
498
    Simulates releasing a mouse \a button with an optional \a modifier
 
499
    on an \a item.  The position of the release is defined by \a x and \a y.
 
500
    If \a delay is specified, the test will wait for the specified amount of
 
501
    milliseconds before releasing the button.
 
502
 
 
503
    The position given by \a x and \a y is transformed from the co-ordinate
 
504
    system of \a item into window co-ordinates and then delivered.
 
505
    If \a item is obscured by another item, or a child of \a item occupies
 
506
    that position, then the event will be delivered to the other item instead.
 
507
 
 
508
    \sa mousePress(), mouseClick(), mouseDoubleClick(), mouseMove()
 
509
*/
 
510
 
 
511
/*!
 
512
    \qmlmethod TestCase::mouseClick(item, x, y, button = Qt.LeftButton, modifiers = Qt.NoModifier, delay = -1)
 
513
 
 
514
    Simulates clicking a mouse \a button with an optional \a modifier
 
515
    on an \a item.  The position of the click is defined by \a x and \a y.
 
516
    If \a delay is specified, the test will wait for the specified amount of
 
517
    milliseconds before pressing and before releasing the button.
 
518
 
 
519
    The position given by \a x and \a y is transformed from the co-ordinate
 
520
    system of \a item into window co-ordinates and then delivered.
 
521
    If \a item is obscured by another item, or a child of \a item occupies
 
522
    that position, then the event will be delivered to the other item instead.
 
523
 
 
524
    \sa mousePress(), mouseRelease(), mouseDoubleClick(), mouseMove()
 
525
*/
 
526
 
 
527
/*!
 
528
    \qmlmethod TestCase::mouseDoubleClick(item, x, y, button = Qt.LeftButton, modifiers = Qt.NoModifier, delay = -1)
 
529
 
 
530
    Simulates double-clicking a mouse \a button with an optional \a modifier
 
531
    on an \a item.  The position of the click is defined by \a x and \a y.
 
532
    If \a delay is specified, the test will wait for the specified amount of
 
533
    milliseconds before pressing and before releasing the button.
 
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(), mouseMove()
 
541
*/
 
542
 
 
543
/*!
 
544
    \qmlmethod TestCase::mouseMove(item, x, y, delay = -1)
 
545
 
 
546
    Moves the mouse pointer to the position given by \a x and \a y within
 
547
    \a item.  If a \a delay (in milliseconds) is given, the test will wait
 
548
    before moving the mouse pointer.
 
549
 
 
550
    The position given by \a x and \a y is transformed from the co-ordinate
 
551
    system of \a item into window co-ordinates and then delivered.
 
552
    If \a item is obscured by another item, or a child of \a item occupies
 
553
    that position, then the event will be delivered to the other item instead.
 
554
 
 
555
    \sa mousePress(), mouseRelease(), mouseClick(), mouseDoubleClick()
 
556
*/
 
557
 
 
558
/*!
 
559
    \qmlmethod TestCase::initTestCase()
 
560
 
 
561
    This function is called before any other test functions in the
 
562
    \l TestCase element.  The default implementation does nothing.
 
563
    The application can provide its own implementation to perform
 
564
    test case initialization.
 
565
 
 
566
    \sa cleanupTestCase(), init()
 
567
*/
 
568
 
 
569
/*!
 
570
    \qmlmethod TestCase::cleanupTestCase()
 
571
 
 
572
    This function is called after all other test functions in the
 
573
    \l TestCase element have completed.  The default implementation
 
574
    does nothing.  The application can provide its own implementation
 
575
    to perform test case cleanup.
 
576
 
 
577
    \sa initTestCase(), cleanup()
 
578
*/
 
579
 
 
580
/*!
 
581
    \qmlmethod TestCase::init()
 
582
 
 
583
    This function is called before each test function that is
 
584
    executed in the \l TestCase element.  The default implementation
 
585
    does nothing.  The application can provide its own implementation
 
586
    to perform initialization before each test function.
 
587
 
 
588
    \sa cleanup(), initTestCase()
 
589
*/
 
590
 
 
591
/*!
 
592
    \qmlmethod TestCase::cleanup()
 
593
 
 
594
    This function is called after each test function that is
 
595
    executed in the \l TestCase element.  The default implementation
 
596
    does nothing.  The application can provide its own implementation
 
597
    to perform cleanup after each test function.
 
598
 
 
599
    \sa init(), cleanupTestCase()
 
600
*/