Warning: That file was not part of the compilation database. It may have many parsing errors.

1/****************************************************************************
2**
3** Copyright (C) 2016 The Qt Company Ltd.
4** Contact: https://www.qt.io/licensing/
5**
6** This file is part of the documentation of the Qt Toolkit.
7**
8** $QT_BEGIN_LICENSE:FDL$
9** Commercial License Usage
10** Licensees holding valid commercial Qt licenses may use this file in
11** accordance with the commercial license agreement provided with the
12** Software or, alternatively, in accordance with the terms contained in
13** a written agreement between you and The Qt Company. For licensing terms
14** and conditions see https://www.qt.io/terms-conditions. For further
15** information use the contact form at https://www.qt.io/contact-us.
16**
17** GNU Free Documentation License Usage
18** Alternatively, this file may be used under the terms of the GNU Free
19** Documentation License version 1.3 as published by the Free Software
20** Foundation and appearing in the file included in the packaging of
21** this file. Please review the following information to ensure
22** the GNU Free Documentation License version 1.3 requirements
23** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
24** $QT_END_LICENSE$
25**
26****************************************************************************/
27
28/*!
29 \namespace QTest
30 \inmodule QtTest
31
32 \brief The QTest namespace contains all the functions and
33 declarations that are related to Qt Test.
34
35 See the \l{Qt Test Overview} for information about how to write unit tests.
36*/
37
38/*! \macro QVERIFY(condition)
39
40 \relates QTest
41
42 The QVERIFY() macro checks whether the \a condition is true or not. If it is
43 true, execution continues. If not, a failure is recorded in the test log
44 and the test won't be executed further.
45
46 \b {Note:} This macro can only be used in a test function that is invoked
47 by the test framework.
48
49 Example:
50 \snippet code/src_qtestlib_qtestcase.cpp 0
51
52 \sa QCOMPARE(), QTRY_VERIFY()
53*/
54
55/*! \macro QVERIFY2(condition, message)
56
57 \relates QTest
58
59 The QVERIFY2() macro behaves exactly like QVERIFY(), except that it outputs
60 a verbose \a message when \a condition is false. The \a message is a plain
61 C string.
62
63 Example:
64 \snippet code/src_qtestlib_qtestcase.cpp 1
65
66 \sa QVERIFY(), QCOMPARE()
67*/
68
69/*! \macro QCOMPARE(actual, expected)
70
71 \relates QTest
72
73 The QCOMPARE macro compares an \a actual value to an \a expected value using
74 the equals operator. If \a actual and \a expected are identical, execution
75 continues. If not, a failure is recorded in the test log and the test
76 won't be executed further.
77
78 In the case of comparing floats and doubles, qFuzzyCompare() is used for
79 comparing. This means that comparing to 0 will likely fail. One solution
80 to this is to compare to 1, and add 1 to the produced output.
81
82 QCOMPARE tries to output the contents of the values if the comparison fails,
83 so it is visible from the test log why the comparison failed.
84
85 For your own classes, you can use \l QTest::toString() to format values for
86 outputting into the test log.
87
88 \note This macro can only be used in a test function that is invoked
89 by the test framework.
90
91 Example:
92 \snippet code/src_qtestlib_qtestcase.cpp 2
93
94 \sa QVERIFY(), QTRY_COMPARE(), QTest::toString()
95*/
96
97/*! \macro QVERIFY_EXCEPTION_THROWN(expression, exceptiontype)
98 \since 5.3
99
100 \relates QTest
101
102 The QVERIFY_EXCEPTION_THROWN macro executes an \a expression and tries
103 to catch an exception thrown from the \a expression. If the \a expression
104 throws an exception and its type is the same as \a exceptiontype
105 or \a exceptiontype is substitutable with the type of thrown exception
106 (i.e. usually the type of thrown exception is publicly derived
107 from \a exceptiontype) then execution will be continued. If not-substitutable
108 type of exception is thrown or the \a expression doesn't throw an exception
109 at all, then a failure will be recorded in the test log and
110 the test won't be executed further.
111
112 \note This macro can only be used in a test function that is invoked
113 by the test framework.
114*/
115
116/*! \macro QTRY_VERIFY_WITH_TIMEOUT(condition, timeout)
117 \since 5.0
118
119 \relates QTest
120
121 The QTRY_VERIFY_WITH_TIMEOUT() macro is similar to QVERIFY(), but checks the \a condition
122 repeatedly, until either the condition becomes true or the \a timeout (in milliseconds) is
123 reached. Between each evaluation, events will be processed. If the timeout
124 is reached, a failure is recorded in the test log and the test won't be
125 executed further.
126
127 \note This macro can only be used in a test function that is invoked
128 by the test framework.
129
130 \sa QTRY_VERIFY(), QTRY_VERIFY2_WITH_TIMEOUT(), QVERIFY(), QCOMPARE(), QTRY_COMPARE()
131*/
132
133
134/*! \macro QTRY_VERIFY(condition)
135 \since 5.0
136
137 \relates QTest
138
139 Checks the \a condition by invoking QTRY_VERIFY_WITH_TIMEOUT() with a timeout of five seconds.
140
141 \note This macro can only be used in a test function that is invoked
142 by the test framework.
143
144 \sa QTRY_VERIFY_WITH_TIMEOUT(), QTRY_VERIFY2(), QVERIFY(), QCOMPARE(), QTRY_COMPARE()
145*/
146
147/*! \macro QTRY_VERIFY2_WITH_TIMEOUT(condition, message, timeout)
148 \since 5.6
149
150 \relates QTest
151
152 The QTRY_VERIFY2_WITH_TIMEOUT macro is similar to QTRY_VERIFY_WITH_TIMEOUT()
153 except that it outputs a verbose \a message when \a condition is still false
154 after the specified \a timeout (in milliseconds). The \a message is a plain C string.
155
156 Example:
157 \code
158 QTRY_VERIFY2_WITH_TIMEOUT(list.size() > 2, QByteArray::number(list.size()).constData(), 10000);
159 \endcode
160
161 \note This macro can only be used in a test function that is invoked
162 by the test framework.
163
164 \sa QTRY_VERIFY(), QTRY_VERIFY_WITH_TIMEOUT(), QVERIFY(), QCOMPARE(), QTRY_COMPARE()
165*/
166
167/*! \macro QTRY_VERIFY2(condition, message)
168 \since 5.6
169
170 \relates QTest
171
172 Checks the \a condition by invoking QTRY_VERIFY2_WITH_TIMEOUT() with a timeout
173 of five seconds. If \a condition is then still false, \a message is output.
174 The \a message is a plain C string.
175
176 Example:
177 \code
178 QTRY_VERIFY2_WITH_TIMEOUT(list.size() > 2, QByteArray::number(list.size()).constData());
179 \endcode
180
181 \note This macro can only be used in a test function that is invoked
182 by the test framework.
183
184 \sa QTRY_VERIFY2_WITH_TIMEOUT(), QTRY_VERIFY2(), QVERIFY(), QCOMPARE(), QTRY_COMPARE()
185*/
186
187/*! \macro QTRY_COMPARE_WITH_TIMEOUT(actual, expected, timeout)
188 \since 5.0
189
190 \relates QTest
191
192 The QTRY_COMPARE_WITH_TIMEOUT() macro is similar to QCOMPARE(), but performs the comparison
193 of the \a actual and \a expected values repeatedly, until either the two values
194 are equal or the \a timeout (in milliseconds) is reached. Between each comparison, events
195 will be processed. If the timeout is reached, a failure is recorded in the
196 test log and the test won't be executed further.
197
198 \note This macro can only be used in a test function that is invoked
199 by the test framework.
200
201 \sa QTRY_COMPARE(), QCOMPARE(), QVERIFY(), QTRY_VERIFY()
202*/
203
204/*! \macro QTRY_COMPARE(actual, expected)
205 \since 5.0
206
207 \relates QTest
208
209 Performs a comparison of the \a actual and \a expected values by
210 invoking QTRY_COMPARE_WITH_TIMEOUT() with a timeout of five seconds.
211
212 \note This macro can only be used in a test function that is invoked
213 by the test framework.
214
215 \sa QTRY_COMPARE_WITH_TIMEOUT(), QCOMPARE(), QVERIFY(), QTRY_VERIFY()
216*/
217
218/*! \macro QFETCH(type, name)
219
220 \relates QTest
221
222 The fetch macro creates a local variable named \a name with the type \a type
223 on the stack. \a name has to match the element name from the test's data.
224 If no such element exists, the test will assert.
225
226 Assuming a test has the following data:
227
228 \snippet code/src_qtestlib_qtestcase.cpp 3
229
230 The test data has two elements, a QString called \c aString and an integer
231 called \c expected. To fetch these values in the actual test:
232
233 \snippet code/src_qtestlib_qtestcase.cpp 4
234
235 \c aString and \c expected are variables on the stack that are initialized with
236 the current test data.
237
238 \b {Note:} This macro can only be used in a test function that is invoked
239 by the test framework. The test function must have a _data function.
240*/
241
242/*! \macro QWARN(message)
243
244 \relates QTest
245 \threadsafe
246
247 Appends \a message as a warning to the test log. This macro can be used anywhere
248 in your tests.
249*/
250
251/*! \macro QFAIL(message)
252
253 \relates QTest
254
255 This macro can be used to force a test failure. The test stops
256 executing and the failure \a message is appended to the test log.
257
258 \b {Note:} This macro can only be used in a test function that is invoked
259 by the test framework.
260
261 Example:
262
263 \snippet code/src_qtestlib_qtestcase.cpp 5
264*/
265
266/*! \macro QTEST(actual, testElement)
267
268 \relates QTest
269
270 QTEST() is a convenience macro for \l QCOMPARE() that compares
271 the value \a actual with the element \a testElement from the test's data.
272 If there is no such element, the test asserts.
273
274 Apart from that, QTEST() behaves exactly as \l QCOMPARE().
275
276 Instead of writing:
277
278 \snippet code/src_qtestlib_qtestcase.cpp 6
279
280 you can write:
281
282 \snippet code/src_qtestlib_qtestcase.cpp 7
283
284 \sa QCOMPARE()
285*/
286
287/*! \macro QSKIP(description)
288
289 \relates QTest
290
291 If called from a test function, the QSKIP() macro stops execution of the test
292 without adding a failure to the test log. You can use it to skip tests that
293 wouldn't make sense in the current configuration. The text \a description is
294 appended to the test log and should contain an explanation of why the test
295 couldn't be executed.
296
297 If the test is data-driven, each call to QSKIP() will skip only the current
298 row of test data, so an unconditional call to QSKIP will produce one skip
299 message in the test log for each row of test data.
300
301 If called from an _data function, the QSKIP() macro will stop execution of
302 the _data function and will prevent execution of the associated test
303 function.
304
305 If called from initTestCase() or initTestCase_data(), the QSKIP() macro will
306 skip all test and _data functions.
307
308 \b {Note:} This macro can only be used in a test function or _data
309 function that is invoked by the test framework.
310
311 Example:
312 \snippet code/src_qtestlib_qtestcase.cpp 8
313*/
314
315/*! \macro QEXPECT_FAIL(dataIndex, comment, mode)
316
317 \relates QTest
318
319 The QEXPECT_FAIL() macro marks the next \l QCOMPARE() or \l QVERIFY() as an
320 expected failure. Instead of adding a failure to the test log, an expected
321 failure will be reported.
322
323 If a \l QVERIFY() or \l QCOMPARE() is marked as an expected failure,
324 but passes instead, an unexpected pass (XPASS) is written to the test log.
325
326 The parameter \a dataIndex describes for which entry in the test data the
327 failure is expected. Pass an empty string (\c{""}) if the failure
328 is expected for all entries or if no test data exists.
329
330 \a comment will be appended to the test log for the expected failure.
331
332 \a mode is a \l QTest::TestFailMode and sets whether the test should
333 continue to execute or not.
334
335 \b {Note:} This macro can only be used in a test function that is invoked
336 by the test framework.
337
338 Example 1:
339 \snippet code/src_qtestlib_qtestcase.cpp 9
340
341 In the example above, an expected fail will be written into the test output
342 if the variable \c i is not 42. If the variable \c i is 42, an unexpected pass
343 is written instead. The QEXPECT_FAIL() has no influence on the second QCOMPARE()
344 statement in the example.
345
346 Example 2:
347 \snippet code/src_qtestlib_qtestcase.cpp 10
348
349 The above testfunction will not continue executing for the test data
350 entry \c{data27}.
351
352 \sa QTest::TestFailMode, QVERIFY(), QCOMPARE()
353*/
354
355/*! \macro QFINDTESTDATA(filename)
356 \since 5.0
357
358 \relates QTest
359
360 Returns a QString for the testdata file referred to by \a filename, or an
361 empty QString if the testdata file could not be found.
362
363 This macro allows the test to load data from an external file without
364 hardcoding an absolute filename into the test, or using relative paths
365 which may be error prone.
366
367 The returned path will be the first path from the following list which
368 resolves to an existing file or directory:
369
370 \list
371 \li \a filename relative to QCoreApplication::applicationDirPath()
372 (only if a QCoreApplication or QApplication object has been created).
373 \li \a filename relative to the test's standard install directory
374 (QLibraryInfo::TestsPath with the lowercased testcase name appended).
375 \li \a filename relative to the directory containing the source file from which
376 QFINDTESTDATA is invoked.
377 \endlist
378
379 If the named file/directory does not exist at any of these locations,
380 a warning is printed to the test log.
381
382 For example, in this code:
383 \snippet code/src_qtestlib_qtestcase.cpp 26
384
385 The testdata file will be resolved as the first existing file from:
386
387 \list
388 \li \c{/home/user/build/myxmlparser/tests/tst_myxmlparser/testxml/simple1.xml}
389 \li \c{/usr/local/Qt-5.0.0/tests/tst_myxmlparser/testxml/simple1.xml}
390 \li \c{/home/user/sources/myxmlparser/tests/tst_myxmlparser/testxml/simple1.xml}
391 \endlist
392
393 This allows the test to find its testdata regardless of whether the
394 test has been installed, and regardless of whether the test's build tree
395 is equal to the test's source tree.
396
397 \b {Note:} reliable detection of testdata from the source directory requires
398 either that qmake is used, or the \c{QT_TESTCASE_BUILDDIR} macro is defined to
399 point to the working directory from which the compiler is invoked, or only
400 absolute paths to the source files are passed to the compiler. Otherwise, the
401 absolute path of the source directory cannot be determined.
402
403 \b {Note:} For tests that use the \l QTEST_APPLESS_MAIN() macro to generate a
404 \c{main()} function, \c{QFINDTESTDATA} will not attempt to find test data
405 relative to QCoreApplication::applicationDirPath(). In practice, this means that
406 tests using \c{QTEST_APPLESS_MAIN()} will fail to find their test data
407 if run from a shadow build tree.
408*/
409
410/*! \macro QTEST_MAIN(TestClass)
411
412 \relates QTest
413
414 Implements a main() function that instantiates an application object and
415 the \a TestClass, and executes all tests in the order they were defined.
416 Use this macro to build stand-alone executables.
417
418 If \c QT_WIDGETS_LIB is defined, the application object will be a QApplication,
419 if \c QT_GUI_LIB is defined, the application object will be a QGuiApplication,
420 otherwise it will be a QCoreApplication. If qmake is used and the configuration
421 includes \c{QT += widgets}, then \c QT_WIDGETS_LIB will be defined automatically.
422 Similarly, if qmake is used and the configuration includes \c{QT += gui}, then
423 \c QT_GUI_LIB will be defined automatically.
424
425 \b {Note:} On platforms that have keypad navigation enabled by default,
426 this macro will forcefully disable it if \c QT_WIDGETS_LIB is defined. This is done
427 to simplify the usage of key events when writing autotests. If you wish to write a
428 test case that uses keypad navigation, you should enable it either in the
429 \c {initTestCase()} or \c {init()} functions of your test case by calling
430 \l {QApplication::setNavigationMode()}.
431
432 Example:
433 \snippet code/src_qtestlib_qtestcase.cpp 11
434
435 \sa QTEST_APPLESS_MAIN(), QTEST_GUILESS_MAIN(), QTest::qExec(),
436 QApplication::setNavigationMode()
437*/
438
439/*! \macro QTEST_APPLESS_MAIN(TestClass)
440
441 \relates QTest
442
443 Implements a main() function that executes all tests in \a TestClass.
444
445 Behaves like \l QTEST_MAIN(), but doesn't instantiate a QApplication
446 object. Use this macro for really simple stand-alone non-GUI tests.
447
448 \sa QTEST_MAIN()
449*/
450
451/*! \macro QTEST_GUILESS_MAIN(TestClass)
452 \since 5.0
453
454 \relates QTest
455
456 Implements a main() function that instantiates a QCoreApplication object
457 and the \a TestClass, and executes all tests in the order they were
458 defined. Use this macro to build stand-alone executables.
459
460 Behaves like \l QTEST_MAIN(), but instantiates a QCoreApplication instead
461 of the QApplication object. Use this macro if your test case doesn't need
462 functionality offered by QApplication, but the event loop is still necessary.
463
464 \sa QTEST_MAIN()
465*/
466
467/*!
468 \macro QBENCHMARK
469
470 \relates QTest
471
472 This macro is used to measure the performance of code within a test.
473 The code to be benchmarked is contained within a code block following
474 this macro.
475
476 For example:
477
478 \snippet code/src_qtestlib_qtestcase.cpp 27
479
480 \sa {Qt Test Overview#Creating a Benchmark}{Creating a Benchmark},
481 {Chapter 5: Writing a Benchmark}{Writing a Benchmark}
482*/
483
484/*!
485 \macro QBENCHMARK_ONCE
486 \since 4.6
487
488 \relates QTest
489
490 \brief The QBENCHMARK_ONCE macro is for measuring performance of a
491 code block by running it once.
492
493 This macro is used to measure the performance of code within a test.
494 The code to be benchmarked is contained within a code block following
495 this macro.
496
497 Unlike QBENCHMARK, the contents of the contained code block is only run
498 once. The elapsed time will be reported as "0" if it's to short to
499 be measured by the selected backend. (Use)
500
501 \sa {Qt Test Overview#Creating a Benchmark}{Creating a Benchmark},
502 {Chapter 5: Writing a Benchmark}{Writing a Benchmark}
503*/
504
505/*! \enum QTest::TestFailMode
506
507 This enum describes the modes for handling an expected failure of the
508 \l QVERIFY() or \l QCOMPARE() macros.
509
510 \value Abort Aborts the execution of the test. Use this mode when it
511 doesn't make sense to execute the test any further after the
512 expected failure.
513
514 \value Continue Continues execution of the test after the expected failure.
515
516 \sa QEXPECT_FAIL()
517*/
518
519/*! \enum QTest::KeyAction
520
521 This enum describes possible actions for key handling.
522
523 \value Press The key is pressed.
524 \value Release The key is released.
525 \value Click The key is clicked (pressed and released).
526 \value Shortcut A shortcut is activated. This value has been added in Qt 5.6.
527*/
528
529/*! \enum QTest::MouseAction
530
531 This enum describes possible actions for mouse handling.
532
533 \value MousePress A mouse button is pressed.
534 \value MouseRelease A mouse button is released.
535 \value MouseClick A mouse button is clicked (pressed and released).
536 \value MouseDClick A mouse button is double clicked (pressed and released twice).
537 \value MouseMove The mouse pointer has moved.
538*/
539
540/*! \fn void QTest::keyClick(QWidget *widget, Qt::Key key, Qt::KeyboardModifiers modifier = Qt::NoModifier, int delay=-1)
541
542 Simulates clicking of \a key with an optional \a modifier on a \a widget.
543 If \a delay is larger than 0, the test will wait for \a delay milliseconds
544 before clicking the key.
545
546 Examples:
547 \snippet code/src_qtestlib_qtestcase.cpp 14
548
549 The first example above simulates clicking the \c escape key on \c
550 myWidget without any keyboard modifiers and without delay. The
551 second example simulates clicking \c shift-escape on \c myWidget
552 following a 200 ms delay of the test.
553
554 \sa QTest::keyClicks()
555*/
556
557/*! \fn void QTest::keyClick(QWidget *widget, char key, Qt::KeyboardModifiers modifier = Qt::NoModifier, int delay=-1)
558 \overload
559
560 Simulates clicking of \a key with an optional \a modifier on a \a widget.
561 If \a delay is larger than 0, the test will wait for \a delay milliseconds
562 before clicking the key.
563
564 Example:
565 \snippet code/src_qtestlib_qtestcase.cpp 13
566
567 The example above simulates clicking \c a on \c myWidget without
568 any keyboard modifiers and without delay of the test.
569
570 \sa QTest::keyClicks()
571*/
572
573/*! \fn void QTest::keySequence(QWidget *widget, const QKeySequence &keySequence)
574 \overload
575 \since 5.10
576
577 Simulates typing of \a keySequence into a \a widget.
578
579 \sa QTest::keyClick(), QTest::keyClicks()
580*/
581
582/*! \fn void QTest::keyClick(QWindow *window, Qt::Key key, Qt::KeyboardModifiers modifier = Qt::NoModifier, int delay=-1)
583 \overload
584 \since 5.0
585
586 Simulates clicking of \a key with an optional \a modifier on a \a window.
587 If \a delay is larger than 0, the test will wait for \a delay milliseconds
588 before clicking the key.
589
590 Examples:
591 \snippet code/src_qtestlib_qtestcase.cpp 29
592
593 The first example above simulates clicking the \c escape key on \c
594 myWindow without any keyboard modifiers and without delay. The
595 second example simulates clicking \c shift-escape on \c myWindow
596 following a 200 ms delay of the test.
597
598 \sa QTest::keyClicks()
599*/
600
601/*! \fn void QTest::keyClick(QWindow *window, char key, Qt::KeyboardModifiers modifier = Qt::NoModifier, int delay=-1)
602 \overload
603 \since 5.0
604
605 Simulates clicking of \a key with an optional \a modifier on a \a window.
606 If \a delay is larger than 0, the test will wait for \a delay milliseconds
607 before clicking the key.
608
609 Example:
610 \snippet code/src_qtestlib_qtestcase.cpp 28
611
612 The example above simulates clicking \c a on \c myWindow without
613 any keyboard modifiers and without delay of the test.
614
615 \sa QTest::keyClicks()
616*/
617
618/*! \fn void QTest::keySequence(QWindow *window, const QKeySequence &keySequence)
619 \overload
620 \since 5.10
621
622 Simulates typing of \a keySequence into a \a window.
623
624 \sa QTest::keyClick(), QTest::keyClicks()
625*/
626
627/*! \fn void QTest::keyEvent(KeyAction action, QWidget *widget, Qt::Key key, Qt::KeyboardModifiers modifier = Qt::NoModifier, int delay=-1)
628
629 Sends a Qt key event to \a widget with the given \a key and an associated \a action.
630 Optionally, a keyboard \a modifier can be specified, as well as a \a delay
631 (in milliseconds) of the test before sending the event.
632*/
633
634/*! \fn void QTest::keyEvent(KeyAction action, QWidget *widget, char ascii, Qt::KeyboardModifiers modifier = Qt::NoModifier, int delay=-1)
635 \overload
636
637 Sends a Qt key event to \a widget with the given key \a ascii and an associated \a action.
638 Optionally, a keyboard \a modifier can be specified, as well as a \a delay
639 (in milliseconds) of the test before sending the event.
640*/
641
642/*! \fn void QTest::keyEvent(KeyAction action, QWindow *window, Qt::Key key, Qt::KeyboardModifiers modifier = Qt::NoModifier, int delay=-1)
643 \overload
644 \since 5.0
645
646 Sends a Qt key event to \a window with the given \a key and an associated \a action.
647 Optionally, a keyboard \a modifier can be specified, as well as a \a delay
648 (in milliseconds) of the test before sending the event.
649*/
650
651/*! \fn void QTest::keyEvent(KeyAction action, QWindow *window, char ascii, Qt::KeyboardModifiers modifier = Qt::NoModifier, int delay=-1)
652 \overload
653 \since 5.0
654
655 Sends a Qt key event to \a window with the given key \a ascii and an associated \a action.
656 Optionally, a keyboard \a modifier can be specified, as well as a \a delay
657 (in milliseconds) of the test before sending the event.
658*/
659
660/*! \fn void QTest::keyPress(QWidget *widget, Qt::Key key, Qt::KeyboardModifiers modifier = Qt::NoModifier, int delay=-1)
661
662 Simulates pressing a \a key with an optional \a modifier on a \a widget. If \a delay
663 is larger than 0, the test will wait for \a delay milliseconds before pressing the key.
664
665 \b {Note:} At some point you should release the key using \l keyRelease().
666
667 \sa QTest::keyRelease(), QTest::keyClick()
668*/
669
670/*! \fn void QTest::keyPress(QWidget *widget, char key, Qt::KeyboardModifiers modifier = Qt::NoModifier, int delay=-1)
671 \overload
672
673 Simulates pressing a \a key with an optional \a modifier on a \a widget.
674 If \a delay is larger than 0, the test will wait for \a delay milliseconds
675 before pressing the key.
676
677 \b {Note:} At some point you should release the key using \l keyRelease().
678
679 \sa QTest::keyRelease(), QTest::keyClick()
680*/
681
682/*! \fn void QTest::keyPress(QWindow *window, Qt::Key key, Qt::KeyboardModifiers modifier = Qt::NoModifier, int delay=-1)
683 \overload
684 \since 5.0
685
686 Simulates pressing a \a key with an optional \a modifier on a \a window. If \a delay
687 is larger than 0, the test will wait for \a delay milliseconds before pressing the key.
688
689 \b {Note:} At some point you should release the key using \l keyRelease().
690
691 \sa QTest::keyRelease(), QTest::keyClick()
692*/
693
694/*! \fn void QTest::keyPress(QWindow *window, char key, Qt::KeyboardModifiers modifier = Qt::NoModifier, int delay=-1)
695 \overload
696 \since 5.0
697
698 Simulates pressing a \a key with an optional \a modifier on a \a window.
699 If \a delay is larger than 0, the test will wait for \a delay milliseconds
700 before pressing the key.
701
702 \b {Note:} At some point you should release the key using \l keyRelease().
703
704 \sa QTest::keyRelease(), QTest::keyClick()
705*/
706
707/*! \fn void QTest::keyRelease(QWidget *widget, Qt::Key key, Qt::KeyboardModifiers modifier = Qt::NoModifier, int delay=-1)
708
709 Simulates releasing a \a key with an optional \a modifier on a \a widget.
710 If \a delay is larger than 0, the test will wait for \a delay milliseconds
711 before releasing the key.
712
713 \sa QTest::keyPress(), QTest::keyClick()
714*/
715
716/*! \fn void QTest::keyRelease(QWidget *widget, char key, Qt::KeyboardModifiers modifier = Qt::NoModifier, int delay=-1)
717 \overload
718
719 Simulates releasing a \a key with an optional \a modifier on a \a widget.
720 If \a delay is larger than 0, the test will wait for \a delay milliseconds
721 before releasing the key.
722
723 \sa QTest::keyClick()
724*/
725
726/*! \fn void QTest::keyRelease(QWindow *window, Qt::Key key, Qt::KeyboardModifiers modifier = Qt::NoModifier, int delay=-1)
727 \overload
728 \since 5.0
729
730 Simulates releasing a \a key with an optional \a modifier on a \a window.
731 If \a delay is larger than 0, the test will wait for \a delay milliseconds
732 before releasing the key.
733
734 \sa QTest::keyPress(), QTest::keyClick()
735*/
736
737/*! \fn void QTest::keyRelease(QWindow *window, char key, Qt::KeyboardModifiers modifier = Qt::NoModifier, int delay=-1)
738 \overload
739 \since 5.0
740
741 Simulates releasing a \a key with an optional \a modifier on a \a window.
742 If \a delay is larger than 0, the test will wait for \a delay milliseconds
743 before releasing the key.
744
745 \sa QTest::keyClick()
746*/
747
748/*! \fn void QTest::keyClicks(QWidget *widget, const QString &sequence, Qt::KeyboardModifiers modifier = Qt::NoModifier, int delay=-1)
749
750 Simulates clicking a \a sequence of keys on a \a
751 widget. Optionally, a keyboard \a modifier can be specified as
752 well as a \a delay (in milliseconds) of the test before each key
753 click.
754
755 Example:
756 \snippet code/src_qtestlib_qtestcase.cpp 15
757
758 The example above simulates clicking the sequence of keys
759 representing "hello world" on \c myWidget without any keyboard
760 modifiers and without delay of the test.
761
762 \sa QTest::keyClick()
763*/
764
765/*! \fn void QTest::mousePress(QWidget *widget, Qt::MouseButton button, Qt::KeyboardModifiers modifier = 0, QPoint pos = QPoint(), int delay=-1)
766
767 Simulates pressing a mouse \a button with an optional \a modifier
768 on a \a widget. The position is defined by \a pos; the default
769 position is the center of the widget. If \a delay is specified,
770 the test will wait for the specified amount of milliseconds before
771 the press.
772
773 \sa QTest::mouseRelease(), QTest::mouseClick()
774*/
775
776/*! \fn void QTest::mousePress(QWindow *window, Qt::MouseButton button, Qt::KeyboardModifiers stateKey = 0, QPoint pos = QPoint(), int delay=-1)
777 \overload
778 \since 5.0
779
780 Simulates pressing a mouse \a button with an optional \a stateKey modifier
781 on a \a window. The position is defined by \a pos; the default
782 position is the center of the window. If \a delay is specified,
783 the test will wait for the specified amount of milliseconds before
784 the press.
785
786 \sa QTest::mouseRelease(), QTest::mouseClick()
787*/
788
789/*! \fn void QTest::mouseRelease(QWidget *widget, Qt::MouseButton button, Qt::KeyboardModifiers modifier = 0, QPoint pos = QPoint(), int delay=-1)
790
791 Simulates releasing a mouse \a button with an optional \a modifier
792 on a \a widget. The position of the release is defined by \a pos;
793 the default position is the center of the widget. If \a delay is
794 specified, the test will wait for the specified amount of
795 milliseconds before releasing the button.
796
797 \sa QTest::mousePress(), QTest::mouseClick()
798*/
799
800/*! \fn void QTest::mouseRelease(QWindow *window, Qt::MouseButton button, Qt::KeyboardModifiers stateKey = 0, QPoint pos = QPoint(), int delay=-1)
801 \overload
802 \since 5.0
803
804 Simulates releasing a mouse \a button with an optional \a stateKey modifier
805 on a \a window. The position of the release is defined by \a pos;
806 the default position is the center of the window. If \a delay is
807 specified, the test will wait for the specified amount of
808 milliseconds before releasing the button.
809
810 \sa QTest::mousePress(), QTest::mouseClick()
811*/
812
813/*! \fn void QTest::mouseClick(QWidget *widget, Qt::MouseButton button, Qt::KeyboardModifiers modifier = 0, QPoint pos = QPoint(), int delay=-1)
814
815 Simulates clicking a mouse \a button with an optional \a modifier
816 on a \a widget. The position of the click is defined by \a pos;
817 the default position is the center of the widget. If \a delay is
818 specified, the test will wait for the specified amount of
819 milliseconds before pressing and before releasing the button.
820
821 \sa QTest::mousePress(), QTest::mouseRelease()
822*/
823
824/*! \fn void QTest::mouseClick(QWindow *window, Qt::MouseButton button, Qt::KeyboardModifiers stateKey = 0, QPoint pos = QPoint(), int delay=-1)
825 \overload
826 \since 5.0
827
828 Simulates clicking a mouse \a button with an optional \a stateKey modifier
829 on a \a window. The position of the click is defined by \a pos;
830 the default position is the center of the window. If \a delay is
831 specified, the test will wait for the specified amount of
832 milliseconds before pressing and before releasing the button.
833
834 \sa QTest::mousePress(), QTest::mouseRelease()
835*/
836
837/*! \fn void QTest::mouseDClick(QWidget *widget, Qt::MouseButton button, Qt::KeyboardModifiers modifier = 0, QPoint pos = QPoint(), int delay=-1)
838
839 Simulates double clicking a mouse \a button with an optional \a
840 modifier on a \a widget. The position of the click is defined by
841 \a pos; the default position is the center of the widget. If \a
842 delay is specified, the test will wait for the specified amount of
843 milliseconds before each press and release.
844
845 \sa QTest::mouseClick()
846*/
847
848/*! \fn void QTest::mouseDClick(QWindow *window, Qt::MouseButton button, Qt::KeyboardModifiers stateKey = 0, QPoint pos = QPoint(), int delay=-1)
849 \overload
850 \since 5.0
851
852 Simulates double clicking a mouse \a button with an optional \a stateKey
853 modifier on a \a window. The position of the click is defined by
854 \a pos; the default position is the center of the window. If \a
855 delay is specified, the test will wait for the specified amount of
856 milliseconds before each press and release.
857
858 \sa QTest::mouseClick()
859*/
860
861/*! \fn void QTest::mouseMove(QWidget *widget, QPoint pos = QPoint(), int delay=-1)
862
863 Moves the mouse pointer to a \a widget. If \a pos is not
864 specified, the mouse pointer moves to the center of the widget. If
865 a \a delay (in milliseconds) is given, the test will wait before
866 moving the mouse pointer.
867*/
868
869/*! \fn void QTest::mouseMove(QWindow *window, QPoint pos = QPoint(), int delay=-1)
870 \overload
871 \since 5.0
872
873 Moves the mouse pointer to a \a window. If \a pos is not
874 specified, the mouse pointer moves to the center of the window. If
875 a \a delay (in milliseconds) is given, the test will wait before
876 moving the mouse pointer.
877*/
878
879/*!
880 \fn template <typename T1, typename T2> char *QTest::toString(const QPair<T1, T2> &pair)
881 \overload
882 \since 5.11
883 Returns a textual representation of the \a pair.
884*/
885
886/*!
887 \fn template <typename T1, typename T2> char *QTest::toString(const std::pair<T1, T2> &pair)
888 \overload
889 \since 5.11
890 Returns a textual representation of the \a pair.
891*/
892
893/*!
894 \fn char *QTest::toString(const QVector2D &v)
895 \overload
896 \since 5.11
897 Returns a textual representation of the 2D vector \a v.
898*/
899
900/*!
901 \fn char *QTest::toString(const QVector3D &v)
902 \overload
903 \since 5.11
904 Returns a textual representation of the 3D vector \a v.
905*/
906
907/*!
908 \fn char *QTest::toString(const QVector4D &v)
909 \overload
910 \since 5.11
911 Returns a textual representation of the 4D vector \a v.
912*/
913
914/*!
915 \fn template<typename T> char *QTest::toString(const T &value)
916
917 Returns a textual representation of \a value. This function is used by
918 \l QCOMPARE() to output verbose information in case of a test failure.
919
920 You can add specializations or overloads of this function to your test to enable
921 verbose output.
922
923 \b {Note:} Starting with Qt 5.5, you should prefer to provide a toString() function
924 in the type's namespace instead of specializing this template.
925 If your code needs to continue to work with the QTestLib from Qt 5.4 or
926 earlier, you need to continue to use specialization.
927
928 \b {Note:} The caller of toString() must delete the returned data
929 using \c{delete[]}. Your implementation should return a string
930 created with \c{new[]} or qstrdup(). The easiest way to do so is to
931 create a QByteArray or QString and calling QTest::toString() on it
932 (see second example below).
933
934 Example for specializing (Qt ≤ 5.4):
935
936 \snippet code/src_qtestlib_qtestcase.cpp 16
937
938 The example above defines a toString() specialization for a class
939 called \c MyPoint. Whenever a comparison of two instances of \c
940 MyPoint fails, \l QCOMPARE() will call this function to output the
941 contents of \c MyPoint to the test log.
942
943 Same example, but with overloading (Qt ≥ 5.5):
944
945 \snippet code/src_qtestlib_qtestcase.cpp toString-overload
946
947 \sa QCOMPARE()
948*/
949
950/*!
951 \fn char *QTest::toString(const QLatin1String &string)
952 \overload
953
954 Returns a textual representation of the given \a string.
955*/
956
957/*!
958 \fn char *QTest::toString(std::nullptr_t)
959 \overload
960 \since 5.8
961
962 Returns a string containing \nullptr.
963*/
964
965/*!
966 \fn char *QTest::toString(const QStringView &string)
967 \overload
968 \since 5.11
969
970 Returns a textual representation of the given \a string.
971*/
972
973/*!
974 \fn char *QTest::toString(const QUuid &uuid)
975 \overload
976 \since 5.11
977
978 Returns a textual representation of the given \a uuid.
979*/
980
981/*!
982 \fn char *QTest::toString(const QString &string)
983 \overload
984
985 Returns a textual representation of the given \a string.
986*/
987
988/*!
989 \fn char *QTest::toString(const QByteArray &ba)
990 \overload
991
992 Returns a textual representation of the byte array \a ba.
993
994 \sa QTest::toHexRepresentation()
995*/
996
997/*!
998 \fn char *QTest::toString(const QCborError &c)
999 \overload
1000 \since 5.12
1001
1002 Returns a textual representation of the given CBOR error \a c.
1003*/
1004
1005/*!
1006 \fn template <class... Types> char *QTest::toString(const std::tuple<Types...> &tuple)
1007 \overload
1008 \since 5.12
1009
1010 Returns a textual representation of the given \a tuple.
1011*/
1012
1013/*!
1014 \fn char *QTest::toString(const QTime &time)
1015 \overload
1016
1017 Returns a textual representation of the given \a time.
1018*/
1019
1020/*!
1021 \fn char *QTest::toString(const QDate &date)
1022 \overload
1023
1024 Returns a textual representation of the given \a date.
1025*/
1026
1027/*!
1028 \fn char *QTest::toString(const QDateTime &dateTime)
1029 \overload
1030
1031 Returns a textual representation of the date and time specified by
1032 \a dateTime.
1033*/
1034
1035/*!
1036 \fn char *QTest::toString(const QChar &character)
1037 \overload
1038
1039 Returns a textual representation of the given \a character.
1040*/
1041
1042/*!
1043 \fn char *QTest::toString(const QPoint &point)
1044 \overload
1045
1046 Returns a textual representation of the given \a point.
1047*/
1048
1049/*!
1050 \fn char *QTest::toString(const QSize &size)
1051 \overload
1052
1053 Returns a textual representation of the given \a size.
1054*/
1055
1056/*!
1057 \fn char *QTest::toString(const QRect &rectangle)
1058 \overload
1059
1060 Returns a textual representation of the given \a rectangle.
1061*/
1062
1063/*!
1064 \fn char *QTest::toString(const QUrl &url)
1065 \since 4.4
1066 \overload
1067
1068 Returns a textual representation of the given \a url.
1069*/
1070
1071/*!
1072 \fn char *QTest::toString(const QPointF &point)
1073 \overload
1074
1075 Returns a textual representation of the given \a point.
1076*/
1077
1078/*!
1079 \fn char *QTest::toString(const QSizeF &size)
1080 \overload
1081
1082 Returns a textual representation of the given \a size.
1083*/
1084
1085/*!
1086 \fn char *QTest::toString(const QRectF &rectangle)
1087 \overload
1088
1089 Returns a textual representation of the given \a rectangle.
1090*/
1091
1092/*!
1093 \fn char *QTest::toString(const QVariant &variant)
1094 \overload
1095
1096 Returns a textual representation of the given \a variant.
1097*/
1098
1099/*!
1100 \fn char *QTest::toString(QSizePolicy::ControlType ct)
1101 \overload
1102 \since 5.5
1103
1104 Returns a textual representation of control type \a ct.
1105*/
1106
1107/*!
1108 \fn char *QTest::toString(QSizePolicy::ControlTypes cts)
1109 \overload
1110 \since 5.5
1111
1112 Returns a textual representation of control types \a cts.
1113*/
1114
1115/*!
1116 \fn char *QTest::toString(QSizePolicy::Policy p)
1117 \overload
1118 \since 5.5
1119
1120 Returns a textual representation of policy \a p.
1121*/
1122
1123/*!
1124 \fn char *QTest::toString(QSizePolicy sp)
1125 \overload
1126 \since 5.5
1127
1128 Returns a textual representation of size policy \a sp.
1129*/
1130
1131/*!
1132 \fn template <typename Tuple, int... I> char *QTest::toString(const Tuple &tuple, QtPrivate::IndexesList<I...> )
1133 \internal
1134 \since 5.12
1135*/
1136
1137/*!
1138 \fn QTouchDevice *QTest::createTouchDevice(QTouchDevice::DeviceType devType = QTouchDevice::TouchScreen)
1139 \since 5.8
1140
1141 Creates a dummy touch device of type \a devType for simulation of touch events.
1142
1143 The touch device will be registered with the QPA window system interface,
1144 and deleted automatically when the QCoreApplication is deleted. So you
1145 should typically use createTouchDevice() to initialize a QTouchDevice
1146 member variable in your test case class, and use the same instance for all tests.
1147
1148 \sa QTest::QTouchEventSequence
1149*/
1150
1151/*!
1152 \class QTest::QTouchEventSequence
1153 \inmodule QtTest
1154 \since 4.6
1155
1156 \brief The QTouchEventSequence class is used to simulate a sequence of touch events.
1157
1158 To simulate a sequence of touch events on a specific device for a window or widget, call
1159 QTest::touchEvent to create a QTouchEventSequence instance. Add touch events to
1160 the sequence by calling press(), move(), release() and stationary(), and let the
1161 instance run out of scope to commit the sequence to the event system.
1162
1163 Example:
1164 \snippet code/src_qtestlib_qtestcase.cpp 25
1165*/
1166
1167/*!
1168 \fn QTest::QTouchEventSequence::~QTouchEventSequence()
1169
1170 Commits this sequence of touch events, unless autoCommit was disabled, and frees allocated resources.
1171*/
1172
1173/*!
1174 \fn void QTest::QTouchEventSequence::commit(bool processEvents)
1175
1176 Commits this sequence of touch events to the event system. Normally there is no need to call this
1177 function because it is called from the destructor. However, if autoCommit is disabled, the events
1178 only get committed upon explicitly calling this function.
1179
1180 In special cases tests may want to disable the processing of the events. This can be achieved by
1181 setting \a processEvents to false. This results in merely queuing the events, the event loop will
1182 not be forced to process them.
1183*/
1184
1185/*!
1186 \fn QTouchEventSequence &QTest::QTouchEventSequence::press(int touchId, const QPoint &pt, QWindow *window)
1187 \since 5.0
1188
1189 Adds a press event for touchpoint \a touchId at position \a pt to this sequence and returns
1190 a reference to this QTouchEventSequence.
1191
1192 The position \a pt is interpreted as relative to \a window. If \a window is the null pointer, then
1193 \a pt is interpreted as relative to the window provided when instantiating this QTouchEventSequence.
1194
1195 Simulates that the user pressed the touch screen or pad with the finger identified by \a touchId.
1196*/
1197
1198/*!
1199 \fn QTouchEventSequence &QTest::QTouchEventSequence::press(int touchId, const QPoint &pt, QWidget *widget)
1200
1201 Adds a press event for touchpoint \a touchId at position \a pt to this sequence and returns
1202 a reference to this QTouchEventSequence.
1203
1204 The position \a pt is interpreted as relative to \a widget. If \a widget is the null pointer, then
1205 \a pt is interpreted as relative to the widget provided when instantiating this QTouchEventSequence.
1206
1207 Simulates that the user pressed the touch screen or pad with the finger identified by \a touchId.
1208*/
1209
1210/*!
1211 \fn QTouchEventSequence &QTest::QTouchEventSequence::move(int touchId, const QPoint &pt, QWindow *window)
1212 \since 5.0
1213
1214 Adds a move event for touchpoint \a touchId at position \a pt to this sequence and returns
1215 a reference to this QTouchEventSequence.
1216
1217 The position \a pt is interpreted as relative to \a window. If \a window is the null pointer, then
1218 \a pt is interpreted as relative to the window provided when instantiating this QTouchEventSequence.
1219
1220 Simulates that the user moved the finger identified by \a touchId.
1221*/
1222
1223/*!
1224 \fn QTouchEventSequence &QTest::QTouchEventSequence::move(int touchId, const QPoint &pt, QWidget *widget)
1225
1226 Adds a move event for touchpoint \a touchId at position \a pt to this sequence and returns
1227 a reference to this QTouchEventSequence.
1228
1229 The position \a pt is interpreted as relative to \a widget. If \a widget is the null pointer, then
1230 \a pt is interpreted as relative to the widget provided when instantiating this QTouchEventSequence.
1231
1232 Simulates that the user moved the finger identified by \a touchId.
1233*/
1234
1235/*!
1236 \fn QTouchEventSequence &QTest::QTouchEventSequence::release(int touchId, const QPoint &pt, QWindow *window)
1237 \since 5.0
1238
1239 Adds a release event for touchpoint \a touchId at position \a pt to this sequence and returns
1240 a reference to this QTouchEventSequence.
1241
1242 The position \a pt is interpreted as relative to \a window. If \a window is the null pointer, then
1243 \a pt is interpreted as relative to the window provided when instantiating this QTouchEventSequence.
1244
1245 Simulates that the user lifted the finger identified by \a touchId.
1246*/
1247
1248/*!
1249 \fn QTouchEventSequence &QTest::QTouchEventSequence::release(int touchId, const QPoint &pt, QWidget *widget)
1250
1251 Adds a release event for touchpoint \a touchId at position \a pt to this sequence and returns
1252 a reference to this QTouchEventSequence.
1253
1254 The position \a pt is interpreted as relative to \a widget. If \a widget is the null pointer, then
1255 \a pt is interpreted as relative to the widget provided when instantiating this QTouchEventSequence.
1256
1257 Simulates that the user lifted the finger identified by \a touchId.
1258*/
1259
1260/*!
1261 \fn QTouchEventSequence &QTest::QTouchEventSequence::stationary(int touchId)
1262
1263 Adds a stationary event for touchpoint \a touchId to this sequence and returns
1264 a reference to this QTouchEventSequence.
1265
1266 Simulates that the user did not move the finger identified by \a touchId.
1267*/
1268
1269/*!
1270 \fn QTouchEventSequence QTest::touchEvent(QWindow *window, QTouchDevice *device, bool autoCommit)
1271 \since 5.0
1272
1273 Creates and returns a QTouchEventSequence for the \a device to
1274 simulate events for \a window.
1275
1276 When adding touch events to the sequence, \a window will also be used to translate
1277 the position provided to screen coordinates, unless another window is provided in the
1278 respective calls to press(), move() etc.
1279
1280 The touch events are committed to the event system when the destructor of the
1281 QTouchEventSequence is called (ie when the object returned runs out of scope), unless
1282 \a autoCommit is set to false. When \a autoCommit is false, commit() has to be called
1283 manually.
1284*/
1285
1286/*!
1287 \fn QTouchEventSequence QTest::touchEvent(QWidget *widget, QTouchDevice *device, bool autoCommit)
1288
1289 Creates and returns a QTouchEventSequence for the \a device to
1290 simulate events for \a widget.
1291
1292 When adding touch events to the sequence, \a widget will also be used to translate
1293 the position provided to screen coordinates, unless another widget is provided in the
1294 respective calls to press(), move() etc.
1295
1296 The touch events are committed to the event system when the destructor of the
1297 QTouchEventSequence is called (ie when the object returned runs out of scope), unless
1298 \a autoCommit is set to false. When \a autoCommit is false, commit() has to be called
1299 manually.
1300*/
1301
1302// Internals of qtestmouse.h:
1303
1304/*! \fn void QTest::mouseEvent(MouseAction action, QWidget *widget, Qt::MouseButton button, Qt::KeyboardModifiers stateKey, QPoint pos, int delay=-1)
1305 \internal
1306*/
1307
1308/*! \fn void QTest::mouseEvent(MouseAction action, QWindow *window, Qt::MouseButton button, Qt::KeyboardModifiers stateKey, QPoint pos, int delay=-1)
1309 \internal
1310*/
1311

Warning: That file was not part of the compilation database. It may have many parsing errors.