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