1// Copyright (C) 2020 The Qt Company Ltd.
2// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
8 \brief The QTest namespace contains all the functions and
9 declarations that are related to Qt Test.
11 See the \l{Qt Test Overview} for information about how to write unit tests.
14/*! \macro QVERIFY(condition)
18 The QVERIFY() macro checks whether the \a condition is true or not. If it is
19 true, execution continues. If not, a failure is recorded in the test log
20 and the test won't be executed further.
22 You can use \l QVERIFY2() when it is practical and valuable to put additional
23 information into the test failure report.
25//! [macro-usage-limitation]
26 \note This macro can only be used in a test function that is invoked
27 by the test framework.
28//! [macro-usage-limitation]
30 For example, the following code shows this macro being used to verify that a
31 \l QSignalSpy object is valid:
33 \snippet code/src_qtestlib_qtestcase_snippet.cpp 0
35 For more information about the failure, use \c QCOMPARE(x, y) instead of
36 \c QVERIFY(x == y), because it reports both the expected and actual value
37 when the comparison fails.
39 \sa QCOMPARE(), QTRY_VERIFY(), QSignalSpy, QEXPECT_FAIL(), QCOMPARE_EQ(),
40 QCOMPARE_NE(), QCOMPARE_LT(), QCOMPARE_LE(), QCOMPARE_GT(), QCOMPARE_GE()
43/*! \macro QVERIFY2(condition, message)
47 The QVERIFY2() macro behaves exactly like QVERIFY(), except that it reports
48 a \a message when \a condition is false. The \a message is a plain C string.
50 The message can also be obtained from a function call that produces a plain
51 C string, such as qPrintable() applied to a QString, which may be built in
52 any of its usual ways, including applying \c {.args()} to format some data.
55 \snippet code/src_qtestlib_qtestcase.cpp 1
57 For example, if you have a file object and you are testing its \c open()
58 function, you might write a test with a statement like:
60 \snippet code/src_qtestlib_qtestcase.cpp 32
62 If this test fails, it will give no clue as to why the file failed to open:
64 \c {FAIL! : tst_QFile::open_write() 'opened' returned FALSE. ()}
66 If there is a more informative error message you could construct from the
67 values being tested, you can use \c QVERIFY2() to pass that message along
68 with your test condition, to provide a more informative message on failure:
70 \snippet code/src_qtestlib_qtestcase.cpp 33
72 If this branch is being tested in the Qt CI system, the above detailed
73 failure message will be inserted into the summary posted to the code-review
76 \c {FAIL! : tst_QFile::open_write() 'opened' returned FALSE.
77 (open /tmp/qt.a3B42Cd: No space left on device)}
79 \sa QVERIFY(), QCOMPARE(), QEXPECT_FAIL(), QCOMPARE_EQ(), QCOMPARE_NE(),
80 QCOMPARE_LT(), QCOMPARE_LE(), QCOMPARE_GT(), QCOMPARE_GE()
83/*! \macro QCOMPARE(actual, expected)
87 The QCOMPARE() macro compares an \a actual value to an \a expected value
88 using the equality operator. If \a actual and \a expected match, execution
89 continues. If not, a failure is recorded in the test log and the test
90 function returns without attempting any later checks.
92 Always respect QCOMPARE() parameter semantics. The first parameter passed to
93 it should always be the actual value produced by the code-under-test, while
94 the second parameter should always be the expected value. When the values
95 don't match, QCOMPARE() prints them with the labels \e Actual and \e
96 Expected. If the parameter order is swapped, debugging a failing test can be
97 confusing and tests expecting zero may fail due to rounding errors.
99 QCOMPARE() tries to output the contents of the values if the comparison fails,
100 so it is visible from the test log why the comparison failed.
103 \snippet code/src_qtestlib_qtestcase.cpp 2
105 When comparing floating-point types (\c float, \c double, and \c qfloat16),
106 \l {qFuzzyCompare()} is used for finite values. If \l {<QtNumeric>::}{qFuzzyIsNull()}
107 is true for both values, they are also considered equal. Infinities
108 match if they have the same sign, and any NaN as actual value matches
109 with any NaN as expected value (even though NaN != NaN, even when
112 When comparing QList, arrays and initializer lists of the value type
113 can be passed as expected value:
114 \snippet code/src_qtestlib_qtestcase.cpp 34
116 Note that using initializer lists requires defining a helper macro
117 to prevent the preprocessor from interpreting the commas as macro argument
119 \snippet code/src_qtestlib_qtestcase.cpp 35
121 \include qtestcase.qdoc macro-usage-limitation
123//! [to-string-overload-desc]
124 For your own classes, you can overload \l QTest::toString() to format values
125 for output into the test log.
126//! [to-string-overload-desc]
129 \snippet code/src_qtestlib_qtestcase_snippet.cpp 34
131 The return from \c toString() must be a \c {new char []}. That is, it shall
132 be released with \c delete[] (rather than \c free() or plain \c delete) once
133 the calling code is done with it.
135 \sa QVERIFY(), QTRY_COMPARE(), QTest::toString(), QEXPECT_FAIL(),
136 QCOMPARE_EQ(), QCOMPARE_NE(), QCOMPARE_LT(), QCOMPARE_LE(),
137 QCOMPARE_GT(), QCOMPARE_GE()
140/*! \macro QCOMPARE_EQ(computed, baseline)
145 The QCOMPARE_EQ() macro checks that \a computed is equal to \a baseline using
146 the equality operator. If that is true, execution continues. If not, a
147 failure is recorded in the test log and the test function returns without
148 attempting any later checks.
150 It is generally similar to calling \c {QVERIFY(computed == baseline);}
151 but prints a formatted error message reporting \a computed and \a baseline argument
152 expressions and values in case of failure.
154 \include qtestcase.qdoc macro-usage-limitation
156 \include qtestcase.qdoc to-string-overload-desc
158 \note Unlike QCOMPARE(), this macro does not provide overloads for custom
159 types and pointers. So passing e.g. two \c {const char *} values as
160 parameters will compare \e pointers, while QCOMPARE() does a comparison of
163 \sa QCOMPARE(), QCOMPARE_NE(), QCOMPARE_LT(), QCOMPARE_LE(), QCOMPARE_GT(),
167/*! \macro QCOMPARE_NE(computed, baseline)
172 The QCOMPARE_NE() macro checks that \a computed is not equal to \a baseline using
173 the inequality operator. If that is true, execution continues. If not, a
174 failure is recorded in the test log and the test function returns without
175 attempting any later checks.
177 It is generally similar to calling \c {QVERIFY(computed != baseline);}
178 but prints a formatted error message reporting \a computed and \a baseline argument
179 expressions and values in case of failure.
181 \include qtestcase.qdoc macro-usage-limitation
183 \include qtestcase.qdoc to-string-overload-desc
185 \sa QCOMPARE_EQ(), QCOMPARE_LT(), QCOMPARE_LE(), QCOMPARE_GT(), QCOMPARE_GE()
188/*! \macro QCOMPARE_LT(computed, baseline)
193 The QCOMPARE_LT() macro checks that \a computed is less than \a baseline using the
194 less-than operator. If that is true, execution continues. If not, a failure
195 is recorded in the test log and the test function returns without attempting
198 It is generally similar to calling \c {QVERIFY(computed < baseline);}
199 but prints a formatted error message reporting \a computed and \a baseline argument
200 expressions and values in case of failure.
202 \include qtestcase.qdoc macro-usage-limitation
204 \include qtestcase.qdoc to-string-overload-desc
206 \sa QCOMPARE_EQ(), QCOMPARE_NE(), QCOMPARE_LE(), QCOMPARE_GT(), QCOMPARE_GE()
209/*! \macro QCOMPARE_LE(computed, baseline)
214 The QCOMPARE_LE() macro checks that \a computed is at most \a baseline using the
215 less-than-or-equal-to operator. If that is true, execution continues. If
216 not, a failure is recorded in the test log and the test function returns
217 without attempting any later checks.
219 It is generally similar to calling \c {QVERIFY(computed <= baseline);}
220 but prints a formatted error message reporting \a computed and \a baseline argument
221 expressions and values in case of failure.
223 \include qtestcase.qdoc macro-usage-limitation
225 \include qtestcase.qdoc to-string-overload-desc
227 \sa QCOMPARE_EQ(), QCOMPARE_NE(), QCOMPARE_LT(), QCOMPARE_GT(), QCOMPARE_GE()
230/*! \macro QCOMPARE_GT(computed, baseline)
235 The QCOMPARE_GT() macro checks that \a computed is greater than \a baseline using
236 the greater-than operator. If that is true, execution continues. If not, a
237 failure is recorded in the test log and the test function returns without
238 attempting any later checks.
240 It is generally similar to calling \c {QVERIFY(computed > baseline);}
241 but prints a formatted error message reporting \a computed and \a baseline argument
242 expressions and values in case of failure.
244 \include qtestcase.qdoc macro-usage-limitation
246 \include qtestcase.qdoc to-string-overload-desc
248 \sa QCOMPARE_EQ(), QCOMPARE_NE(), QCOMPARE_LT(), QCOMPARE_LE(), QCOMPARE_GE()
251/*! \macro QCOMPARE_GE(computed, baseline)
256 The QCOMPARE_GE() macro checks that \a computed is at least \a baseline using the
257 greater-than-or-equal-to operator. If that is true, execution continues. If
258 not, a failure is recorded in the test log and the test function returns
259 without attempting any later checks.
261 It is generally similar to calling \c {QVERIFY(computed >= baseline);}
262 but prints a formatted error message reporting \a computed and \a baseline argument
263 expressions and values in case of failure.
265 \include qtestcase.qdoc macro-usage-limitation
267 \include qtestcase.qdoc to-string-overload-desc
269 \sa QCOMPARE_EQ(), QCOMPARE_NE(), QCOMPARE_LT(), QCOMPARE_LE(), QCOMPARE_GT()
272/*! \macro QVERIFY_EXCEPTION_THROWN(expression, exceptiontype)
276 \deprecated [6.3] Use \c{QVERIFY_THROWS_EXCEPTION(exceptiontype, expression)} instead.
280 \macro QVERIFY_THROWS_EXCEPTION(exceptiontype, ...)
284 The QVERIFY_THROWS_EXCEPTION macro executes the expression given in the variadic
285 argument and expects to catch an exception thrown from the expression.
287 There are several possible outcomes:
290 \li If the expression throws an exception that is either the same as
291 \a exceptiontype or derived from \a exceptiontype, then execution will continue.
293 \li Otherwise, if the expression throws no exception, or the
294 exception thrown derives from \c{std::exception}, then a failure
295 will be recorded in the test log and the macro returns early
296 (from enclosing function).
298 \li If the thrown exception derives neither from \c{std::exception} nor from
299 \a exceptiontype, a failure will be recorded in the test log, and the exception is
300 re-thrown. This avoids problems with e.g. pthread cancellation exceptions.
303 The macro uses variadic arguments so the expression can contain commas that the
304 preprocessor considers argument separators, e.g. as in
306 QVERIFY_THROWS_EXCEPTION(std::bad_alloc,
307 // macro arguments: ^ exceptiontype
308 std::vector<std::pair<int, long>>{42'000'000'000, {42, 42L}});
309 // macro arguments: \---------- 1 ----------/ \-------- 2 --------/ \3/ \ 4 /
310 // \----------------------- expression -----------------------/
313 \note This macro can only be used in a test function that is invoked
314 by the test framework.
318 \macro QVERIFY_THROWS_NO_EXCEPTION(...)
323 The QVERIFY_THROWS_NO_EXCEPTION macro executes the expression given in its
324 variadic argument and tries to catch any exception thrown from the expression.
326 There are several different outcomes:
329 \li If the expression does not throw an exception, then execution will continue.
331 \li Otherwise, if an exception derived from \c{std::exception} is caught, a failure
332 will be recorded in the test log and the macro returns early (implicit return from
335 \li If an exception not derived from \c{std::exception} is caught, a failure will be
336 recorded in the test log and the exception will be re-thrown. This avoids problems
337 with e.g. pthread cancellation exceptions.
340 The macro uses variadic arguments so the expression can contain commas that the
341 preprocessor considers argument separators, e.g. as in
343 QVERIFY_THROWS_NO_EXCEPTION(std::pair<int, long>{42, 42L});
344 // macro arguments: \---- 1 ----/ \-- 2 -/ \3 /
347 \note This macro can only be used in a test function that is invoked
348 by the test framework.
351/*! \macro QTRY_VERIFY_WITH_TIMEOUT(condition, timeout)
356 The QTRY_VERIFY_WITH_TIMEOUT() macro is similar to QVERIFY(), but checks the \a condition
357 repeatedly, until either the condition becomes true or the \a timeout (in milliseconds) is
358 reached. Between each evaluation, events will be processed. If the timeout
359 is reached, a failure is recorded in the test log and the test won't be
363 Since Qt 6.8, the \a timeout can also be a \c{std::chrono} literal such as \c{2s}.
366 \note This macro can only be used in a test function that is invoked
367 by the test framework.
369 \sa QTRY_VERIFY(), QTRY_VERIFY2_WITH_TIMEOUT(), QVERIFY(), QCOMPARE(), QTRY_COMPARE(),
374/*! \macro QTRY_VERIFY(condition)
379 Checks the \a condition by invoking QTRY_VERIFY_WITH_TIMEOUT() with a timeout of five seconds.
381 \note This macro can only be used in a test function that is invoked
382 by the test framework.
384 \sa QTRY_VERIFY_WITH_TIMEOUT(), QTRY_VERIFY2(), QVERIFY(), QCOMPARE(), QTRY_COMPARE(),
388/*! \macro QTRY_VERIFY2_WITH_TIMEOUT(condition, message, timeout)
393 The QTRY_VERIFY2_WITH_TIMEOUT macro is similar to QTRY_VERIFY_WITH_TIMEOUT()
394 except that it outputs a verbose \a message when \a condition is still false
395 after the specified \a timeout (in milliseconds). The \a message is a plain C string.
397 \include qtestcase.qdoc chrono-timeout
401 QTRY_VERIFY2_WITH_TIMEOUT(list.size() > 2, QByteArray::number(list.size()).constData(), 10s);
404 \note This macro can only be used in a test function that is invoked
405 by the test framework.
407 \sa QTRY_VERIFY(), QTRY_VERIFY_WITH_TIMEOUT(), QVERIFY(), QCOMPARE(), QTRY_COMPARE(),
411/*! \macro QTRY_VERIFY2(condition, message)
416 Checks the \a condition by invoking QTRY_VERIFY2_WITH_TIMEOUT() with a timeout
417 of five seconds. If \a condition is then still false, \a message is output.
418 The \a message is a plain C string.
422 QTRY_VERIFY2(list.size() > 2, QByteArray::number(list.size()).constData());
425 \note This macro can only be used in a test function that is invoked
426 by the test framework.
428 \sa QTRY_VERIFY2_WITH_TIMEOUT(), QTRY_VERIFY2(), QVERIFY(), QCOMPARE(), QTRY_COMPARE(),
432/*! \macro QTRY_COMPARE_WITH_TIMEOUT(actual, expected, timeout)
437 The QTRY_COMPARE_WITH_TIMEOUT() macro is similar to QCOMPARE(), but performs the comparison
438 of the \a actual and \a expected values repeatedly, until either the two values
439 are equal or the \a timeout (in milliseconds) is reached. Between each comparison, events
440 will be processed. If the timeout is reached, a failure is recorded in the
441 test log and the test won't be executed further.
443 \include qtestcase.qdoc chrono-timeout
445 \note This macro can only be used in a test function that is invoked
446 by the test framework.
448 \sa QTRY_COMPARE(), QCOMPARE(), QVERIFY(), QTRY_VERIFY(), QEXPECT_FAIL()
451/*! \macro QTRY_COMPARE(actual, expected)
456 Performs a comparison of the \a actual and \a expected values by
457 invoking QTRY_COMPARE_WITH_TIMEOUT() with a timeout of five seconds.
459 \note This macro can only be used in a test function that is invoked
460 by the test framework.
462 \sa QTRY_COMPARE_WITH_TIMEOUT(), QCOMPARE(), QVERIFY(), QTRY_VERIFY(),
466/*! \macro QTRY_COMPARE_EQ_WITH_TIMEOUT(computed, baseline, timeout)
470 This macro is similar to QCOMPARE_EQ(), but performs the comparison of the
471 \a computed and \a baseline values repeatedly, until either the comparison returns
472 \c true or the \a timeout (in milliseconds) is reached. Between each
473 comparison, events will be processed. If the timeout is reached, a failure
474 is recorded in the test log and the test won't be executed further.
476 \include qtestcase.qdoc chrono-timeout
478 \include qtestcase.qdoc macro-usage-limitation
480 \sa QCOMPARE_EQ(), QTRY_COMPARE_EQ()
483/*! \macro QTRY_COMPARE_EQ(computed, baseline)
487 Performs comparison of \a computed and \a baseline values by invoking
488 QTRY_COMPARE_EQ_WITH_TIMEOUT with a timeout of five seconds.
490 \include qtestcase.qdoc macro-usage-limitation
492 \sa QCOMPARE_EQ(), QTRY_COMPARE_EQ_WITH_TIMEOUT()
495/*! \macro QTRY_COMPARE_NE_WITH_TIMEOUT(computed, baseline, timeout)
499 This macro is similar to QCOMPARE_NE(), but performs the comparison of the
500 \a computed and \a baseline values repeatedly, until either the comparison returns
501 \c true or the \a timeout (in milliseconds) is reached. Between each
502 comparison, events will be processed. If the timeout is reached, a failure
503 is recorded in the test log and the test won't be executed further.
505 \include qtestcase.qdoc chrono-timeout
507 \include qtestcase.qdoc macro-usage-limitation
509 \sa QCOMPARE_NE(), QTRY_COMPARE_NE()
512/*! \macro QTRY_COMPARE_NE(computed, baseline)
516 Performs comparison of \a computed and \a baseline values by invoking
517 QTRY_COMPARE_NE_WITH_TIMEOUT with a timeout of five seconds.
519 \include qtestcase.qdoc macro-usage-limitation
521 \sa QCOMPARE_NE(), QTRY_COMPARE_NE_WITH_TIMEOUT()
524/*! \macro QTRY_COMPARE_LT_WITH_TIMEOUT(computed, baseline, timeout)
528 This macro is similar to QCOMPARE_LT(), but performs the comparison of the
529 \a computed and \a baseline values repeatedly, until either the comparison returns
530 \c true or the \a timeout (in milliseconds) is reached. Between each
531 comparison, events will be processed. If the timeout is reached, a failure
532 is recorded in the test log and the test won't be executed further.
534 \include qtestcase.qdoc chrono-timeout
536 \include qtestcase.qdoc macro-usage-limitation
538 \sa QCOMPARE_LT(), QTRY_COMPARE_LT()
541/*! \macro QTRY_COMPARE_LT(computed, baseline)
545 Performs comparison of \a computed and \a baseline values by invoking
546 QTRY_COMPARE_LT_WITH_TIMEOUT with a timeout of five seconds.
548 \include qtestcase.qdoc macro-usage-limitation
550 \sa QCOMPARE_LT(), QTRY_COMPARE_LT_WITH_TIMEOUT()
553/*! \macro QTRY_COMPARE_LE_WITH_TIMEOUT(computed, baseline, timeout)
557 This macro is similar to QCOMPARE_LE(), but performs the comparison of the
558 \a computed and \a baseline values repeatedly, until either the comparison returns
559 \c true or the \a timeout (in milliseconds) is reached. Between each
560 comparison, events will be processed. If the timeout is reached, a failure
561 is recorded in the test log and the test won't be executed further.
563 \include qtestcase.qdoc chrono-timeout
565 \include qtestcase.qdoc macro-usage-limitation
567 \sa QCOMPARE_LE(), QTRY_COMPARE_LE()
570/*! \macro QTRY_COMPARE_LE(computed, baseline)
574 Performs comparison of \a computed and \a baseline values by invoking
575 QTRY_COMPARE_LE_WITH_TIMEOUT with a timeout of five seconds.
577 \include qtestcase.qdoc macro-usage-limitation
579 \sa QCOMPARE_LE(), QTRY_COMPARE_LE_WITH_TIMEOUT()
582/*! \macro QTRY_COMPARE_GT_WITH_TIMEOUT(computed, baseline, timeout)
586 This macro is similar to QCOMPARE_GT(), but performs the comparison of the
587 \a computed and \a baseline values repeatedly, until either the comparison returns
588 \c true or the \a timeout (in milliseconds) is reached. Between each
589 comparison, events will be processed. If the timeout is reached, a failure
590 is recorded in the test log and the test won't be executed further.
592 \include qtestcase.qdoc chrono-timeout
594 \include qtestcase.qdoc macro-usage-limitation
596 \sa QCOMPARE_GT(), QTRY_COMPARE_GT()
599/*! \macro QTRY_COMPARE_GT(computed, baseline)
603 Performs comparison of \a computed and \a baseline values by invoking
604 QTRY_COMPARE_GT_WITH_TIMEOUT with a timeout of five seconds.
606 \include qtestcase.qdoc macro-usage-limitation
608 \sa QCOMPARE_GT(), QTRY_COMPARE_GT_WITH_TIMEOUT()
611/*! \macro QTRY_COMPARE_GE_WITH_TIMEOUT(computed, baseline, timeout)
615 This macro is similar to QCOMPARE_GE(), but performs the comparison of the
616 \a computed and \a baseline values repeatedly, until either the comparison returns
617 \c true or the \a timeout (in milliseconds) is reached. Between each
618 comparison, events will be processed. If the timeout is reached, a failure
619 is recorded in the test log and the test won't be executed further.
621 \include qtestcase.qdoc chrono-timeout
623 \include qtestcase.qdoc macro-usage-limitation
625 \sa QCOMPARE_GE(), QTRY_COMPARE_GE()
628/*! \macro QTRY_COMPARE_GE(computed, baseline)
632 Performs comparison of \a computed and \a baseline values by invoking
633 QTRY_COMPARE_GE_WITH_TIMEOUT with a timeout of five seconds.
635 \include qtestcase.qdoc macro-usage-limitation
637 \sa QCOMPARE_GE(), QTRY_COMPARE_GE_WITH_TIMEOUT()
640/*! \macro QFETCH(type, name)
644 The fetch macro creates a local variable named \a name with the type \a type
645 on the stack. The \a name and \a type must match a column from the test's
646 data table. This is asserted and the test will abort if the assertion fails.
648 Assuming a test has the following data:
650 \snippet code/src_qtestlib_qtestcase.cpp 3
652 The test data has two elements, a QString called \c aString and an integer
653 called \c expected. To fetch these values in the actual test:
655 \snippet code/src_qtestlib_qtestcase.cpp 4
657 \c aString and \c expected are variables on the stack that are initialized with
658 the current test data.
660 \note This macro can only be used in a test function that is invoked
661 by the test framework. The test function must have a _data function.
664/*! \macro QFETCH_GLOBAL(type, name)
668 This macro fetches a variable named \a name with the type \a type from
669 a row in the global data table. The \a name and \a type must match a
670 column in the global data table. This is asserted and the test will abort
671 if the assertion fails.
673 Assuming a test has the following data:
675 \snippet code/src_qtestlib_qtestcase_snippet.cpp 30
677 The test's own data is a single number per row. In this case,
678 \c initTestCase_data() also supplies a locale per row. Therefore,
679 this test will be run with every combination of locale from the
680 latter and number from the former. Thus, with four rows in the
681 global table and three in the local, the test function is run for
682 12 distinct test-cases (4 * 3 = 12).
684 \snippet code/src_qtestlib_qtestcase_snippet.cpp 31
686 The locale is read from the global data table using QFETCH_GLOBAL(),
687 and the number is read from the local data table using QFETCH().
689 \note This macro can only be used in test methods of a class with an
690 \c initTestCase_data() method.
693/*! \macro QWARN(message)
697 \deprecated Use qWarning() instead.
699 Appends \a message as a warning to the test log. This macro can be used anywhere
703/*! \macro QFAIL(message)
707 This macro can be used to force a test failure. The test stops
708 executing and the failure \a message is appended to the test log.
710 \note This macro can only be used in a test function that is invoked
711 by the test framework.
715 \snippet code/src_qtestlib_qtestcase.cpp 5
718/*! \macro QTEST(actual, testElement)
722 QTEST() is a convenience macro for \l QCOMPARE() that compares
723 the value \a actual with the element \a testElement from the test's data.
724 If there is no such element, the test asserts.
726 Apart from that, QTEST() behaves exactly as \l QCOMPARE().
730 \snippet code/src_qtestlib_qtestcase.cpp 6
734 \snippet code/src_qtestlib_qtestcase.cpp 7
739/*! \macro QSKIP(description)
743 If called from a test function, the QSKIP() macro stops execution of the test
744 without adding a failure to the test log. You can use it to skip tests that
745 wouldn't make sense in the current configuration. For example, a test of font
746 rendering may call QSKIP() if the needed fonts are not installed on the test
749 The text \a description is appended to the test log and should contain an
750 explanation of why the test couldn't be executed.
752 If the test is data-driven, each call to QSKIP() in the test function will
753 skip only the current row of test data, so an unconditional call to QSKIP()
754 will produce one skip message in the test log for each row of test data.
756 If called from an \c _data function, the QSKIP() macro will stop execution of
757 the \c _data function and will prevent execution of the associated test
758 function. This entirely omits a data-driven test. To omit individual rows,
759 make them conditional by using a simple \c{if (condition) newRow(...) << ...}
760 in the \c _data function, instead of using QSKIP() in the test function.
762 If called from \c initTestCase_data(), the QSKIP() macro will skip all test
763 and \c _data functions. If called from \c initTestCase() when there is no
764 \c initTestCase_data(), or when it only sets up one row, QSKIP() will
765 likewise skip the whole test. However, if \c initTestCase_data() contains
766 more than one row, then \c initTestCase() is called (followed by each test
767 and finally the wrap-up) once per row of it. Therefore, a call to QSKIP() in
768 \c initTestCase() will merely skip all test functions for the current row of
769 global data, set up by \c initTestCase_data().
771 \note This macro can only be used in a test function or \c _data
772 function that is invoked by the test framework.
775 \snippet code/src_qtestlib_qtestcase.cpp 8
777 \section2 Skipping Known Bugs
779 If a test exposes a known bug that will not be fixed immediately, use the
780 QEXPECT_FAIL() macro to document the failure and reference the bug tracking
781 identifier for the known issue. When the test is run, expected failures will
782 be marked as XFAIL in the test output and will not be counted as failures
783 when setting the test program's return code. If an expected failure does
784 not occur, the XPASS (unexpected pass) will be reported in the test output
785 and will be counted as a test failure.
787 For known bugs, QEXPECT_FAIL() is better than QSKIP() because a developer
788 cannot fix the bug without an XPASS result reminding them that the test
789 needs to be updated too. If QSKIP() is used, there is no reminder to revise
790 or re-enable the test, without which subsequent regressions will not be
793 \sa QEXPECT_FAIL(), {Select Appropriate Mechanisms to Exclude Tests}
796/*! \macro QEXPECT_FAIL(dataIndex, comment, mode)
800 The QEXPECT_FAIL() macro marks the next \l QCOMPARE() or \l QVERIFY() as an
801 expected failure. Instead of adding a failure to the test log, an expected
802 failure will be reported.
804 If a \l QVERIFY() or \l QCOMPARE() is marked as an expected failure,
805 but passes instead, an unexpected pass (XPASS) is written to the test log
806 and will be counted as a test failure.
808 The parameter \a dataIndex describes for which entry in the test data the
809 failure is expected. Pass an empty string (\c{""}) if the failure
810 is expected for all entries or if no test data exists.
812 \a comment will be appended to the test log for the expected failure.
814 \a mode is a \l QTest::TestFailMode and sets whether the test should
815 continue to execute or not. The \a mode is applied regardless of
816 whether the expected test failure occurs.
818 \note This macro can only be used in a test function that is invoked
819 by the test framework.
822 \snippet code/src_qtestlib_qtestcase.cpp 9
824 In the example above, an expected fail will be written into the test output
825 if the variable \c i is not 42. If the variable \c i is 42, an unexpected pass
826 is written instead. The QEXPECT_FAIL() has no influence on the second QCOMPARE()
827 statement in the example.
830 \snippet code/src_qtestlib_qtestcase.cpp 10
832 The above testfunction will not continue executing for the test data
833 entry \c{data27} (regardless of the value of \c i).
835 \sa QTest::TestFailMode, QVERIFY(), QCOMPARE()
838/*! \macro QFINDTESTDATA(filename)
843 Returns a QString for the testdata file referred to by \a filename, or an
844 empty QString if the testdata file could not be found.
846 This macro allows the test to load data from an external file without
847 hardcoding an absolute filename into the test, or using relative paths
848 which may be error prone.
850 The returned path will be the first path from the following list which
851 resolves to an existing file or directory:
854 \li \a filename relative to QCoreApplication::applicationDirPath()
855 (only if a QCoreApplication or QApplication object has been created).
856 \li \a filename relative to the test's standard install directory
857 (QLibraryInfo::TestsPath with the lowercased testcase name appended).
858 \li \a filename relative to the directory containing the source file from which
859 QFINDTESTDATA is invoked.
862 If the named file/directory does not exist at any of these locations,
863 a warning is printed to the test log.
865 For example, in this code:
866 \snippet code/src_qtestlib_qtestcase_snippet.cpp 26
868 The testdata file will be resolved as the first existing file from:
871 \li \c{/home/user/build/myxmlparser/tests/tst_myxmlparser/testxml/simple1.xml}
872 \li \c{/usr/local/Qt-5.0.0/tests/tst_myxmlparser/testxml/simple1.xml}
873 \li \c{/home/user/sources/myxmlparser/tests/tst_myxmlparser/testxml/simple1.xml}
876 This allows the test to find its testdata regardless of whether the
877 test has been installed, and regardless of whether the test's build tree
878 is equal to the test's source tree.
880 \note reliable detection of testdata from the source directory requires
881 either that qmake is used, or the \c{QT_TESTCASE_BUILDDIR} macro is defined to
882 point to the working directory from which the compiler is invoked, or only
883 absolute paths to the source files are passed to the compiler. Otherwise, the
884 absolute path of the source directory cannot be determined.
886 \note The \c{QT_TESTCASE_BUILDDIR} macro is also implicitly defined if CMake is used
887 and the QtTest module is linked to the target. You can change the default
888 \c{QT_TESTCASE_BUILDDIR} by setting the QT_TESTCASE_BUILDDIR property on the target.
890 \note For tests that use the \l QTEST_APPLESS_MAIN() macro to generate a
891 \c{main()} function, \c{QFINDTESTDATA} will not attempt to find test data
892 relative to QCoreApplication::applicationDirPath(). In practice, this means that
893 tests using \c{QTEST_APPLESS_MAIN()} will fail to find their test data
894 if run from a shadow build tree.
897/*! \macro QTEST_MAIN(TestClass)
901 Implements a main() function that instantiates an application object and
902 the \a TestClass, and executes all tests in the order they were defined.
903 Use this macro to build stand-alone executables.
905 If \c QT_WIDGETS_LIB is defined, the application object will be a QApplication,
906 if \c QT_GUI_LIB is defined, the application object will be a QGuiApplication,
907 otherwise it will be a QCoreApplication. If qmake is used and the configuration
908 includes \c{QT += widgets}, then \c QT_WIDGETS_LIB will be defined automatically.
909 Similarly, if qmake is used and the configuration includes \c{QT += gui}, then
910 \c QT_GUI_LIB will be defined automatically.
912 \note On platforms that have keypad navigation enabled by default,
913 this macro will forcefully disable it if \c QT_WIDGETS_LIB is defined. This is done
914 to simplify the usage of key events when writing autotests. If you wish to write a
915 test case that uses keypad navigation, you should enable it either in the
916 \c {initTestCase()} or \c {init()} functions of your test case by calling
917 \l {QApplication::setNavigationMode()}.
920 \snippet code/src_qtestlib_qtestcase.cpp 11
922 \sa QTEST_APPLESS_MAIN(), QTEST_GUILESS_MAIN(), QTest::qExec(),
923 QApplication::setNavigationMode()
926/*! \macro QTEST_APPLESS_MAIN(TestClass)
930 Implements a main() function that executes all tests in \a TestClass.
932 Behaves like \l QTEST_MAIN(), but doesn't instantiate a QApplication
933 object. Use this macro for really simple stand-alone non-GUI tests.
938/*! \macro QTEST_GUILESS_MAIN(TestClass)
943 Implements a main() function that instantiates a QCoreApplication object
944 and the \a TestClass, and executes all tests in the order they were
945 defined. Use this macro to build stand-alone executables.
947 Behaves like \l QTEST_MAIN(), but instantiates a QCoreApplication instead
948 of the QApplication object. Use this macro if your test case doesn't need
949 functionality offered by QApplication, but the event loop is still necessary.
959 This macro is used to measure the performance of code within a test.
960 The code to be benchmarked is contained within a code block following
965 \snippet code/src_qtestlib_qtestcase.cpp 27
967 \sa {Qt Test Overview#Creating a Benchmark}{Creating a Benchmark},
968 {Chapter 5: Writing a Benchmark}{Writing a Benchmark}
972 \macro QBENCHMARK_ONCE
977 \brief The QBENCHMARK_ONCE macro is for measuring performance of a
978 code block by running it once.
980 This macro is used to measure the performance of code within a test.
981 The code to be benchmarked is contained within a code block following
984 Unlike QBENCHMARK, the contents of the contained code block is only run
985 once. The elapsed time will be reported as "0" if it's too short to
986 be measured by the selected backend.
988 \sa {Qt Test Overview#Creating a Benchmark}{Creating a Benchmark},
989 {Chapter 5: Writing a Benchmark}{Writing a Benchmark}
992/*! \enum QTest::TestFailMode
994 This enum describes the modes for handling a check, such as by \l
995 QVERIFY() or \l QCOMPARE() macros, that is known to fail. The mode
996 applies regardless of whether the check fails or succeeds.
998 \value Abort Aborts the execution of the test. Use this mode when
999 it doesn't make sense to execute the test any further after
1000 the problematic check.
1002 \value Continue Continues execution of the test after the
1008/*! \enum QTest::KeyAction
1010 This enum describes possible actions for key handling.
1012 \value Press The key is pressed.
1013 \value Release The key is released.
1014 \value Click The key is clicked (pressed and released).
1015 \value Shortcut A shortcut is activated. This value has been added in Qt 5.6.
1018/*! \enum QTest::MouseAction
1020 This enum describes possible actions for mouse handling.
1022 \value MousePress A mouse button is pressed.
1023 \value MouseRelease A mouse button is released.
1024 \value MouseClick A mouse button is clicked (pressed and released).
1025 \value MouseDClick A mouse button is double clicked (pressed and released twice).
1026 \value MouseMove The mouse pointer has moved.
1029/*! \fn void QTest::keyClick(QWidget *widget, Qt::Key key, Qt::KeyboardModifiers modifier = Qt::NoModifier, int delay=-1)
1031 Simulates clicking of \a key with an optional \a modifier on a \a widget.
1032 If \a delay is larger than 0, the test will wait for \a delay milliseconds
1033 before clicking the key.
1036 \snippet code/src_qtestlib_qtestcase_snippet.cpp 14
1038 The first example above simulates clicking the \c escape key on \c
1039 myWidget without any keyboard modifiers and without delay. The
1040 second example simulates clicking \c shift-escape on \c myWidget
1041 following a 200 ms delay of the test.
1043 \sa QTest::keyClicks()
1046/*! \fn void QTest::keyClick(QWidget *widget, char key, Qt::KeyboardModifiers modifier = Qt::NoModifier, int delay=-1)
1049 Simulates clicking of \a key with an optional \a modifier on a \a widget.
1050 If \a delay is larger than 0, the test will wait for \a delay milliseconds
1051 before clicking the key.
1054 \snippet code/src_qtestlib_qtestcase_snippet.cpp 13
1056 The example above simulates clicking \c a on \c myWidget without
1057 any keyboard modifiers and without delay of the test.
1059 \sa QTest::keyClicks()
1062/*! \fn void QTest::keySequence(QWidget *widget, const QKeySequence &keySequence)
1066 Simulates typing of \a keySequence into a \a widget.
1068 \sa QTest::keyClick(), QTest::keyClicks()
1071/*! \fn void QTest::keyClick(QWindow *window, Qt::Key key, Qt::KeyboardModifiers modifier = Qt::NoModifier, int delay=-1)
1075 Simulates clicking of \a key with an optional \a modifier on a \a window.
1076 If \a delay is larger than 0, the test will wait for \a delay milliseconds
1077 before clicking the key.
1080 \snippet code/src_qtestlib_qtestcase_snippet.cpp 29
1082 The first example above simulates clicking the \c escape key on \c
1083 myWindow without any keyboard modifiers and without delay. The
1084 second example simulates clicking \c shift-escape on \c myWindow
1085 following a 200 ms delay of the test.
1087 \sa QTest::keyClicks()
1090/*! \fn void QTest::keyClick(QWindow *window, char key, Qt::KeyboardModifiers modifier = Qt::NoModifier, int delay=-1)
1094 Simulates clicking of \a key with an optional \a modifier on a \a window.
1095 If \a delay is larger than 0, the test will wait for \a delay milliseconds
1096 before clicking the key.
1099 \snippet code/src_qtestlib_qtestcase_snippet.cpp 28
1101 The example above simulates clicking \c a on \c myWindow without
1102 any keyboard modifiers and without delay of the test.
1104 \sa QTest::keyClicks()
1107/*! \fn void QTest::keySequence(QWindow *window, const QKeySequence &keySequence)
1111 Simulates typing of \a keySequence into a \a window.
1113 \sa QTest::keyClick(), QTest::keyClicks()
1116/*! \fn void QTest::keyEvent(KeyAction action, QWidget *widget, Qt::Key key, Qt::KeyboardModifiers modifier = Qt::NoModifier, int delay=-1)
1118 Sends a Qt key event to \a widget with the given \a key and an associated \a action.
1119 Optionally, a keyboard \a modifier can be specified, as well as a \a delay
1120 (in milliseconds) of the test before sending the event.
1123/*! \fn void QTest::keyEvent(KeyAction action, QWidget *widget, char ascii, Qt::KeyboardModifiers modifier = Qt::NoModifier, int delay=-1)
1126 Sends a Qt key event to \a widget with the given key \a ascii and an associated \a action.
1127 Optionally, a keyboard \a modifier can be specified, as well as a \a delay
1128 (in milliseconds) of the test before sending the event.
1131/*! \fn void QTest::keyEvent(KeyAction action, QWindow *window, Qt::Key key, Qt::KeyboardModifiers modifier = Qt::NoModifier, int delay=-1)
1135 Sends a Qt key event to \a window with the given \a key and an associated \a action.
1136 Optionally, a keyboard \a modifier can be specified, as well as a \a delay
1137 (in milliseconds) of the test before sending the event.
1140/*! \fn void QTest::keyEvent(KeyAction action, QWindow *window, char ascii, Qt::KeyboardModifiers modifier = Qt::NoModifier, int delay=-1)
1144 Sends a Qt key event to \a window with the given key \a ascii and an associated \a action.
1145 Optionally, a keyboard \a modifier can be specified, as well as a \a delay
1146 (in milliseconds) of the test before sending the event.
1149/*! \fn void QTest::keyPress(QWidget *widget, Qt::Key key, Qt::KeyboardModifiers modifier = Qt::NoModifier, int delay=-1)
1151 Simulates pressing a \a key with an optional \a modifier on a \a widget. If \a delay
1152 is larger than 0, the test will wait for \a delay milliseconds before pressing the key.
1154 \note At some point you should release the key using \l keyRelease().
1156 \sa QTest::keyRelease(), QTest::keyClick()
1159/*! \fn void QTest::keyPress(QWidget *widget, char key, Qt::KeyboardModifiers modifier = Qt::NoModifier, int delay=-1)
1162 Simulates pressing a \a key with an optional \a modifier on a \a widget.
1163 If \a delay is larger than 0, the test will wait for \a delay milliseconds
1164 before pressing the key.
1166 \note At some point you should release the key using \l keyRelease().
1168 \sa QTest::keyRelease(), QTest::keyClick()
1171/*! \fn void QTest::keyPress(QWindow *window, Qt::Key key, Qt::KeyboardModifiers modifier = Qt::NoModifier, int delay=-1)
1175 Simulates pressing a \a key with an optional \a modifier on a \a window. If \a delay
1176 is larger than 0, the test will wait for \a delay milliseconds before pressing the key.
1178 \note At some point you should release the key using \l keyRelease().
1180 \sa QTest::keyRelease(), QTest::keyClick()
1183/*! \fn void QTest::keyPress(QWindow *window, char key, Qt::KeyboardModifiers modifier = Qt::NoModifier, int delay=-1)
1187 Simulates pressing a \a key with an optional \a modifier on a \a window.
1188 If \a delay is larger than 0, the test will wait for \a delay milliseconds
1189 before pressing the key.
1191 \note At some point you should release the key using \l keyRelease().
1193 \sa QTest::keyRelease(), QTest::keyClick()
1196/*! \fn void QTest::keyRelease(QWidget *widget, Qt::Key key, Qt::KeyboardModifiers modifier = Qt::NoModifier, int delay=-1)
1198 Simulates releasing a \a key with an optional \a modifier on a \a widget.
1199 If \a delay is larger than 0, the test will wait for \a delay milliseconds
1200 before releasing the key.
1202 \sa QTest::keyPress(), QTest::keyClick()
1205/*! \fn void QTest::keyRelease(QWidget *widget, char key, Qt::KeyboardModifiers modifier = Qt::NoModifier, int delay=-1)
1208 Simulates releasing a \a key with an optional \a modifier on a \a widget.
1209 If \a delay is larger than 0, the test will wait for \a delay milliseconds
1210 before releasing the key.
1212 \sa QTest::keyClick()
1215/*! \fn void QTest::keyRelease(QWindow *window, Qt::Key key, Qt::KeyboardModifiers modifier = Qt::NoModifier, int delay=-1)
1219 Simulates releasing a \a key with an optional \a modifier on a \a window.
1220 If \a delay is larger than 0, the test will wait for \a delay milliseconds
1221 before releasing the key.
1223 \sa QTest::keyPress(), QTest::keyClick()
1226/*! \fn void QTest::keyRelease(QWindow *window, char key, Qt::KeyboardModifiers modifier = Qt::NoModifier, int delay=-1)
1230 Simulates releasing a \a key with an optional \a modifier on a \a window.
1231 If \a delay is larger than 0, the test will wait for \a delay milliseconds
1232 before releasing the key.
1234 \sa QTest::keyClick()
1237/*! \fn void QTest::keyClicks(QWidget *widget, const QString &sequence, Qt::KeyboardModifiers modifier = Qt::NoModifier, int delay=-1)
1239 Simulates clicking a \a sequence of keys on a \a
1240 widget. Optionally, a keyboard \a modifier can be specified as
1241 well as a \a delay (in milliseconds) of the test before each key
1245 \snippet code/src_qtestlib_qtestcase_snippet.cpp 15
1247 The example above simulates clicking the sequence of keys
1248 representing "hello world" on \c myWidget without any keyboard
1249 modifiers and without delay of the test.
1251 \sa QTest::keyClick()
1254/*! \fn void QTest::mousePress(QWidget *widget, Qt::MouseButton button, Qt::KeyboardModifiers modifier, QPoint pos = QPoint(), int delay=-1)
1256 Simulates pressing a mouse \a button with an optional \a modifier
1257 on a \a widget. The position is defined by \a pos; the default
1258 position is the center of the widget. If \a delay is specified,
1259 the test will wait for the specified amount of milliseconds before
1262 \sa QTest::mouseRelease(), QTest::mouseClick()
1265/*! \fn void QTest::mousePress(QWindow *window, Qt::MouseButton button, Qt::KeyboardModifiers stateKey, QPoint pos = QPoint(), int delay=-1)
1269 Simulates pressing a mouse \a button with an optional \a stateKey modifier
1270 on a \a window. The position is defined by \a pos; the default
1271 position is the center of the window. If \a delay is specified,
1272 the test will wait for the specified amount of milliseconds before
1275 \sa QTest::mouseRelease(), QTest::mouseClick()
1278/*! \fn void QTest::mouseRelease(QWidget *widget, Qt::MouseButton button, Qt::KeyboardModifiers modifier, QPoint pos = QPoint(), int delay=-1)
1280 Simulates releasing a mouse \a button with an optional \a modifier
1281 on a \a widget. The position of the release is defined by \a pos;
1282 the default position is the center of the widget. If \a delay is
1283 specified, the test will wait for the specified amount of
1284 milliseconds before releasing the button; otherwise, it will wait for a
1285 default amount of time (1 ms), which can be overridden via
1286 \l {Testing Options}{command-line arguments}.
1288 \note If you wish to test a double-click by sending events individually,
1289 specify a short delay, greater than the default, on both mouse release events.
1290 The total of the delays for the press, release, press and release must be
1291 less than QStyleHints::mouseDoubleClickInterval(). But if you don't need
1292 to check state between events, it's better to use QTest::mouseDClick().
1293 \snippet code/src_qtestlib_qtestcase_snippet.cpp 35
1295 \sa QTest::mousePress(), QTest::mouseClick()
1298/*! \fn void QTest::mouseRelease(QWindow *window, Qt::MouseButton button, Qt::KeyboardModifiers stateKey, QPoint pos = QPoint(), int delay=-1)
1302 Simulates releasing a mouse \a button with an optional \a stateKey modifier
1303 on a \a window. The position of the release is defined by \a pos;
1304 the default position is the center of the window. If \a delay is
1305 specified, the test will wait for the specified amount of
1306 milliseconds before releasing the button; otherwise, it will wait for a
1307 default amount of time (1 ms), which can be overridden via
1308 \l {Testing Options}{command-line arguments}.
1310 \note If you wish to test a double-click by sending events individually,
1311 specify a short delay, greater than the default, on both mouse release events.
1312 The total of the delays for the press, release, press and release must be
1313 less than QStyleHints::mouseDoubleClickInterval(). But if you don't need
1314 to check state between events, it's better to use QTest::mouseDClick().
1315 \snippet code/src_qtestlib_qtestcase_snippet.cpp 35
1317 \sa QTest::mousePress(), QTest::mouseClick()
1320/*! \fn void QTest::mouseClick(QWidget *widget, Qt::MouseButton button, Qt::KeyboardModifiers modifier, QPoint pos = QPoint(), int delay=-1)
1322 Simulates clicking a mouse \a button with an optional \a modifier
1323 on a \a widget. The position of the click is defined by \a pos;
1324 the default position is the center of the widget. If \a delay is
1325 specified, the test will wait for the specified amount of
1326 milliseconds before pressing and before releasing the button.
1328 \sa QTest::mousePress(), QTest::mouseRelease()
1331/*! \fn void QTest::mouseClick(QWindow *window, Qt::MouseButton button, Qt::KeyboardModifiers stateKey, QPoint pos = QPoint(), int delay=-1)
1335 Simulates clicking a mouse \a button with an optional \a stateKey modifier
1336 on a \a window. The position of the click is defined by \a pos;
1337 the default position is the center of the window. If \a delay is
1338 specified, the test will wait for the specified amount of
1339 milliseconds before pressing and before releasing the button.
1341 \sa QTest::mousePress(), QTest::mouseRelease()
1344/*! \fn void QTest::mouseDClick(QWidget *widget, Qt::MouseButton button, Qt::KeyboardModifiers modifier, QPoint pos = QPoint(), int delay=-1)
1346 Simulates double clicking a mouse \a button with an optional \a
1347 modifier on a \a widget. The position of the click is defined by
1348 \a pos; the default position is the center of the widget. If \a
1349 delay is specified, the test will wait for the specified amount of
1350 milliseconds before each press and release.
1352 \sa QTest::mouseClick()
1355/*! \fn void QTest::mouseDClick(QWindow *window, Qt::MouseButton button, Qt::KeyboardModifiers stateKey, QPoint pos = QPoint(), int delay=-1)
1359 Simulates double clicking a mouse \a button with an optional \a stateKey
1360 modifier on a \a window. The position of the click is defined by
1361 \a pos; the default position is the center of the window. If \a
1362 delay is specified, the test will wait for the specified amount of
1363 milliseconds before each press and release.
1365 \sa QTest::mouseClick()
1368/*! \fn void QTest::mouseMove(QWidget *widget, QPoint pos = QPoint(), int delay=-1)
1370 Moves the mouse pointer to a \a widget. If \a pos is not
1371 specified, the mouse pointer moves to the center of the widget. If
1372 a \a delay (in milliseconds) is given, the test will wait before
1373 moving the mouse pointer.
1376/*! \fn void QTest::mouseMove(QWindow *window, QPoint pos = QPoint(), int delay=-1)
1380 Moves the mouse pointer to a \a window. If \a pos is not
1381 specified, the mouse pointer moves to the center of the window. If
1382 a \a delay (in milliseconds) is given, the test will wait before
1383 moving the mouse pointer.
1386/*! \fn void QTest::wheelEvent(QWindow *window, QPointF pos, QPoint angleDelta, QPoint pixelDelta = QPoint(0, 0), Qt::KeyboardModifiers stateKey = Qt::NoModifier, Qt::ScrollPhase phase = Qt::NoScrollPhase)
1389 Simulates a wheel event within \a window at position \a pos in local
1390 window coordinates. \a angleDelta contains the wheel rotation angle.
1391 A positive value means forward rotation, and a negative one means backward.
1392 \a pixelDelta contains the scrolling distance in pixels on screen. This value can be null.
1393 The keyboard states at the time of the event are specified by \a stateKey.
1394 The scrolling phase of the event is specified by \a phase.
1398 \fn template <typename T1, typename T2> char *QTest::toString(const std::pair<T1, T2> &pair)
1401 Returns a textual representation of the \a pair.
1405 \fn char *QTest::toString(const QVector2D &v)
1408 Returns a textual representation of the 2D vector \a v.
1412 \fn char *QTest::toString(const QVector3D &v)
1415 Returns a textual representation of the 3D vector \a v.
1419 \fn char *QTest::toString(const QVector4D &v)
1422 Returns a textual representation of the 4D vector \a v.
1426 \fn template<typename T, QTest::Internal::is_suitable_type_v<T> = true> char *QTest::toString(const T &value)
1428 Returns a textual representation of \a value. This function is used by
1429 \l QCOMPARE() to output verbose information in case of a test failure.
1431 You can add specializations or overloads of this function to your test to enable
1434 \note Starting with Qt 5.5, you should prefer to provide a toString() function
1435 in the type's namespace instead of specializing this template.
1436 If your code needs to continue to work with the QTestLib from Qt 5.4 or
1437 earlier, you need to continue to use specialization.
1439 \note The caller of toString() must delete the returned data
1440 using \c{delete[]}. Your implementation should return a string
1441 created with \c{new[]} or qstrdup(). The easiest way to do so is to
1442 create a QByteArray or QString and call QTest::toString() on it
1443 (see second example below).
1445 Example for specializing (Qt ≤ 5.4):
1447 \snippet code/src_qtestlib_qtestcase_snippet.cpp 16
1449 The example above defines a toString() specialization for a class
1450 called \c MyPoint. Whenever a comparison of two instances of \c
1451 MyPoint fails, \l QCOMPARE() will call this function to output the
1452 contents of \c MyPoint to the test log.
1454 Same example, but with overloading (Qt ≥ 5.5):
1456 \snippet code/src_qtestlib_qtestcase_snippet.cpp toString-overload
1462 \fn char *QTest::toString(const QLatin1StringView &string)
1465 Returns a textual representation of the given \a string.
1469 \fn char *QTest::toString(std::nullptr_t)
1473 Returns a string containing \nullptr.
1477 \fn char *QTest::toString(const QStringView &string)
1481 Returns a textual representation of the given \a string.
1485 \fn char *QTest::toString(const QUuid &uuid)
1489 Returns a textual representation of the given \a uuid.
1493 \fn char *QTest::toString(const QString &string)
1496 Returns a textual representation of the given \a string.
1500 \fn char *QTest::toString(const QByteArray &ba)
1503 Returns a textual representation of the byte array \a ba.
1505 \sa QTest::toHexRepresentation()
1509 \fn char *QTest::toString(const QCborError &c)
1513 Returns a textual representation of the given CBOR error \a c.
1517 \fn template <class... Types> char *QTest::toString(const std::tuple<Types...> &tuple)
1521 Returns a textual representation of the given \a tuple.
1525 \fn char *QTest::toString(const QTime &time)
1528 Returns a textual representation of the given \a time.
1532 \fn char *QTest::toString(const QDate &date)
1535 Returns a textual representation of the given \a date.
1539 \fn char *QTest::toString(const QDateTime &dateTime)
1542 Returns a textual representation of the date and time specified by
1547 \fn char *QTest::toString(const QChar &character)
1550 Returns a textual representation of the given \a character.
1554 \fn char *QTest::toString(const QPoint &point)
1557 Returns a textual representation of the given \a point.
1561 \fn char *QTest::toString(const QSize &size)
1564 Returns a textual representation of the given \a size.
1568 \fn char *QTest::toString(const QRect &rectangle)
1571 Returns a textual representation of the given \a rectangle.
1575 \fn char *QTest::toString(const QUrl &url)
1579 Returns a textual representation of the given \a url.
1583 \fn char *QTest::toString(const QPointF &point)
1586 Returns a textual representation of the given \a point.
1590 \fn char *QTest::toString(const QSizeF &size)
1593 Returns a textual representation of the given \a size.
1597 \fn char *QTest::toString(const QRectF &rectangle)
1600 Returns a textual representation of the given \a rectangle.
1604 \fn char *QTest::toString(const QVariant &variant)
1607 Returns a textual representation of the given \a variant.
1611 \fn char *toString(QSizePolicy::ControlType ct)
1616 Returns a textual representation of control type \a ct.
1620 \fn char *toString(QSizePolicy::ControlTypes cts)
1625 Returns a textual representation of control types \a cts.
1629 \fn char *toString(QSizePolicy::Policy p)
1634 Returns a textual representation of policy \a p.
1638 \fn char *toString(QSizePolicy sp)
1643 Returns a textual representation of size policy \a sp.
1647 \fn char *QTest::toString(const QKeySequence &ks)
1650 Returns a textual representation of the key sequence \a ks.
1654 \fn QPointingDevice * QTest::createTouchDevice(QInputDevice::DeviceType devType = QInputDevice::DeviceType::TouchScreen, QInputDevice::Capabilities caps = QInputDevice::Capability::Position)
1657 Creates a dummy touch device of type \a devType with capabilities \a caps for
1658 simulation of touch events.
1660 The touch device will be registered with the Qt window system interface.
1661 You should typically use createTouchDevice() to initialize a QPointingDevice
1662 member variable in your test case class, use the same instance for all tests and
1663 delete it when no longer needed.
1665 \sa QTest::QTouchEventSequence, touchEvent()
1669 \class QTest::QTouchEventSequence
1673 \brief The QTouchEventSequence class is used to simulate a sequence of touch events.
1675 To simulate a sequence of touch events on a specific device for a window or widget, call
1676 QTest::touchEvent to create a QTouchEventSequence instance. Add touch events to
1677 the sequence by calling press(), move(), release() and stationary(), and let the
1678 instance run out of scope to commit the sequence to the event system.
1681 \snippet code/src_qtestlib_qtestcase_snippet.cpp 25
1685 \fn QTest::QTouchEventSequence::~QTouchEventSequence()
1687 Commits this sequence of touch events, unless autoCommit was disabled, and frees allocated resources.
1691 \fn bool QTest::QTouchEventSequence::commit(bool processEvents)
1693 Commits this touch event to the event system, and returns whether it was
1694 accepted after delivery.
1696 Normally there is no need to call this function because it is called from
1697 the destructor. However, if autoCommit is disabled, the events only get
1698 committed upon explicitly calling this function. Another reason to call it
1699 explicitly is to check the return value.
1701 In special cases, tests may want to disable the processing of the event.
1702 This can be achieved by setting \a processEvents to false. This results in
1703 merely queuing the event: the event loop will not be forced to process it.
1705 Returns whether the event was accepted after delivery.
1709 \fn QTouchEventSequence &QTest::QTouchEventSequence::press(int touchId, const QPoint &pt, QWindow *window)
1712 Adds a press event for touchpoint \a touchId at position \a pt to this sequence and returns
1713 a reference to this QTouchEventSequence.
1715 The position \a pt is interpreted as relative to \a window. If \a window is the null pointer, then
1716 \a pt is interpreted as relative to the window provided when instantiating this QTouchEventSequence.
1718 Simulates that the user pressed the touch screen or pad with the finger identified by \a touchId.
1722 \fn QTouchEventWidgetSequence &QTest::QTouchEventWidgetSequence::press(int touchId, const QPoint &pt, QWidget *widget)
1724 Adds a press event for touchpoint \a touchId at position \a pt to this sequence and returns
1725 a reference to this QTouchEventWidgetSequence.
1727 The position \a pt is interpreted as relative to \a widget. If \a widget is the null pointer, then
1728 \a pt is interpreted as relative to the widget provided when instantiating this QTouchEventWidgetSequence.
1730 Simulates that the user pressed the touch screen or pad with the finger identified by \a touchId.
1734 \fn QTouchEventSequence &QTest::QTouchEventSequence::move(int touchId, const QPoint &pt, QWindow *window)
1737 Adds a move event for touchpoint \a touchId at position \a pt to this sequence and returns
1738 a reference to this QTouchEventSequence.
1740 The position \a pt is interpreted as relative to \a window. If \a window is the null pointer, then
1741 \a pt is interpreted as relative to the window provided when instantiating this QTouchEventSequence.
1743 Simulates that the user moved the finger identified by \a touchId.
1747 \fn QTouchEventWidgetSequence &QTest::QTouchEventWidgetSequence::move(int touchId, const QPoint &pt, QWidget *widget)
1749 Adds a move event for touchpoint \a touchId at position \a pt to this sequence and returns
1750 a reference to this QTouchEventWidgetSequence.
1752 The position \a pt is interpreted as relative to \a widget. If \a widget is the null pointer, then
1753 \a pt is interpreted as relative to the widget provided when instantiating this QTouchEventWidgetSequence.
1755 Simulates that the user moved the finger identified by \a touchId.
1759 \fn QTouchEventSequence &QTest::QTouchEventSequence::release(int touchId, const QPoint &pt, QWindow *window)
1762 Adds a release event for touchpoint \a touchId at position \a pt to this sequence and returns
1763 a reference to this QTouchEventSequence.
1765 The position \a pt is interpreted as relative to \a window. If \a window is the null pointer, then
1766 \a pt is interpreted as relative to the window provided when instantiating this QTouchEventSequence.
1768 Simulates that the user lifted the finger identified by \a touchId.
1772 \fn QTouchEventWidgetSequence &QTest::QTouchEventWidgetSequence::release(int touchId, const QPoint &pt, QWidget *widget)
1774 Adds a release event for touchpoint \a touchId at position \a pt to this sequence and returns
1775 a reference to this QTouchEventWidgetSequence.
1777 The position \a pt is interpreted as relative to \a widget. If \a widget is the null pointer, then
1778 \a pt is interpreted as relative to the widget provided when instantiating this QTouchEventWidgetSequence.
1780 Simulates that the user lifted the finger identified by \a touchId.
1784 \fn QTouchEventSequence &QTest::QTouchEventSequence::stationary(int touchId)
1786 Adds a stationary event for touchpoint \a touchId to this sequence and returns
1787 a reference to this QTouchEventSequence.
1789 Simulates that the user did not move the finger identified by \a touchId.
1793 \fn QTouchEventSequence QTest::touchEvent(QWindow *window, QPointingDevice *device, bool autoCommit)
1796 Creates and returns a QTouchEventSequence for the \a device to
1797 simulate events for \a window.
1799 When adding touch events to the sequence, \a window will also be used to translate
1800 the position provided to screen coordinates, unless another window is provided in the
1801 respective calls to press(), move() etc.
1803 The touch events are committed to the event system when the destructor of the
1804 QTouchEventSequence is called (ie when the object returned runs out of scope), unless
1805 \a autoCommit is set to false. When \a autoCommit is false, commit() has to be called
1808 \l createTouchDevice() can be called to create a test touch device for use with this
1813 \fn QTouchEventSequence QTest::touchEvent(QWidget *widget, QPointingDevice *device, bool autoCommit)
1815 Creates and returns a QTouchEventSequence for the \a device to
1816 simulate events for \a widget.
1818 When adding touch events to the sequence, \a widget will also be used to translate
1819 the position provided to screen coordinates, unless another widget is provided in the
1820 respective calls to press(), move() etc.
1822 The touch events are committed to the event system when the destructor of the
1823 QTouchEventSequence is called (ie when the object returned runs out of scope), unless
1824 \a autoCommit is set to false. When \a autoCommit is false, commit() has to be called
1827 \l createTouchDevice() can be called to create a test touch device for use with this
1831// Internals of qtestmouse.h:
1833/*! \fn void QTest::mouseEvent(MouseAction action, QWidget *widget, Qt::MouseButton button, Qt::KeyboardModifiers stateKey, QPoint pos, int delay=-1)
1837/*! \fn void QTest::mouseEvent(MouseAction action, QWindow *window, Qt::MouseButton button, Qt::KeyboardModifiers stateKey, QPoint pos, int delay=-1)