Qt
Internal/Contributor docs for the Qt SDK. Note: These are NOT official API docs; those are found at https://doc.qt.io/
Loading...
Searching...
No Matches
qtestcase.qdoc
Go to the documentation of this file.
1// Copyright (C) 2020 The Qt Company Ltd.
2// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
3
4/*!
5 \namespace QTest
6 \inmodule QtTest
7
8 \brief The QTest namespace contains all the functions and
9 declarations that are related to Qt Test.
10
11 See the \l{Qt Test Overview} for information about how to write unit tests.
12*/
13
14/*! \macro QVERIFY(condition)
15
16 \relates QTest
17
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.
21
22 You can use \l QVERIFY2() when it is practical and valuable to put additional
23 information into the test failure report.
24
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]
29
30 For example, the following code shows this macro being used to verify that a
31 \l QSignalSpy object is valid:
32
33 \snippet code/src_qtestlib_qtestcase_snippet.cpp 0
34
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.
38
39 \sa QCOMPARE(), QTRY_VERIFY(), QSignalSpy, QEXPECT_FAIL(), QCOMPARE_EQ(),
40 QCOMPARE_NE(), QCOMPARE_LT(), QCOMPARE_LE(), QCOMPARE_GT(), QCOMPARE_GE()
41*/
42
43/*! \macro QVERIFY2(condition, message)
44
45 \relates QTest
46
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.
49
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.
53
54 Example:
55 \snippet code/src_qtestlib_qtestcase.cpp 1
56
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:
59
60 \snippet code/src_qtestlib_qtestcase.cpp 32
61
62 If this test fails, it will give no clue as to why the file failed to open:
63
64 \c {FAIL! : tst_QFile::open_write() 'opened' returned FALSE. ()}
65
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:
69
70 \snippet code/src_qtestlib_qtestcase.cpp 33
71
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
74 system:
75
76 \c {FAIL! : tst_QFile::open_write() 'opened' returned FALSE.
77 (open /tmp/qt.a3B42Cd: No space left on device)}
78
79 \sa QVERIFY(), QCOMPARE(), QEXPECT_FAIL(), QCOMPARE_EQ(), QCOMPARE_NE(),
80 QCOMPARE_LT(), QCOMPARE_LE(), QCOMPARE_GT(), QCOMPARE_GE()
81*/
82
83/*! \macro QCOMPARE(actual, expected)
84
85 \relates QTest
86
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.
91
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.
98
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.
101
102 Example:
103 \snippet code/src_qtestlib_qtestcase.cpp 2
104
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
110 they're identical).
111
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
115
116 Note that using initializer lists requires defining a helper macro
117 to prevent the preprocessor from interpreting the commas as macro argument
118 delimiters:
119 \snippet code/src_qtestlib_qtestcase.cpp 35
120
121 \include qtestcase.qdoc macro-usage-limitation
122
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]
127
128 Example:
129 \snippet code/src_qtestlib_qtestcase_snippet.cpp 34
130
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.
134
135 \sa QVERIFY(), QTRY_COMPARE(), QTest::toString(), QEXPECT_FAIL(),
136 QCOMPARE_EQ(), QCOMPARE_NE(), QCOMPARE_LT(), QCOMPARE_LE(),
137 QCOMPARE_GT(), QCOMPARE_GE()
138*/
139
140/*! \macro QCOMPARE_EQ(computed, baseline)
141 \since 6.4
142
143 \relates QTest
144
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.
149
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.
153
154 \include qtestcase.qdoc macro-usage-limitation
155
156 \include qtestcase.qdoc to-string-overload-desc
157
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
161 C-style strings.
162
163 \sa QCOMPARE(), QCOMPARE_NE(), QCOMPARE_LT(), QCOMPARE_LE(), QCOMPARE_GT(),
164 QCOMPARE_GE()
165*/
166
167/*! \macro QCOMPARE_NE(computed, baseline)
168 \since 6.4
169
170 \relates QTest
171
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.
176
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.
180
181 \include qtestcase.qdoc macro-usage-limitation
182
183 \include qtestcase.qdoc to-string-overload-desc
184
185 \sa QCOMPARE_EQ(), QCOMPARE_LT(), QCOMPARE_LE(), QCOMPARE_GT(), QCOMPARE_GE()
186*/
187
188/*! \macro QCOMPARE_LT(computed, baseline)
189 \since 6.4
190
191 \relates QTest
192
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
196 any later checks.
197
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.
201
202 \include qtestcase.qdoc macro-usage-limitation
203
204 \include qtestcase.qdoc to-string-overload-desc
205
206 \sa QCOMPARE_EQ(), QCOMPARE_NE(), QCOMPARE_LE(), QCOMPARE_GT(), QCOMPARE_GE()
207*/
208
209/*! \macro QCOMPARE_LE(computed, baseline)
210 \since 6.4
211
212 \relates QTest
213
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.
218
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.
222
223 \include qtestcase.qdoc macro-usage-limitation
224
225 \include qtestcase.qdoc to-string-overload-desc
226
227 \sa QCOMPARE_EQ(), QCOMPARE_NE(), QCOMPARE_LT(), QCOMPARE_GT(), QCOMPARE_GE()
228*/
229
230/*! \macro QCOMPARE_GT(computed, baseline)
231 \since 6.4
232
233 \relates QTest
234
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.
239
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.
243
244 \include qtestcase.qdoc macro-usage-limitation
245
246 \include qtestcase.qdoc to-string-overload-desc
247
248 \sa QCOMPARE_EQ(), QCOMPARE_NE(), QCOMPARE_LT(), QCOMPARE_LE(), QCOMPARE_GE()
249*/
250
251/*! \macro QCOMPARE_GE(computed, baseline)
252 \since 6.4
253
254 \relates QTest
255
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.
260
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.
264
265 \include qtestcase.qdoc macro-usage-limitation
266
267 \include qtestcase.qdoc to-string-overload-desc
268
269 \sa QCOMPARE_EQ(), QCOMPARE_NE(), QCOMPARE_LT(), QCOMPARE_LE(), QCOMPARE_GT()
270*/
271
272/*! \macro QCOMPARE_3WAY(lhs, rhs, order)
273 \since 6.9
274
275 \relates QTest
276
277 The QCOMPARE_3WAY() macro applies the three-way comparison operator \c {<=>}
278 to the input expressions \a lhs and \a rhs, and checks if the result
279 is \a order.
280 If that is true, execution continues. If not, a
281 failure is recorded in the test log and the test function returns without
282 attempting any later checks.
283 The macro only accepts Qt:: and std:: ordering types as \a order
284 argument, otherwise it asserts.
285 \note \a order can be a Qt:: ordering type even if a
286 \c {decltype(lhs <=> rhs)} is a std one.
287 The result of \c {decltype(lhs <=> rhs)} operation should have the same
288 strength as \a order. Otherwise, applying the macro will result in
289 a compilation error. For example, if the result of \c {decltype(lhs <=> rhs)}
290 has a weak ordering type, the \a order argument can't have partial
291 or strong ordering types.
292 \note The macro only works if the compiler supports the \c{<=>} operator,
293 and otherwise it statically asserts that the prerequisite feature
294 isn't available. Before a macro usage always check if
295 \c __cpp_lib_three_way_comparison is defined, and use QSKIP, if it isn't.
296
297 \include qtestcase.qdoc macro-usage-limitation
298
299 \include qtestcase.qdoc to-string-overload-desc
300*/
301
302/*! \macro QVERIFY_EXCEPTION_THROWN(expression, exceptiontype)
303 \since 5.3
304
305 \relates QTest
306 \deprecated [6.3] Use \c{QVERIFY_THROWS_EXCEPTION(exceptiontype, expression)} instead.
307*/
308
309/*!
310 \macro QVERIFY_THROWS_EXCEPTION(exceptiontype, ...)
311 \relates QTest
312 \since 6.3
313
314 The QVERIFY_THROWS_EXCEPTION macro executes the expression given in the variadic
315 argument and expects to catch an exception thrown from the expression.
316
317 There are several possible outcomes:
318
319 \list
320 \li If the expression throws an exception that is either the same as
321 \a exceptiontype or derived from \a exceptiontype, then execution will continue.
322
323 \li Otherwise, if the expression throws no exception, or the
324 exception thrown derives from \c{std::exception}, then a failure
325 will be recorded in the test log and the macro returns early
326 (from enclosing function).
327
328 \li If the thrown exception derives neither from \c{std::exception} nor from
329 \a exceptiontype, a failure will be recorded in the test log, and the exception is
330 re-thrown. This avoids problems with e.g. pthread cancellation exceptions.
331 \endlist
332
333 The macro uses variadic arguments so the expression can contain commas that the
334 preprocessor considers argument separators, e.g. as in
335 \code
336 QVERIFY_THROWS_EXCEPTION(std::bad_alloc,
337 // macro arguments: ^ exceptiontype
338 std::vector<std::pair<int, long>>{42'000'000'000, {42, 42L}});
339 // macro arguments: \---------- 1 ----------/ \-------- 2 --------/ \3/ \ 4 /
340 // \----------------------- expression -----------------------/
341 \endcode
342
343 \note This macro can only be used in a test function that is invoked
344 by the test framework.
345*/
346
347/*!
348 \macro QVERIFY_THROWS_NO_EXCEPTION(...)
349 \since 6.3
350
351 \relates QTest
352
353 The QVERIFY_THROWS_NO_EXCEPTION macro executes the expression given in its
354 variadic argument and tries to catch any exception thrown from the expression.
355
356 There are several different outcomes:
357
358 \list
359 \li If the expression does not throw an exception, then execution will continue.
360
361 \li Otherwise, if an exception derived from \c{std::exception} is caught, a failure
362 will be recorded in the test log and the macro returns early (implicit return from
363 enclosing function).
364
365 \li If an exception not derived from \c{std::exception} is caught, a failure will be
366 recorded in the test log and the exception will be re-thrown. This avoids problems
367 with e.g. pthread cancellation exceptions.
368 \endlist
369
370 The macro uses variadic arguments so the expression can contain commas that the
371 preprocessor considers argument separators, e.g. as in
372 \code
373 QVERIFY_THROWS_NO_EXCEPTION(std::pair<int, long>{42, 42L});
374 // macro arguments: \---- 1 ----/ \-- 2 -/ \3 /
375 \endcode
376
377 \note This macro can only be used in a test function that is invoked
378 by the test framework.
379*/
380
381/*! \macro QTRY_VERIFY_WITH_TIMEOUT(condition, timeout)
382 \since 5.0
383
384 \relates QTest
385
386 The QTRY_VERIFY_WITH_TIMEOUT() macro is similar to QVERIFY(), but checks the \a condition
387 repeatedly, until either the condition becomes true or the \a timeout (in milliseconds) is
388 reached. Between each evaluation, events will be processed. If the timeout
389 is reached, a failure is recorded in the test log and the test won't be
390 executed further.
391
392 //![chrono-timeout]
393 Since Qt 6.8, the \a timeout can also be a \c{std::chrono} literal such as \c{2s}.
394 //![chrono-timeout]
395
396 \note This macro can only be used in a test function that is invoked
397 by the test framework.
398
399 \sa QTRY_VERIFY(), QTRY_VERIFY2_WITH_TIMEOUT(), QVERIFY(), QCOMPARE(), QTRY_COMPARE(),
400 QEXPECT_FAIL()
401*/
402
403
404/*! \macro QTRY_VERIFY(condition)
405 \since 5.0
406
407 \relates QTest
408
409 Checks the \a condition by invoking QTRY_VERIFY_WITH_TIMEOUT() with a timeout of five seconds.
410
411 \note This macro can only be used in a test function that is invoked
412 by the test framework.
413
414 \sa QTRY_VERIFY_WITH_TIMEOUT(), QTRY_VERIFY2(), QVERIFY(), QCOMPARE(), QTRY_COMPARE(),
415 QEXPECT_FAIL()
416*/
417
418/*! \macro QTRY_VERIFY2_WITH_TIMEOUT(condition, message, timeout)
419 \since 5.6
420
421 \relates QTest
422
423 The QTRY_VERIFY2_WITH_TIMEOUT macro is similar to QTRY_VERIFY_WITH_TIMEOUT()
424 except that it outputs a verbose \a message when \a condition is still false
425 after the specified \a timeout (in milliseconds). The \a message is a plain C string.
426
427 \include qtestcase.qdoc chrono-timeout
428
429 Example:
430 \code
431 QTRY_VERIFY2_WITH_TIMEOUT(list.size() > 2, QByteArray::number(list.size()).constData(), 10s);
432 \endcode
433
434 \note This macro can only be used in a test function that is invoked
435 by the test framework.
436
437 \sa QTRY_VERIFY(), QTRY_VERIFY_WITH_TIMEOUT(), QVERIFY(), QCOMPARE(), QTRY_COMPARE(),
438 QEXPECT_FAIL()
439*/
440
441/*! \macro QTRY_VERIFY2(condition, message)
442 \since 5.6
443
444 \relates QTest
445
446 Checks the \a condition by invoking QTRY_VERIFY2_WITH_TIMEOUT() with a timeout
447 of five seconds. If \a condition is then still false, \a message is output.
448 The \a message is a plain C string.
449
450 Example:
451 \code
452 QTRY_VERIFY2(list.size() > 2, QByteArray::number(list.size()).constData());
453 \endcode
454
455 \note This macro can only be used in a test function that is invoked
456 by the test framework.
457
458 \sa QTRY_VERIFY2_WITH_TIMEOUT(), QTRY_VERIFY2(), QVERIFY(), QCOMPARE(), QTRY_COMPARE(),
459 QEXPECT_FAIL()
460*/
461
462/*! \macro QTRY_COMPARE_WITH_TIMEOUT(actual, expected, timeout)
463 \since 5.0
464
465 \relates QTest
466
467 The QTRY_COMPARE_WITH_TIMEOUT() macro is similar to QCOMPARE(), but performs the comparison
468 of the \a actual and \a expected values repeatedly, until either the two values
469 are equal or the \a timeout (in milliseconds) is reached. Between each comparison, events
470 will be processed. If the timeout is reached, a failure is recorded in the
471 test log and the test won't be executed further.
472
473 \include qtestcase.qdoc chrono-timeout
474
475 \note This macro can only be used in a test function that is invoked
476 by the test framework.
477
478 \sa QTRY_COMPARE(), QCOMPARE(), QVERIFY(), QTRY_VERIFY(), QEXPECT_FAIL()
479*/
480
481/*! \macro QTRY_COMPARE(actual, expected)
482 \since 5.0
483
484 \relates QTest
485
486 Performs a comparison of the \a actual and \a expected values by
487 invoking QTRY_COMPARE_WITH_TIMEOUT() with a timeout of five seconds.
488
489 \note This macro can only be used in a test function that is invoked
490 by the test framework.
491
492 \sa QTRY_COMPARE_WITH_TIMEOUT(), QCOMPARE(), QVERIFY(), QTRY_VERIFY(),
493 QEXPECT_FAIL()
494*/
495
496/*! \macro QTRY_COMPARE_EQ_WITH_TIMEOUT(computed, baseline, timeout)
497 \since 6.4
498 \relates QTest
499
500 This macro is similar to QCOMPARE_EQ(), but performs the comparison of the
501 \a computed and \a baseline values repeatedly, until either the comparison returns
502 \c true or the \a timeout (in milliseconds) is reached. Between each
503 comparison, events will be processed. If the timeout is reached, a failure
504 is recorded in the test log and the test won't be executed further.
505
506 \include qtestcase.qdoc chrono-timeout
507
508 \include qtestcase.qdoc macro-usage-limitation
509
510 \sa QCOMPARE_EQ(), QTRY_COMPARE_EQ()
511*/
512
513/*! \macro QTRY_COMPARE_EQ(computed, baseline)
514 \since 6.4
515 \relates QTest
516
517 Performs comparison of \a computed and \a baseline values by invoking
518 QTRY_COMPARE_EQ_WITH_TIMEOUT with a timeout of five seconds.
519
520 \include qtestcase.qdoc macro-usage-limitation
521
522 \sa QCOMPARE_EQ(), QTRY_COMPARE_EQ_WITH_TIMEOUT()
523*/
524
525/*! \macro QTRY_COMPARE_NE_WITH_TIMEOUT(computed, baseline, timeout)
526 \since 6.4
527 \relates QTest
528
529 This macro is similar to QCOMPARE_NE(), but performs the comparison of the
530 \a computed and \a baseline values repeatedly, until either the comparison returns
531 \c true or the \a timeout (in milliseconds) is reached. Between each
532 comparison, events will be processed. If the timeout is reached, a failure
533 is recorded in the test log and the test won't be executed further.
534
535 \include qtestcase.qdoc chrono-timeout
536
537 \include qtestcase.qdoc macro-usage-limitation
538
539 \sa QCOMPARE_NE(), QTRY_COMPARE_NE()
540*/
541
542/*! \macro QTRY_COMPARE_NE(computed, baseline)
543 \since 6.4
544 \relates QTest
545
546 Performs comparison of \a computed and \a baseline values by invoking
547 QTRY_COMPARE_NE_WITH_TIMEOUT with a timeout of five seconds.
548
549 \include qtestcase.qdoc macro-usage-limitation
550
551 \sa QCOMPARE_NE(), QTRY_COMPARE_NE_WITH_TIMEOUT()
552*/
553
554/*! \macro QTRY_COMPARE_LT_WITH_TIMEOUT(computed, baseline, timeout)
555 \since 6.4
556 \relates QTest
557
558 This macro is similar to QCOMPARE_LT(), but performs the comparison of the
559 \a computed and \a baseline values repeatedly, until either the comparison returns
560 \c true or the \a timeout (in milliseconds) is reached. Between each
561 comparison, events will be processed. If the timeout is reached, a failure
562 is recorded in the test log and the test won't be executed further.
563
564 \include qtestcase.qdoc chrono-timeout
565
566 \include qtestcase.qdoc macro-usage-limitation
567
568 \sa QCOMPARE_LT(), QTRY_COMPARE_LT()
569*/
570
571/*! \macro QTRY_COMPARE_LT(computed, baseline)
572 \since 6.4
573 \relates QTest
574
575 Performs comparison of \a computed and \a baseline values by invoking
576 QTRY_COMPARE_LT_WITH_TIMEOUT with a timeout of five seconds.
577
578 \include qtestcase.qdoc macro-usage-limitation
579
580 \sa QCOMPARE_LT(), QTRY_COMPARE_LT_WITH_TIMEOUT()
581*/
582
583/*! \macro QTRY_COMPARE_LE_WITH_TIMEOUT(computed, baseline, timeout)
584 \since 6.4
585 \relates QTest
586
587 This macro is similar to QCOMPARE_LE(), but performs the comparison of the
588 \a computed and \a baseline values repeatedly, until either the comparison returns
589 \c true or the \a timeout (in milliseconds) is reached. Between each
590 comparison, events will be processed. If the timeout is reached, a failure
591 is recorded in the test log and the test won't be executed further.
592
593 \include qtestcase.qdoc chrono-timeout
594
595 \include qtestcase.qdoc macro-usage-limitation
596
597 \sa QCOMPARE_LE(), QTRY_COMPARE_LE()
598*/
599
600/*! \macro QTRY_COMPARE_LE(computed, baseline)
601 \since 6.4
602 \relates QTest
603
604 Performs comparison of \a computed and \a baseline values by invoking
605 QTRY_COMPARE_LE_WITH_TIMEOUT with a timeout of five seconds.
606
607 \include qtestcase.qdoc macro-usage-limitation
608
609 \sa QCOMPARE_LE(), QTRY_COMPARE_LE_WITH_TIMEOUT()
610*/
611
612/*! \macro QTRY_COMPARE_GT_WITH_TIMEOUT(computed, baseline, timeout)
613 \since 6.4
614 \relates QTest
615
616 This macro is similar to QCOMPARE_GT(), but performs the comparison of the
617 \a computed and \a baseline values repeatedly, until either the comparison returns
618 \c true or the \a timeout (in milliseconds) is reached. Between each
619 comparison, events will be processed. If the timeout is reached, a failure
620 is recorded in the test log and the test won't be executed further.
621
622 \include qtestcase.qdoc chrono-timeout
623
624 \include qtestcase.qdoc macro-usage-limitation
625
626 \sa QCOMPARE_GT(), QTRY_COMPARE_GT()
627*/
628
629/*! \macro QTRY_COMPARE_GT(computed, baseline)
630 \since 6.4
631 \relates QTest
632
633 Performs comparison of \a computed and \a baseline values by invoking
634 QTRY_COMPARE_GT_WITH_TIMEOUT with a timeout of five seconds.
635
636 \include qtestcase.qdoc macro-usage-limitation
637
638 \sa QCOMPARE_GT(), QTRY_COMPARE_GT_WITH_TIMEOUT()
639*/
640
641/*! \macro QTRY_COMPARE_GE_WITH_TIMEOUT(computed, baseline, timeout)
642 \since 6.4
643 \relates QTest
644
645 This macro is similar to QCOMPARE_GE(), but performs the comparison of the
646 \a computed and \a baseline values repeatedly, until either the comparison returns
647 \c true or the \a timeout (in milliseconds) is reached. Between each
648 comparison, events will be processed. If the timeout is reached, a failure
649 is recorded in the test log and the test won't be executed further.
650
651 \include qtestcase.qdoc chrono-timeout
652
653 \include qtestcase.qdoc macro-usage-limitation
654
655 \sa QCOMPARE_GE(), QTRY_COMPARE_GE()
656*/
657
658/*! \macro QTRY_COMPARE_GE(computed, baseline)
659 \since 6.4
660 \relates QTest
661
662 Performs comparison of \a computed and \a baseline values by invoking
663 QTRY_COMPARE_GE_WITH_TIMEOUT with a timeout of five seconds.
664
665 \include qtestcase.qdoc macro-usage-limitation
666
667 \sa QCOMPARE_GE(), QTRY_COMPARE_GE_WITH_TIMEOUT()
668*/
669
670/*! \macro QFETCH(type, name)
671
672 \relates QTest
673
674 The fetch macro creates a local variable named \a name with the type \a type
675 on the stack. The \a name and \a type must match a column from the test's
676 data table. This is asserted and the test will abort if the assertion fails.
677
678 Assuming a test has the following data:
679
680 \snippet code/src_qtestlib_qtestcase.cpp 3
681
682 The test data has two elements, a QString called \c aString and an integer
683 called \c expected. To fetch these values in the actual test:
684
685 \snippet code/src_qtestlib_qtestcase.cpp 4
686
687 \c aString and \c expected are variables on the stack that are initialized with
688 the current test data.
689
690 \note This macro can only be used in a test function that is invoked
691 by the test framework. The test function must have a _data function.
692*/
693
694/*! \macro QFETCH_GLOBAL(type, name)
695
696 \relates QTest
697
698 This macro fetches a variable named \a name with the type \a type from
699 a row in the global data table. The \a name and \a type must match a
700 column in the global data table. This is asserted and the test will abort
701 if the assertion fails.
702
703 Assuming a test has the following data:
704
705 \snippet code/src_qtestlib_qtestcase_snippet.cpp 30
706
707 The test's own data is a single number per row. In this case,
708 \c initTestCase_data() also supplies a locale per row. Therefore,
709 this test will be run with every combination of locale from the
710 latter and number from the former. Thus, with four rows in the
711 global table and three in the local, the test function is run for
712 12 distinct test-cases (4 * 3 = 12).
713
714 \snippet code/src_qtestlib_qtestcase_snippet.cpp 31
715
716 The locale is read from the global data table using QFETCH_GLOBAL(),
717 and the number is read from the local data table using QFETCH().
718
719 \note This macro can only be used in test methods of a class with an
720 \c initTestCase_data() method.
721*/
722
723/*! \macro QWARN(message)
724
725 \relates QTest
726 \threadsafe
727 \deprecated Use qWarning() instead.
728
729 Appends \a message as a warning to the test log. This macro can be used anywhere
730 in your tests.
731*/
732
733/*! \macro QFAIL(message)
734
735 \relates QTest
736
737 This macro can be used to force a test failure. The test stops
738 executing and the failure \a message is appended to the test log.
739
740 \note This macro can only be used in a test function that is invoked
741 by the test framework.
742
743 Example:
744
745 \snippet code/src_qtestlib_qtestcase.cpp 5
746*/
747
748/*! \macro QTEST(actual, testElement)
749
750 \relates QTest
751
752 QTEST() is a convenience macro for \l QCOMPARE() that compares
753 the value \a actual with the element \a testElement from the test's data.
754 If there is no such element, the test asserts.
755
756 Apart from that, QTEST() behaves exactly as \l QCOMPARE().
757
758 Instead of writing:
759
760 \snippet code/src_qtestlib_qtestcase.cpp 6
761
762 you can write:
763
764 \snippet code/src_qtestlib_qtestcase.cpp 7
765
766 \sa QCOMPARE()
767*/
768
769/*! \macro QSKIP(description)
770
771 \relates QTest
772
773 If called from a test function, the QSKIP() macro stops execution of the test
774 without adding a failure to the test log. You can use it to skip tests that
775 wouldn't make sense in the current configuration. For example, a test of font
776 rendering may call QSKIP() if the needed fonts are not installed on the test
777 system.
778
779 The text \a description is appended to the test log and should contain an
780 explanation of why the test couldn't be executed.
781
782 If the test is data-driven, each call to QSKIP() in the test function will
783 skip only the current row of test data, so an unconditional call to QSKIP()
784 will produce one skip message in the test log for each row of test data.
785
786 If called from an \c _data function, the QSKIP() macro will stop execution of
787 the \c _data function and will prevent execution of the associated test
788 function. This entirely omits a data-driven test. To omit individual rows,
789 make them conditional by using a simple \c{if (condition) newRow(...) << ...}
790 in the \c _data function, instead of using QSKIP() in the test function.
791
792 If called from \c initTestCase_data(), the QSKIP() macro will skip all test
793 and \c _data functions. If called from \c initTestCase() when there is no
794 \c initTestCase_data(), or when it only sets up one row, QSKIP() will
795 likewise skip the whole test. However, if \c initTestCase_data() contains
796 more than one row, then \c initTestCase() is called (followed by each test
797 and finally the wrap-up) once per row of it. Therefore, a call to QSKIP() in
798 \c initTestCase() will merely skip all test functions for the current row of
799 global data, set up by \c initTestCase_data().
800
801 \note This macro can only be used in a test function or \c _data
802 function that is invoked by the test framework.
803
804 Example:
805 \snippet code/src_qtestlib_qtestcase.cpp 8
806
807 \section2 Skipping Known Bugs
808
809 If a test exposes a known bug that will not be fixed immediately, use the
810 QEXPECT_FAIL() macro to document the failure and reference the bug tracking
811 identifier for the known issue. When the test is run, expected failures will
812 be marked as XFAIL in the test output and will not be counted as failures
813 when setting the test program's return code. If an expected failure does
814 not occur, the XPASS (unexpected pass) will be reported in the test output
815 and will be counted as a test failure.
816
817 For known bugs, QEXPECT_FAIL() is better than QSKIP() because a developer
818 cannot fix the bug without an XPASS result reminding them that the test
819 needs to be updated too. If QSKIP() is used, there is no reminder to revise
820 or re-enable the test, without which subsequent regressions will not be
821 reported.
822
823 \sa QEXPECT_FAIL(), {Select Appropriate Mechanisms to Exclude Tests}
824*/
825
826/*! \macro QEXPECT_FAIL(dataIndex, comment, mode)
827
828 \relates QTest
829
830 The QEXPECT_FAIL() macro marks the next \l QCOMPARE() or \l QVERIFY() as an
831 expected failure. Instead of adding a failure to the test log, an expected
832 failure will be reported.
833
834 If a \l QVERIFY() or \l QCOMPARE() is marked as an expected failure,
835 but passes instead, an unexpected pass (XPASS) is written to the test log
836 and will be counted as a test failure.
837
838 The parameter \a dataIndex describes for which entry in the test data the
839 failure is expected. Pass an empty string (\c{""}) if the failure
840 is expected for all entries or if no test data exists.
841
842 \a comment will be appended to the test log for the expected failure.
843
844 \a mode is a \l QTest::TestFailMode and sets whether the test should
845 continue to execute or not. The \a mode is applied regardless of
846 whether the expected test failure occurs.
847
848 \note This macro can only be used in a test function that is invoked
849 by the test framework.
850
851 Example 1:
852 \snippet code/src_qtestlib_qtestcase.cpp 9
853
854 In the example above, an expected fail will be written into the test output
855 if the variable \c i is not 42. If the variable \c i is 42, an unexpected pass
856 is written instead. The QEXPECT_FAIL() has no influence on the second QCOMPARE()
857 statement in the example.
858
859 Example 2:
860 \snippet code/src_qtestlib_qtestcase.cpp 10
861
862 The above testfunction will not continue executing for the test data
863 entry \c{data27} (regardless of the value of \c i).
864
865 \sa QTest::TestFailMode, QVERIFY(), QCOMPARE()
866*/
867
868/*! \macro QFINDTESTDATA(filename)
869 \since 5.0
870
871 \relates QTest
872
873 Returns a QString for the testdata file referred to by \a filename, or an
874 empty QString if the testdata file could not be found.
875
876 This macro allows the test to load data from an external file without
877 hardcoding an absolute filename into the test, or using relative paths
878 which may be error prone.
879
880 The returned path will be the first path from the following list which
881 resolves to an existing file or directory:
882
883 \list
884 \li \a filename relative to QCoreApplication::applicationDirPath()
885 (only if a QCoreApplication or QApplication object has been created).
886 \li \a filename relative to the test's standard install directory
887 (QLibraryInfo::TestsPath with the lowercased testcase name appended).
888 \li \a filename relative to the directory containing the source file from which
889 QFINDTESTDATA is invoked.
890 \endlist
891
892 If the named file/directory does not exist at any of these locations,
893 a warning is printed to the test log.
894
895 For example, in this code:
896 \snippet code/src_qtestlib_qtestcase_snippet.cpp 26
897
898 The testdata file will be resolved as the first existing file from:
899
900 \list
901 \li \c{/home/user/build/myxmlparser/tests/tst_myxmlparser/testxml/simple1.xml}
902 \li \c{/usr/local/Qt-5.0.0/tests/tst_myxmlparser/testxml/simple1.xml}
903 \li \c{/home/user/sources/myxmlparser/tests/tst_myxmlparser/testxml/simple1.xml}
904 \endlist
905
906 This allows the test to find its testdata regardless of whether the
907 test has been installed, and regardless of whether the test's build tree
908 is equal to the test's source tree.
909
910 \note reliable detection of testdata from the source directory requires
911 either that qmake is used, or the \c{QT_TESTCASE_BUILDDIR} macro is defined to
912 point to the working directory from which the compiler is invoked, or only
913 absolute paths to the source files are passed to the compiler. Otherwise, the
914 absolute path of the source directory cannot be determined.
915
916 \note The \c{QT_TESTCASE_BUILDDIR} macro is also implicitly defined if CMake is used
917 and the QtTest module is linked to the target. You can change the default
918 \c{QT_TESTCASE_BUILDDIR} by setting the QT_TESTCASE_BUILDDIR property on the target.
919
920 \note For tests that use the \l QTEST_APPLESS_MAIN() macro to generate a
921 \c{main()} function, \c{QFINDTESTDATA} will not attempt to find test data
922 relative to QCoreApplication::applicationDirPath(). In practice, this means that
923 tests using \c{QTEST_APPLESS_MAIN()} will fail to find their test data
924 if run from a shadow build tree.
925*/
926
927/*! \macro QTEST_MAIN(TestClass)
928
929 \relates QTest
930
931 Implements a main() function that instantiates an application object and
932 the \a TestClass, and executes all tests in the order they were defined.
933 Use this macro to build stand-alone executables.
934
935 If \c QT_WIDGETS_LIB is defined, the application object will be a QApplication,
936 if \c QT_GUI_LIB is defined, the application object will be a QGuiApplication,
937 otherwise it will be a QCoreApplication. If qmake is used and the configuration
938 includes \c{QT += widgets}, then \c QT_WIDGETS_LIB will be defined automatically.
939 Similarly, if qmake is used and the configuration includes \c{QT += gui}, then
940 \c QT_GUI_LIB will be defined automatically.
941
942 \note On platforms that have keypad navigation enabled by default,
943 this macro will forcefully disable it if \c QT_WIDGETS_LIB is defined. This is done
944 to simplify the usage of key events when writing autotests. If you wish to write a
945 test case that uses keypad navigation, you should enable it either in the
946 \c {initTestCase()} or \c {init()} functions of your test case by calling
947 \l {QApplication::setNavigationMode()}.
948
949 Example:
950 \snippet code/src_qtestlib_qtestcase.cpp 11
951
952 \sa QTEST_APPLESS_MAIN(), QTEST_GUILESS_MAIN(), QTest::qExec(),
953 QApplication::setNavigationMode()
954*/
955
956/*! \macro QTEST_APPLESS_MAIN(TestClass)
957
958 \relates QTest
959
960 Implements a main() function that executes all tests in \a TestClass.
961
962 Behaves like \l QTEST_MAIN(), but doesn't instantiate a QApplication
963 object. Use this macro for really simple stand-alone non-GUI tests.
964
965 \sa QTEST_MAIN()
966*/
967
968/*! \macro QTEST_GUILESS_MAIN(TestClass)
969 \since 5.0
970
971 \relates QTest
972
973 Implements a main() function that instantiates a QCoreApplication object
974 and the \a TestClass, and executes all tests in the order they were
975 defined. Use this macro to build stand-alone executables.
976
977 Behaves like \l QTEST_MAIN(), but instantiates a QCoreApplication instead
978 of the QApplication object. Use this macro if your test case doesn't need
979 functionality offered by QApplication, but the event loop is still necessary.
980
981 \sa QTEST_MAIN()
982*/
983
984/*!
985 \macro QBENCHMARK
986
987 \relates QTest
988
989 This macro is used to measure the performance of code within a test.
990 The code to be benchmarked is contained within a code block following
991 this macro.
992
993 For example:
994
995 \snippet code/src_qtestlib_qtestcase.cpp 27
996
997 \sa {Qt Test Overview#Creating a Benchmark}{Creating a Benchmark},
998 {Chapter 5: Writing a Benchmark}{Writing a Benchmark}
999*/
1000
1001/*!
1002 \macro QBENCHMARK_ONCE
1003 \since 4.6
1004
1005 \relates QTest
1006
1007 \brief The QBENCHMARK_ONCE macro is for measuring performance of a
1008 code block by running it once.
1009
1010 This macro is used to measure the performance of code within a test.
1011 The code to be benchmarked is contained within a code block following
1012 this macro.
1013
1014 Unlike QBENCHMARK, the contents of the contained code block is only run
1015 once. The elapsed time will be reported as "0" if it's too short to
1016 be measured by the selected backend.
1017
1018 \sa {Qt Test Overview#Creating a Benchmark}{Creating a Benchmark},
1019 {Chapter 5: Writing a Benchmark}{Writing a Benchmark}
1020*/
1021
1022/*! \enum QTest::TestFailMode
1023
1024 This enum describes the modes for handling a check, such as by \l
1025 QVERIFY() or \l QCOMPARE() macros, that is known to fail. The mode
1026 applies regardless of whether the check fails or succeeds.
1027
1028 \value Abort Aborts the execution of the test. Use this mode when
1029 it doesn't make sense to execute the test any further after
1030 the problematic check.
1031
1032 \value Continue Continues execution of the test after the
1033 problematic check.
1034
1035 \sa QEXPECT_FAIL()
1036*/
1037
1038/*! \enum QTest::KeyAction
1039
1040 This enum describes possible actions for key handling.
1041
1042 \value Press The key is pressed.
1043 \value Release The key is released.
1044 \value Click The key is clicked (pressed and released).
1045 \value Shortcut A shortcut is activated. This value has been added in Qt 5.6.
1046*/
1047
1048/*! \enum QTest::MouseAction
1049
1050 This enum describes possible actions for mouse handling.
1051
1052 \value MousePress A mouse button is pressed.
1053 \value MouseRelease A mouse button is released.
1054 \value MouseClick A mouse button is clicked (pressed and released).
1055 \value MouseDClick A mouse button is double clicked (pressed and released twice).
1056 \value MouseMove The mouse pointer has moved.
1057*/
1058
1059/*! \fn void QTest::keyClick(QWidget *widget, Qt::Key key, Qt::KeyboardModifiers modifier = Qt::NoModifier, int delay=-1)
1060
1061 Simulates clicking of \a key with an optional \a modifier on a \a widget.
1062 If \a delay is larger than 0, the test will wait for \a delay milliseconds
1063 before clicking the key.
1064
1065 Examples:
1066 \snippet code/src_qtestlib_qtestcase_snippet.cpp 14
1067
1068 The first example above simulates clicking the \c escape key on \c
1069 myWidget without any keyboard modifiers and without delay. The
1070 second example simulates clicking \c shift-escape on \c myWidget
1071 following a 200 ms delay of the test.
1072
1073 \sa QTest::keyClicks()
1074*/
1075
1076/*! \fn void QTest::keyClick(QWidget *widget, char key, Qt::KeyboardModifiers modifier = Qt::NoModifier, int delay=-1)
1077 \overload
1078
1079 Simulates clicking of \a key with an optional \a modifier on a \a widget.
1080 If \a delay is larger than 0, the test will wait for \a delay milliseconds
1081 before clicking the key.
1082
1083 Example:
1084 \snippet code/src_qtestlib_qtestcase_snippet.cpp 13
1085
1086 The example above simulates clicking \c a on \c myWidget without
1087 any keyboard modifiers and without delay of the test.
1088
1089 \sa QTest::keyClicks()
1090*/
1091
1092/*! \fn void QTest::keySequence(QWidget *widget, const QKeySequence &keySequence)
1093 \overload
1094 \since 5.10
1095
1096 Simulates typing of \a keySequence into a \a widget.
1097
1098 \sa QTest::keyClick(), QTest::keyClicks()
1099*/
1100
1101/*! \fn void QTest::keyClick(QWindow *window, Qt::Key key, Qt::KeyboardModifiers modifier = Qt::NoModifier, int delay=-1)
1102 \overload
1103 \since 5.0
1104
1105 Simulates clicking of \a key with an optional \a modifier on a \a window.
1106 If \a delay is larger than 0, the test will wait for \a delay milliseconds
1107 before clicking the key.
1108
1109 Examples:
1110 \snippet code/src_qtestlib_qtestcase_snippet.cpp 29
1111
1112 The first example above simulates clicking the \c escape key on \c
1113 myWindow without any keyboard modifiers and without delay. The
1114 second example simulates clicking \c shift-escape on \c myWindow
1115 following a 200 ms delay of the test.
1116
1117 \sa QTest::keyClicks()
1118*/
1119
1120/*! \fn void QTest::keyClick(QWindow *window, char key, Qt::KeyboardModifiers modifier = Qt::NoModifier, int delay=-1)
1121 \overload
1122 \since 5.0
1123
1124 Simulates clicking of \a key with an optional \a modifier on a \a window.
1125 If \a delay is larger than 0, the test will wait for \a delay milliseconds
1126 before clicking the key.
1127
1128 Example:
1129 \snippet code/src_qtestlib_qtestcase_snippet.cpp 28
1130
1131 The example above simulates clicking \c a on \c myWindow without
1132 any keyboard modifiers and without delay of the test.
1133
1134 \sa QTest::keyClicks()
1135*/
1136
1137/*! \fn void QTest::keySequence(QWindow *window, const QKeySequence &keySequence)
1138 \overload
1139 \since 5.10
1140
1141 Simulates typing of \a keySequence into a \a window.
1142
1143 \sa QTest::keyClick(), QTest::keyClicks()
1144*/
1145
1146/*! \fn void QTest::keyEvent(KeyAction action, QWidget *widget, Qt::Key key, Qt::KeyboardModifiers modifier = Qt::NoModifier, int delay=-1)
1147
1148 Sends a Qt key event to \a widget with the given \a key and an associated \a action.
1149 Optionally, a keyboard \a modifier can be specified, as well as a \a delay
1150 (in milliseconds) of the test before sending the event.
1151*/
1152
1153/*! \fn void QTest::keyEvent(KeyAction action, QWidget *widget, char ascii, Qt::KeyboardModifiers modifier = Qt::NoModifier, int delay=-1)
1154 \overload
1155
1156 Sends a Qt key event to \a widget with the given key \a ascii and an associated \a action.
1157 Optionally, a keyboard \a modifier can be specified, as well as a \a delay
1158 (in milliseconds) of the test before sending the event.
1159*/
1160
1161/*! \fn void QTest::keyEvent(KeyAction action, QWindow *window, Qt::Key key, Qt::KeyboardModifiers modifier = Qt::NoModifier, int delay=-1)
1162 \overload
1163 \since 5.0
1164
1165 Sends a Qt key event to \a window with the given \a key and an associated \a action.
1166 Optionally, a keyboard \a modifier can be specified, as well as a \a delay
1167 (in milliseconds) of the test before sending the event.
1168*/
1169
1170/*! \fn void QTest::keyEvent(KeyAction action, QWindow *window, char ascii, Qt::KeyboardModifiers modifier = Qt::NoModifier, int delay=-1)
1171 \overload
1172 \since 5.0
1173
1174 Sends a Qt key event to \a window with the given key \a ascii and an associated \a action.
1175 Optionally, a keyboard \a modifier can be specified, as well as a \a delay
1176 (in milliseconds) of the test before sending the event.
1177*/
1178
1179/*! \fn void QTest::keyPress(QWidget *widget, Qt::Key key, Qt::KeyboardModifiers modifier = Qt::NoModifier, int delay=-1)
1180
1181 Simulates pressing a \a key with an optional \a modifier on a \a widget. If \a delay
1182 is larger than 0, the test will wait for \a delay milliseconds before pressing the key.
1183
1184 \note At some point you should release the key using \l keyRelease().
1185
1186 \sa QTest::keyRelease(), QTest::keyClick()
1187*/
1188
1189/*! \fn void QTest::keyPress(QWidget *widget, char key, Qt::KeyboardModifiers modifier = Qt::NoModifier, int delay=-1)
1190 \overload
1191
1192 Simulates pressing a \a key with an optional \a modifier on a \a widget.
1193 If \a delay is larger than 0, the test will wait for \a delay milliseconds
1194 before pressing the key.
1195
1196 \note At some point you should release the key using \l keyRelease().
1197
1198 \sa QTest::keyRelease(), QTest::keyClick()
1199*/
1200
1201/*! \fn void QTest::keyPress(QWindow *window, Qt::Key key, Qt::KeyboardModifiers modifier = Qt::NoModifier, int delay=-1)
1202 \overload
1203 \since 5.0
1204
1205 Simulates pressing a \a key with an optional \a modifier on a \a window. If \a delay
1206 is larger than 0, the test will wait for \a delay milliseconds before pressing the key.
1207
1208 \note At some point you should release the key using \l keyRelease().
1209
1210 \sa QTest::keyRelease(), QTest::keyClick()
1211*/
1212
1213/*! \fn void QTest::keyPress(QWindow *window, char key, Qt::KeyboardModifiers modifier = Qt::NoModifier, int delay=-1)
1214 \overload
1215 \since 5.0
1216
1217 Simulates pressing a \a key with an optional \a modifier on a \a window.
1218 If \a delay is larger than 0, the test will wait for \a delay milliseconds
1219 before pressing the key.
1220
1221 \note At some point you should release the key using \l keyRelease().
1222
1223 \sa QTest::keyRelease(), QTest::keyClick()
1224*/
1225
1226/*! \fn void QTest::keyRelease(QWidget *widget, Qt::Key key, Qt::KeyboardModifiers modifier = Qt::NoModifier, int delay=-1)
1227
1228 Simulates releasing a \a key with an optional \a modifier on a \a widget.
1229 If \a delay is larger than 0, the test will wait for \a delay milliseconds
1230 before releasing the key.
1231
1232 \sa QTest::keyPress(), QTest::keyClick()
1233*/
1234
1235/*! \fn void QTest::keyRelease(QWidget *widget, char key, Qt::KeyboardModifiers modifier = Qt::NoModifier, int delay=-1)
1236 \overload
1237
1238 Simulates releasing a \a key with an optional \a modifier on a \a widget.
1239 If \a delay is larger than 0, the test will wait for \a delay milliseconds
1240 before releasing the key.
1241
1242 \sa QTest::keyClick()
1243*/
1244
1245/*! \fn void QTest::keyRelease(QWindow *window, Qt::Key key, Qt::KeyboardModifiers modifier = Qt::NoModifier, int delay=-1)
1246 \overload
1247 \since 5.0
1248
1249 Simulates releasing a \a key with an optional \a modifier on a \a window.
1250 If \a delay is larger than 0, the test will wait for \a delay milliseconds
1251 before releasing the key.
1252
1253 \sa QTest::keyPress(), QTest::keyClick()
1254*/
1255
1256/*! \fn void QTest::keyRelease(QWindow *window, char key, Qt::KeyboardModifiers modifier = Qt::NoModifier, int delay=-1)
1257 \overload
1258 \since 5.0
1259
1260 Simulates releasing a \a key with an optional \a modifier on a \a window.
1261 If \a delay is larger than 0, the test will wait for \a delay milliseconds
1262 before releasing the key.
1263
1264 \sa QTest::keyClick()
1265*/
1266
1267/*! \fn void QTest::keyClicks(QWidget *widget, const QString &sequence, Qt::KeyboardModifiers modifier = Qt::NoModifier, int delay=-1)
1268
1269 Simulates clicking a \a sequence of keys on a \a
1270 widget. Optionally, a keyboard \a modifier can be specified as
1271 well as a \a delay (in milliseconds) of the test before each key
1272 click.
1273
1274 Example:
1275 \snippet code/src_qtestlib_qtestcase_snippet.cpp 15
1276
1277 The example above simulates clicking the sequence of keys
1278 representing "hello world" on \c myWidget without any keyboard
1279 modifiers and without delay of the test.
1280
1281 \sa QTest::keyClick()
1282*/
1283
1284/*! \fn void QTest::mousePress(QWidget *widget, Qt::MouseButton button, Qt::KeyboardModifiers modifier, QPoint pos = QPoint(), int delay=-1)
1285
1286 Simulates pressing a mouse \a button with an optional \a modifier
1287 on a \a widget. The position is defined by \a pos; the default
1288 position is the center of the widget. If \a delay is specified,
1289 the test will wait for the specified amount of milliseconds before
1290 the press.
1291
1292 \sa QTest::mouseRelease(), QTest::mouseClick()
1293*/
1294
1295/*! \fn void QTest::mousePress(QWindow *window, Qt::MouseButton button, Qt::KeyboardModifiers stateKey, QPoint pos = QPoint(), int delay=-1)
1296 \overload
1297 \since 5.0
1298
1299 Simulates pressing a mouse \a button with an optional \a stateKey modifier
1300 on a \a window. The position is defined by \a pos; the default
1301 position is the center of the window. If \a delay is specified,
1302 the test will wait for the specified amount of milliseconds before
1303 the press.
1304
1305 \sa QTest::mouseRelease(), QTest::mouseClick()
1306*/
1307
1308/*! \fn void QTest::mouseRelease(QWidget *widget, Qt::MouseButton button, Qt::KeyboardModifiers modifier, QPoint pos = QPoint(), int delay=-1)
1309
1310 Simulates releasing a mouse \a button with an optional \a modifier
1311 on a \a widget. The position of the release is defined by \a pos;
1312 the default position is the center of the widget. If \a delay is
1313 specified, the test will wait for the specified amount of
1314 milliseconds before releasing the button; otherwise, it will wait for a
1315 default amount of time (1 ms), which can be overridden via
1316 \l {Testing Options}{command-line arguments}.
1317
1318 \note If you wish to test a double-click by sending events individually,
1319 specify a short delay, greater than the default, on both mouse release events.
1320 The total of the delays for the press, release, press and release must be
1321 less than QStyleHints::mouseDoubleClickInterval(). But if you don't need
1322 to check state between events, it's better to use QTest::mouseDClick().
1323 \snippet code/src_qtestlib_qtestcase_snippet.cpp 35
1324
1325 \sa QTest::mousePress(), QTest::mouseClick()
1326*/
1327
1328/*! \fn void QTest::mouseRelease(QWindow *window, Qt::MouseButton button, Qt::KeyboardModifiers stateKey, QPoint pos = QPoint(), int delay=-1)
1329 \overload
1330 \since 5.0
1331
1332 Simulates releasing a mouse \a button with an optional \a stateKey modifier
1333 on a \a window. The position of the release is defined by \a pos;
1334 the default position is the center of the window. If \a delay is
1335 specified, the test will wait for the specified amount of
1336 milliseconds before releasing the button; otherwise, it will wait for a
1337 default amount of time (1 ms), which can be overridden via
1338 \l {Testing Options}{command-line arguments}.
1339
1340 \note If you wish to test a double-click by sending events individually,
1341 specify a short delay, greater than the default, on both mouse release events.
1342 The total of the delays for the press, release, press and release must be
1343 less than QStyleHints::mouseDoubleClickInterval(). But if you don't need
1344 to check state between events, it's better to use QTest::mouseDClick().
1345 \snippet code/src_qtestlib_qtestcase_snippet.cpp 35
1346
1347 \sa QTest::mousePress(), QTest::mouseClick()
1348*/
1349
1350/*! \fn void QTest::mouseClick(QWidget *widget, Qt::MouseButton button, Qt::KeyboardModifiers modifier, QPoint pos = QPoint(), int delay=-1)
1351
1352 Simulates clicking a mouse \a button with an optional \a modifier
1353 on a \a widget. The position of the click is defined by \a pos;
1354 the default position is the center of the widget. If \a delay is
1355 specified, the test will wait for the specified amount of
1356 milliseconds before pressing and before releasing the button.
1357
1358 \sa QTest::mousePress(), QTest::mouseRelease()
1359*/
1360
1361/*! \fn void QTest::mouseClick(QWindow *window, Qt::MouseButton button, Qt::KeyboardModifiers stateKey, QPoint pos = QPoint(), int delay=-1)
1362 \overload
1363 \since 5.0
1364
1365 Simulates clicking a mouse \a button with an optional \a stateKey modifier
1366 on a \a window. The position of the click is defined by \a pos;
1367 the default position is the center of the window. If \a delay is
1368 specified, the test will wait for the specified amount of
1369 milliseconds before pressing and before releasing the button.
1370
1371 \sa QTest::mousePress(), QTest::mouseRelease()
1372*/
1373
1374/*! \fn void QTest::mouseDClick(QWidget *widget, Qt::MouseButton button, Qt::KeyboardModifiers modifier, QPoint pos = QPoint(), int delay=-1)
1375
1376 Simulates double clicking a mouse \a button with an optional \a
1377 modifier on a \a widget. The position of the click is defined by
1378 \a pos; the default position is the center of the widget. If \a
1379 delay is specified, the test will wait for the specified amount of
1380 milliseconds before each press and release.
1381
1382 \sa QTest::mouseClick()
1383*/
1384
1385/*! \fn void QTest::mouseDClick(QWindow *window, Qt::MouseButton button, Qt::KeyboardModifiers stateKey, QPoint pos = QPoint(), int delay=-1)
1386 \overload
1387 \since 5.0
1388
1389 Simulates double clicking a mouse \a button with an optional \a stateKey
1390 modifier on a \a window. The position of the click is defined by
1391 \a pos; the default position is the center of the window. If \a
1392 delay is specified, the test will wait for the specified amount of
1393 milliseconds before each press and release.
1394
1395 \sa QTest::mouseClick()
1396*/
1397
1398/*! \fn void QTest::mouseMove(QWidget *widget, QPoint pos = QPoint(), int delay=-1)
1399
1400 Moves the mouse pointer to a \a widget. If \a pos is not
1401 specified, the mouse pointer moves to the center of the widget. If
1402 a \a delay (in milliseconds) is given, the test will wait before
1403 moving the mouse pointer.
1404*/
1405
1406/*! \fn void QTest::mouseMove(QWindow *window, QPoint pos = QPoint(), int delay=-1)
1407 \overload
1408 \since 5.0
1409
1410 Moves the mouse pointer to a \a window. If \a pos is not
1411 specified, the mouse pointer moves to the center of the window. If
1412 a \a delay (in milliseconds) is given, the test will wait before
1413 moving the mouse pointer.
1414*/
1415
1416/*! \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)
1417 \since 6.8
1418
1419 Simulates a wheel event within \a window at position \a pos in local
1420 window coordinates. \a angleDelta contains the wheel rotation angle.
1421 A positive value means forward rotation, and a negative one means backward.
1422 \a pixelDelta contains the scrolling distance in pixels on screen. This value can be null.
1423 The keyboard states at the time of the event are specified by \a stateKey.
1424 The scrolling phase of the event is specified by \a phase.
1425*/
1426
1427/*!
1428 \fn template <typename T1, typename T2> char *QTest::toString(const std::pair<T1, T2> &pair)
1429 \overload
1430 \since 5.11
1431 Returns a textual representation of the \a pair.
1432*/
1433
1434/*!
1435 \fn char *QTest::toString(const QVector2D &v)
1436 \overload
1437 \since 5.11
1438 Returns a textual representation of the 2D vector \a v.
1439*/
1440
1441/*!
1442 \fn char *QTest::toString(const QVector3D &v)
1443 \overload
1444 \since 5.11
1445 Returns a textual representation of the 3D vector \a v.
1446*/
1447
1448/*!
1449 \fn char *QTest::toString(const QVector4D &v)
1450 \overload
1451 \since 5.11
1452 Returns a textual representation of the 4D vector \a v.
1453*/
1454
1455/*!
1456 \fn template <typename T> char *QTest::toString(const T &value)
1457
1458 Returns a textual representation of \a value. This function is used by
1459 \l QCOMPARE() to output verbose information in case of a test failure.
1460
1461 You can add specializations or overloads of this function to your test to enable
1462 verbose output.
1463
1464 \note Starting with Qt 5.5, you should prefer to provide a toString() function
1465 in the type's namespace instead of specializing this template.
1466 If your code needs to continue to work with the QTestLib from Qt 5.4 or
1467 earlier, you need to continue to use specialization.
1468
1469 \note The caller of toString() must delete the returned data
1470 using \c{delete[]}. Your implementation should return a string
1471 created with \c{new[]} or qstrdup(). The easiest way to do so is to
1472 create a QByteArray or QString and call QTest::toString() on it
1473 (see second example below).
1474
1475 Example for specializing (Qt ≤ 5.4):
1476
1477 \snippet code/src_qtestlib_qtestcase_snippet.cpp 16
1478
1479 The example above defines a toString() specialization for a class
1480 called \c MyPoint. Whenever a comparison of two instances of \c
1481 MyPoint fails, \l QCOMPARE() will call this function to output the
1482 contents of \c MyPoint to the test log.
1483
1484 Same example, but with overloading (Qt ≥ 5.5):
1485
1486 \snippet code/src_qtestlib_qtestcase_snippet.cpp toString-overload
1487
1488 \sa QCOMPARE()
1489*/
1490
1491/*!
1492 \fn char *QTest::toString(const QLatin1StringView &string)
1493 \overload
1494
1495 Returns a textual representation of the given \a string.
1496*/
1497
1498/*!
1499 \fn char *QTest::toString(std::nullptr_t)
1500 \overload
1501 \since 5.8
1502
1503 Returns a string containing \nullptr.
1504*/
1505
1506/*!
1507 \fn char *QTest::toString(const QStringView &string)
1508 \overload
1509 \since 5.11
1510
1511 Returns a textual representation of the given \a string.
1512*/
1513
1514/*!
1515 \fn char *QTest::toString(const QUuid &uuid)
1516 \overload
1517 \since 5.11
1518
1519 Returns a textual representation of the given \a uuid.
1520*/
1521
1522/*!
1523 \fn char *QTest::toString(const QString &string)
1524 \overload
1525
1526 Returns a textual representation of the given \a string.
1527*/
1528
1529/*!
1530 \fn char *QTest::toString(const QByteArray &ba)
1531 \overload
1532
1533 Returns a textual representation of the byte array \a ba.
1534
1535 \sa QTest::toHexRepresentation()
1536*/
1537
1538/*!
1539 \fn char *QTest::toString(const QCborError &c)
1540 \overload
1541 \since 5.12
1542
1543 Returns a textual representation of the given CBOR error \a c.
1544*/
1545
1546/*!
1547 \fn template <class... Types> char *QTest::toString(const std::tuple<Types...> &tuple)
1548 \overload
1549 \since 5.12
1550
1551 Returns a textual representation of the given \a tuple.
1552*/
1553
1554/*!
1555 \fn char *QTest::toString(const QTime &time)
1556 \overload
1557
1558 Returns a textual representation of the given \a time.
1559*/
1560
1561/*!
1562 \fn char *QTest::toString(const QDate &date)
1563 \overload
1564
1565 Returns a textual representation of the given \a date.
1566*/
1567
1568/*!
1569 \fn char *QTest::toString(const QDateTime &dateTime)
1570 \overload
1571
1572 Returns a textual representation of the date and time specified by
1573 \a dateTime.
1574*/
1575
1576/*!
1577 \fn char *QTest::toString(const QChar &character)
1578 \overload
1579
1580 Returns a textual representation of the given \a character.
1581*/
1582
1583/*!
1584 \fn char *QTest::toString(const QPoint &point)
1585 \overload
1586
1587 Returns a textual representation of the given \a point.
1588*/
1589
1590/*!
1591 \fn char *QTest::toString(const QSize &size)
1592 \overload
1593
1594 Returns a textual representation of the given \a size.
1595*/
1596
1597/*!
1598 \fn char *QTest::toString(const QRect &rectangle)
1599 \overload
1600
1601 Returns a textual representation of the given \a rectangle.
1602*/
1603
1604/*!
1605 \fn char *QTest::toString(const QUrl &url)
1606 \since 4.4
1607 \overload
1608
1609 Returns a textual representation of the given \a url.
1610*/
1611
1612/*!
1613 \fn char *QTest::toString(const QPointF &point)
1614 \overload
1615
1616 Returns a textual representation of the given \a point.
1617*/
1618
1619/*!
1620 \fn char *QTest::toString(const QSizeF &size)
1621 \overload
1622
1623 Returns a textual representation of the given \a size.
1624*/
1625
1626/*!
1627 \fn char *QTest::toString(const QRectF &rectangle)
1628 \overload
1629
1630 Returns a textual representation of the given \a rectangle.
1631*/
1632
1633/*!
1634 \fn char *QTest::toString(const QVariant &variant)
1635 \overload
1636
1637 Returns a textual representation of the given \a variant.
1638*/
1639
1640/*!
1641 \fn char *toString(QSizePolicy::ControlType ct)
1642 \relates QTest
1643 \overload
1644 \since 5.5
1645
1646 Returns a textual representation of control type \a ct.
1647*/
1648
1649/*!
1650 \fn char *toString(QSizePolicy::ControlTypes cts)
1651 \relates QTest
1652 \overload
1653 \since 5.5
1654
1655 Returns a textual representation of control types \a cts.
1656*/
1657
1658/*!
1659 \fn char *toString(QSizePolicy::Policy p)
1660 \relates QTest
1661 \overload
1662 \since 5.5
1663
1664 Returns a textual representation of policy \a p.
1665*/
1666
1667/*!
1668 \fn char *toString(QSizePolicy sp)
1669 \relates QTest
1670 \overload
1671 \since 5.5
1672
1673 Returns a textual representation of size policy \a sp.
1674*/
1675
1676/*!
1677 \fn char *QTest::toString(const QKeySequence &ks)
1678 \overload
1679 \since 6.5
1680 Returns a textual representation of the key sequence \a ks.
1681*/
1682
1683/*!
1684 \fn QPointingDevice * QTest::createTouchDevice(QInputDevice::DeviceType devType = QInputDevice::DeviceType::TouchScreen, QInputDevice::Capabilities caps = QInputDevice::Capability::Position)
1685 \since 5.8
1686
1687 Creates a dummy touch device of type \a devType with capabilities \a caps for
1688 simulation of touch events.
1689
1690 The touch device will be registered with the Qt window system interface.
1691 You should typically use createTouchDevice() to initialize a QPointingDevice
1692 member variable in your test case class, use the same instance for all tests and
1693 delete it when no longer needed.
1694
1695 \sa QTest::QTouchEventSequence, touchEvent()
1696*/
1697
1698/*!
1699 \class QTest::QTouchEventSequence
1700 \inmodule QtTest
1701 \since 4.6
1702
1703 \brief The QTouchEventSequence class is used to simulate a sequence of touch events.
1704
1705 To simulate a sequence of touch events on a specific device for a window or widget, call
1706 QTest::touchEvent to create a QTouchEventSequence instance. Add touch events to
1707 the sequence by calling press(), move(), release() and stationary(), and let the
1708 instance run out of scope to commit the sequence to the event system.
1709
1710 Example:
1711 \snippet code/src_qtestlib_qtestcase_snippet.cpp 25
1712*/
1713
1714/*!
1715 \fn QTest::QTouchEventSequence::~QTouchEventSequence()
1716
1717 Commits this sequence of touch events, unless autoCommit was disabled, and frees allocated resources.
1718*/
1719
1720/*!
1721 \fn bool QTest::QTouchEventSequence::commit(bool processEvents)
1722
1723 Commits this touch event to the event system, and returns whether it was
1724 accepted after delivery.
1725
1726 Normally there is no need to call this function because it is called from
1727 the destructor. However, if autoCommit is disabled, the events only get
1728 committed upon explicitly calling this function. Another reason to call it
1729 explicitly is to check the return value.
1730
1731 In special cases, tests may want to disable the processing of the event.
1732 This can be achieved by setting \a processEvents to false. This results in
1733 merely queuing the event: the event loop will not be forced to process it.
1734
1735 Returns whether the event was accepted after delivery.
1736*/
1737
1738/*!
1739 \fn QTouchEventSequence &QTest::QTouchEventSequence::press(int touchId, const QPoint &pt, QWindow *window)
1740 \since 5.0
1741
1742 Adds a press event for touchpoint \a touchId at position \a pt to this sequence and returns
1743 a reference to this QTouchEventSequence.
1744
1745 The position \a pt is interpreted as relative to \a window. If \a window is the null pointer, then
1746 \a pt is interpreted as relative to the window provided when instantiating this QTouchEventSequence.
1747
1748 Simulates that the user pressed the touch screen or pad with the finger identified by \a touchId.
1749*/
1750
1751/*!
1752 \fn QTouchEventWidgetSequence &QTest::QTouchEventWidgetSequence::press(int touchId, const QPoint &pt, QWidget *widget)
1753
1754 Adds a press event for touchpoint \a touchId at position \a pt to this sequence and returns
1755 a reference to this QTouchEventWidgetSequence.
1756
1757 The position \a pt is interpreted as relative to \a widget. If \a widget is the null pointer, then
1758 \a pt is interpreted as relative to the widget provided when instantiating this QTouchEventWidgetSequence.
1759
1760 Simulates that the user pressed the touch screen or pad with the finger identified by \a touchId.
1761*/
1762
1763/*!
1764 \fn QTouchEventSequence &QTest::QTouchEventSequence::move(int touchId, const QPoint &pt, QWindow *window)
1765 \since 5.0
1766
1767 Adds a move event for touchpoint \a touchId at position \a pt to this sequence and returns
1768 a reference to this QTouchEventSequence.
1769
1770 The position \a pt is interpreted as relative to \a window. If \a window is the null pointer, then
1771 \a pt is interpreted as relative to the window provided when instantiating this QTouchEventSequence.
1772
1773 Simulates that the user moved the finger identified by \a touchId.
1774*/
1775
1776/*!
1777 \fn QTouchEventWidgetSequence &QTest::QTouchEventWidgetSequence::move(int touchId, const QPoint &pt, QWidget *widget)
1778
1779 Adds a move event for touchpoint \a touchId at position \a pt to this sequence and returns
1780 a reference to this QTouchEventWidgetSequence.
1781
1782 The position \a pt is interpreted as relative to \a widget. If \a widget is the null pointer, then
1783 \a pt is interpreted as relative to the widget provided when instantiating this QTouchEventWidgetSequence.
1784
1785 Simulates that the user moved the finger identified by \a touchId.
1786*/
1787
1788/*!
1789 \fn QTouchEventSequence &QTest::QTouchEventSequence::release(int touchId, const QPoint &pt, QWindow *window)
1790 \since 5.0
1791
1792 Adds a release event for touchpoint \a touchId at position \a pt to this sequence and returns
1793 a reference to this QTouchEventSequence.
1794
1795 The position \a pt is interpreted as relative to \a window. If \a window is the null pointer, then
1796 \a pt is interpreted as relative to the window provided when instantiating this QTouchEventSequence.
1797
1798 Simulates that the user lifted the finger identified by \a touchId.
1799*/
1800
1801/*!
1802 \fn QTouchEventWidgetSequence &QTest::QTouchEventWidgetSequence::release(int touchId, const QPoint &pt, QWidget *widget)
1803
1804 Adds a release event for touchpoint \a touchId at position \a pt to this sequence and returns
1805 a reference to this QTouchEventWidgetSequence.
1806
1807 The position \a pt is interpreted as relative to \a widget. If \a widget is the null pointer, then
1808 \a pt is interpreted as relative to the widget provided when instantiating this QTouchEventWidgetSequence.
1809
1810 Simulates that the user lifted the finger identified by \a touchId.
1811*/
1812
1813/*!
1814 \fn QTouchEventSequence &QTest::QTouchEventSequence::stationary(int touchId)
1815
1816 Adds a stationary event for touchpoint \a touchId to this sequence and returns
1817 a reference to this QTouchEventSequence.
1818
1819 Simulates that the user did not move the finger identified by \a touchId.
1820*/
1821
1822/*!
1823 \fn QTouchEventSequence QTest::touchEvent(QWindow *window, QPointingDevice *device, bool autoCommit)
1824 \since 5.0
1825
1826 Creates and returns a QTouchEventSequence for the \a device to
1827 simulate events for \a window.
1828
1829 When adding touch events to the sequence, \a window will also be used to translate
1830 the position provided to screen coordinates, unless another window is provided in the
1831 respective calls to press(), move() etc.
1832
1833 The touch events are committed to the event system when the destructor of the
1834 QTouchEventSequence is called (ie when the object returned runs out of scope), unless
1835 \a autoCommit is set to false. When \a autoCommit is false, commit() has to be called
1836 manually.
1837
1838 \l createTouchDevice() can be called to create a test touch device for use with this
1839 function.
1840*/
1841
1842/*!
1843 \fn QTouchEventSequence QTest::touchEvent(QWidget *widget, QPointingDevice *device, bool autoCommit)
1844
1845 Creates and returns a QTouchEventSequence for the \a device to
1846 simulate events for \a widget.
1847
1848 When adding touch events to the sequence, \a widget will also be used to translate
1849 the position provided to screen coordinates, unless another widget is provided in the
1850 respective calls to press(), move() etc.
1851
1852 The touch events are committed to the event system when the destructor of the
1853 QTouchEventSequence is called (ie when the object returned runs out of scope), unless
1854 \a autoCommit is set to false. When \a autoCommit is false, commit() has to be called
1855 manually.
1856
1857 \l createTouchDevice() can be called to create a test touch device for use with this
1858 function.
1859*/
1860
1861// Internals of qtestmouse.h:
1862
1863/*! \fn void QTest::mouseEvent(MouseAction action, QWidget *widget, Qt::MouseButton button, Qt::KeyboardModifiers stateKey, QPoint pos, int delay=-1)
1864 \internal
1865*/
1866
1867/*! \fn void QTest::mouseEvent(MouseAction action, QWindow *window, Qt::MouseButton button, Qt::KeyboardModifiers stateKey, QPoint pos, int delay=-1)
1868 \internal
1869*/