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 \note On platforms that have keypad navigation enabled by default,
944 this macro will forcefully disable it if \c QT_WIDGETS_LIB is defined. This is done
945 to simplify the usage of key events when writing autotests. If you wish to write a
946 test case that uses keypad navigation, you should enable it either in the
947 \c {initTestCase()} or \c {init()} functions of your test case by calling
948 \l {QApplication::setNavigationMode()}.
949
950 Example:
951 \snippet code/src_qtestlib_qtestcase.cpp 11
952
953 \sa QTEST_APPLESS_MAIN(), QTEST_GUILESS_MAIN(), QTest::qExec(),
954 QApplication::setNavigationMode()
955*/
956
957/*! \macro QTEST_APPLESS_MAIN(TestClass)
958
959 \relates QTest
960
961 Implements a main() function that executes all tests in \a TestClass.
962
963 Behaves like \l QTEST_MAIN(), but doesn't instantiate a QApplication
964 object. Use this macro for really simple stand-alone non-GUI tests.
965
966 \sa QTEST_MAIN()
967*/
968
969/*! \macro QTEST_GUILESS_MAIN(TestClass)
970 \since 5.0
971
972 \relates QTest
973
974 Implements a main() function that instantiates a QCoreApplication object
975 and the \a TestClass, and executes all tests in the order they were
976 defined. Use this macro to build stand-alone executables.
977
978 Behaves like \l QTEST_MAIN(), but instantiates a QCoreApplication instead
979 of the QApplication object. Use this macro if your test case doesn't need
980 functionality offered by QApplication, but the event loop is still necessary.
981
982 \sa QTEST_MAIN()
983*/
984
985/*!
986 \macro QBENCHMARK
987
988 \relates QTest
989
990 This macro is used to measure the performance of code within a test.
991 The code to be benchmarked is contained within a code block following
992 this macro.
993
994 For example:
995
996 \snippet code/src_qtestlib_qtestcase.cpp 27
997
998 \sa {Qt Test Overview#Creating a Benchmark}{Creating a Benchmark},
999 {Chapter 5: Writing a Benchmark}{Writing a Benchmark}
1000*/
1001
1002/*!
1003 \macro QBENCHMARK_ONCE
1004 \since 4.6
1005
1006 \relates QTest
1007
1008 \brief The QBENCHMARK_ONCE macro is for measuring performance of a
1009 code block by running it once.
1010
1011 This macro is used to measure the performance of code within a test.
1012 The code to be benchmarked is contained within a code block following
1013 this macro.
1014
1015 Unlike QBENCHMARK, the contents of the contained code block is only run
1016 once. The elapsed time will be reported as "0" if it's too short to
1017 be measured by the selected backend.
1018
1019 \sa {Qt Test Overview#Creating a Benchmark}{Creating a Benchmark},
1020 {Chapter 5: Writing a Benchmark}{Writing a Benchmark}
1021*/
1022
1023/*! \enum QTest::TestFailMode
1024
1025 This enum describes the modes for handling a check, such as by \l
1026 QVERIFY() or \l QCOMPARE() macros, that is known to fail. The mode
1027 applies regardless of whether the check fails or succeeds.
1028
1029 \value Abort Aborts the execution of the test. Use this mode when
1030 it doesn't make sense to execute the test any further after
1031 the problematic check.
1032
1033 \value Continue Continues execution of the test after the
1034 problematic check.
1035
1036 \sa QEXPECT_FAIL()
1037*/
1038
1039/*! \enum QTest::KeyAction
1040
1041 This enum describes possible actions for key handling.
1042
1043 \value Press The key is pressed.
1044 \value Release The key is released.
1045 \value Click The key is clicked (pressed and released).
1046 \value Shortcut A shortcut is activated. This value has been added in Qt 5.6.
1047*/
1048
1049/*! \enum QTest::MouseAction
1050
1051 This enum describes possible actions for mouse handling.
1052
1053 \value MousePress A mouse button is pressed.
1054 \value MouseRelease A mouse button is released.
1055 \value MouseClick A mouse button is clicked (pressed and released).
1056 \value MouseDClick A mouse button is double clicked (pressed and released twice).
1057 \value MouseMove The mouse pointer has moved.
1058*/
1059
1060/*! \fn void QTest::keyClick(QWidget *widget, Qt::Key key, Qt::KeyboardModifiers modifier = Qt::NoModifier, int delay=-1)
1061
1062 Simulates clicking of \a key with an optional \a modifier on a \a widget.
1063 If \a delay is larger than 0, the test will wait for \a delay milliseconds
1064 before clicking the key.
1065
1066 Examples:
1067 \snippet code/src_qtestlib_qtestcase_snippet.cpp 14
1068
1069 The first example above simulates clicking the \c escape key on \c
1070 myWidget without any keyboard modifiers and without delay. The
1071 second example simulates clicking \c shift-escape on \c myWidget
1072 following a 200 ms delay of the test.
1073
1074 \sa QTest::keyClicks()
1075*/
1076
1077/*! \fn void QTest::keyClick(QWidget *widget, char key, Qt::KeyboardModifiers modifier = Qt::NoModifier, int delay=-1)
1078 \overload
1079
1080 Simulates clicking of \a key with an optional \a modifier on a \a widget.
1081 If \a delay is larger than 0, the test will wait for \a delay milliseconds
1082 before clicking the key.
1083
1084 Example:
1085 \snippet code/src_qtestlib_qtestcase_snippet.cpp 13
1086
1087 The example above simulates clicking \c a on \c myWidget without
1088 any keyboard modifiers and without delay of the test.
1089
1090 \sa QTest::keyClicks()
1091*/
1092
1093/*! \fn void QTest::keySequence(QWidget *widget, const QKeySequence &keySequence)
1094 \overload
1095 \since 5.10
1096
1097 Simulates typing of \a keySequence into a \a widget.
1098
1099 \sa QTest::keyClick(), QTest::keyClicks()
1100*/
1101
1102/*! \fn void QTest::keyClick(QWindow *window, Qt::Key key, Qt::KeyboardModifiers modifier = Qt::NoModifier, int delay=-1)
1103 \overload
1104 \since 5.0
1105
1106 Simulates clicking of \a key with an optional \a modifier on a \a window.
1107 If \a delay is larger than 0, the test will wait for \a delay milliseconds
1108 before clicking the key.
1109
1110 Examples:
1111 \snippet code/src_qtestlib_qtestcase_snippet.cpp 29
1112
1113 The first example above simulates clicking the \c escape key on \c
1114 myWindow without any keyboard modifiers and without delay. The
1115 second example simulates clicking \c shift-escape on \c myWindow
1116 following a 200 ms delay of the test.
1117
1118 \sa QTest::keyClicks()
1119*/
1120
1121/*! \fn void QTest::keyClick(QWindow *window, char key, Qt::KeyboardModifiers modifier = Qt::NoModifier, int delay=-1)
1122 \overload
1123 \since 5.0
1124
1125 Simulates clicking of \a key with an optional \a modifier on a \a window.
1126 If \a delay is larger than 0, the test will wait for \a delay milliseconds
1127 before clicking the key.
1128
1129 Example:
1130 \snippet code/src_qtestlib_qtestcase_snippet.cpp 28
1131
1132 The example above simulates clicking \c a on \c myWindow without
1133 any keyboard modifiers and without delay of the test.
1134
1135 \sa QTest::keyClicks()
1136*/
1137
1138/*! \fn void QTest::keySequence(QWindow *window, const QKeySequence &keySequence)
1139 \overload
1140 \since 5.10
1141
1142 Simulates typing of \a keySequence into a \a window.
1143
1144 \sa QTest::keyClick(), QTest::keyClicks()
1145*/
1146
1147/*! \fn void QTest::keyEvent(KeyAction action, QWidget *widget, Qt::Key key, Qt::KeyboardModifiers modifier = Qt::NoModifier, int delay=-1)
1148
1149 Sends a Qt key event to \a widget with the given \a key 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, QWidget *widget, char ascii, Qt::KeyboardModifiers modifier = Qt::NoModifier, int delay=-1)
1155 \overload
1156
1157 Sends a Qt key event to \a widget with the given key \a ascii and an associated \a action.
1158 Optionally, a keyboard \a modifier can be specified, as well as a \a delay
1159 (in milliseconds) of the test before sending the event.
1160*/
1161
1162/*! \fn void QTest::keyEvent(KeyAction action, QWindow *window, Qt::Key key, Qt::KeyboardModifiers modifier = Qt::NoModifier, int delay=-1)
1163 \overload
1164 \since 5.0
1165
1166 Sends a Qt key event to \a window with the given \a key and an associated \a action.
1167 Optionally, a keyboard \a modifier can be specified, as well as a \a delay
1168 (in milliseconds) of the test before sending the event.
1169*/
1170
1171/*! \fn void QTest::keyEvent(KeyAction action, QWindow *window, char ascii, Qt::KeyboardModifiers modifier = Qt::NoModifier, int delay=-1)
1172 \overload
1173 \since 5.0
1174
1175 Sends a Qt key event to \a window with the given key \a ascii and an associated \a action.
1176 Optionally, a keyboard \a modifier can be specified, as well as a \a delay
1177 (in milliseconds) of the test before sending the event.
1178*/
1179
1180/*! \fn void QTest::keyPress(QWidget *widget, Qt::Key key, Qt::KeyboardModifiers modifier = Qt::NoModifier, int delay=-1)
1181
1182 Simulates pressing a \a key with an optional \a modifier on a \a widget. If \a delay
1183 is larger than 0, the test will wait for \a delay milliseconds before pressing the key.
1184
1185 \note At some point you should release the key using \l keyRelease().
1186
1187 \sa QTest::keyRelease(), QTest::keyClick()
1188*/
1189
1190/*! \fn void QTest::keyPress(QWidget *widget, char key, Qt::KeyboardModifiers modifier = Qt::NoModifier, int delay=-1)
1191 \overload
1192
1193 Simulates pressing a \a key with an optional \a modifier on a \a widget.
1194 If \a delay is larger than 0, the test will wait for \a delay milliseconds
1195 before pressing the key.
1196
1197 \note At some point you should release the key using \l keyRelease().
1198
1199 \sa QTest::keyRelease(), QTest::keyClick()
1200*/
1201
1202/*! \fn void QTest::keyPress(QWindow *window, Qt::Key key, Qt::KeyboardModifiers modifier = Qt::NoModifier, int delay=-1)
1203 \overload
1204 \since 5.0
1205
1206 Simulates pressing a \a key with an optional \a modifier on a \a window. If \a delay
1207 is larger than 0, the test will wait for \a delay milliseconds before pressing the key.
1208
1209 \note At some point you should release the key using \l keyRelease().
1210
1211 \sa QTest::keyRelease(), QTest::keyClick()
1212*/
1213
1214/*! \fn void QTest::keyPress(QWindow *window, char key, Qt::KeyboardModifiers modifier = Qt::NoModifier, int delay=-1)
1215 \overload
1216 \since 5.0
1217
1218 Simulates pressing a \a key with an optional \a modifier on a \a window.
1219 If \a delay is larger than 0, the test will wait for \a delay milliseconds
1220 before pressing the key.
1221
1222 \note At some point you should release the key using \l keyRelease().
1223
1224 \sa QTest::keyRelease(), QTest::keyClick()
1225*/
1226
1227/*! \fn void QTest::keyRelease(QWidget *widget, Qt::Key key, Qt::KeyboardModifiers modifier = Qt::NoModifier, int delay=-1)
1228
1229 Simulates releasing a \a key with an optional \a modifier on a \a widget.
1230 If \a delay is larger than 0, the test will wait for \a delay milliseconds
1231 before releasing the key.
1232
1233 \sa QTest::keyPress(), QTest::keyClick()
1234*/
1235
1236/*! \fn void QTest::keyRelease(QWidget *widget, char key, Qt::KeyboardModifiers modifier = Qt::NoModifier, int delay=-1)
1237 \overload
1238
1239 Simulates releasing a \a key with an optional \a modifier on a \a widget.
1240 If \a delay is larger than 0, the test will wait for \a delay milliseconds
1241 before releasing the key.
1242
1243 \sa QTest::keyClick()
1244*/
1245
1246/*! \fn void QTest::keyRelease(QWindow *window, Qt::Key key, Qt::KeyboardModifiers modifier = Qt::NoModifier, int delay=-1)
1247 \overload
1248 \since 5.0
1249
1250 Simulates releasing a \a key with an optional \a modifier on a \a window.
1251 If \a delay is larger than 0, the test will wait for \a delay milliseconds
1252 before releasing the key.
1253
1254 \sa QTest::keyPress(), QTest::keyClick()
1255*/
1256
1257/*! \fn void QTest::keyRelease(QWindow *window, char key, Qt::KeyboardModifiers modifier = Qt::NoModifier, int delay=-1)
1258 \overload
1259 \since 5.0
1260
1261 Simulates releasing a \a key with an optional \a modifier on a \a window.
1262 If \a delay is larger than 0, the test will wait for \a delay milliseconds
1263 before releasing the key.
1264
1265 \sa QTest::keyClick()
1266*/
1267
1268/*! \fn void QTest::keyClicks(QWidget *widget, const QString &sequence, Qt::KeyboardModifiers modifier = Qt::NoModifier, int delay=-1)
1269
1270 Simulates clicking a \a sequence of keys on a \a
1271 widget. Optionally, a keyboard \a modifier can be specified as
1272 well as a \a delay (in milliseconds) of the test before each key
1273 click.
1274
1275 Example:
1276 \snippet code/src_qtestlib_qtestcase_snippet.cpp 15
1277
1278 The example above simulates clicking the sequence of keys
1279 representing "hello world" on \c myWidget without any keyboard
1280 modifiers and without delay of the test.
1281
1282 \sa QTest::keyClick()
1283*/
1284
1285/*! \fn void QTest::mousePress(QWidget *widget, Qt::MouseButton button, Qt::KeyboardModifiers modifier, QPoint pos = QPoint(), int delay=-1)
1286
1287 Simulates pressing a mouse \a button with an optional \a modifier
1288 on a \a widget. The position is defined by \a pos; the default
1289 position is the center of the widget. If \a delay is specified,
1290 the test will wait for the specified amount of milliseconds before
1291 the press.
1292
1293 \sa QTest::mouseRelease(), QTest::mouseClick()
1294*/
1295
1296/*! \fn void QTest::mousePress(QWindow *window, Qt::MouseButton button, Qt::KeyboardModifiers stateKey, QPoint pos = QPoint(), int delay=-1)
1297 \overload
1298 \since 5.0
1299
1300 Simulates pressing a mouse \a button with an optional \a stateKey modifier
1301 on a \a window. The position is defined by \a pos; the default
1302 position is the center of the window. If \a delay is specified,
1303 the test will wait for the specified amount of milliseconds before
1304 the press.
1305
1306 \sa QTest::mouseRelease(), QTest::mouseClick()
1307*/
1308
1309/*! \fn void QTest::mouseRelease(QWidget *widget, Qt::MouseButton button, Qt::KeyboardModifiers modifier, QPoint pos = QPoint(), int delay=-1)
1310
1311 Simulates releasing a mouse \a button with an optional \a modifier
1312 on a \a widget. The position of the release is defined by \a pos;
1313 the default position is the center of the widget. If \a delay is
1314 specified, the test will wait for the specified amount of
1315 milliseconds before releasing the button; otherwise, it will wait for a
1316 default amount of time (1 ms), which can be overridden via
1317 \l {Testing Options}{command-line arguments}.
1318
1319 \note If you wish to test a double-click by sending events individually,
1320 specify a short delay, greater than the default, on both mouse release events.
1321 The total of the delays for the press, release, press and release must be
1322 less than QStyleHints::mouseDoubleClickInterval(). But if you don't need
1323 to check state between events, it's better to use QTest::mouseDClick().
1324 \snippet code/src_qtestlib_qtestcase_snippet.cpp 35
1325
1326 \sa QTest::mousePress(), QTest::mouseClick()
1327*/
1328
1329/*! \fn void QTest::mouseRelease(QWindow *window, Qt::MouseButton button, Qt::KeyboardModifiers stateKey, QPoint pos = QPoint(), int delay=-1)
1330 \overload
1331 \since 5.0
1332
1333 Simulates releasing a mouse \a button with an optional \a stateKey modifier
1334 on a \a window. The position of the release is defined by \a pos;
1335 the default position is the center of the window. If \a delay is
1336 specified, the test will wait for the specified amount of
1337 milliseconds before releasing the button; otherwise, it will wait for a
1338 default amount of time (1 ms), which can be overridden via
1339 \l {Testing Options}{command-line arguments}.
1340
1341 \note If you wish to test a double-click by sending events individually,
1342 specify a short delay, greater than the default, on both mouse release events.
1343 The total of the delays for the press, release, press and release must be
1344 less than QStyleHints::mouseDoubleClickInterval(). But if you don't need
1345 to check state between events, it's better to use QTest::mouseDClick().
1346 \snippet code/src_qtestlib_qtestcase_snippet.cpp 35
1347
1348 \sa QTest::mousePress(), QTest::mouseClick()
1349*/
1350
1351/*! \fn void QTest::mouseClick(QWidget *widget, Qt::MouseButton button, Qt::KeyboardModifiers modifier, QPoint pos = QPoint(), int delay=-1)
1352
1353 Simulates clicking a mouse \a button with an optional \a modifier
1354 on a \a widget. The position of the click is defined by \a pos;
1355 the default position is the center of the widget. If \a delay is
1356 specified, the test will wait for the specified amount of
1357 milliseconds before pressing and before releasing the button.
1358
1359 \sa QTest::mousePress(), QTest::mouseRelease()
1360*/
1361
1362/*! \fn void QTest::mouseClick(QWindow *window, Qt::MouseButton button, Qt::KeyboardModifiers stateKey, QPoint pos = QPoint(), int delay=-1)
1363 \overload
1364 \since 5.0
1365
1366 Simulates clicking a mouse \a button with an optional \a stateKey modifier
1367 on a \a window. The position of the click is defined by \a pos;
1368 the default position is the center of the window. If \a delay is
1369 specified, the test will wait for the specified amount of
1370 milliseconds before pressing and before releasing the button.
1371
1372 \sa QTest::mousePress(), QTest::mouseRelease()
1373*/
1374
1375/*! \fn void QTest::mouseDClick(QWidget *widget, Qt::MouseButton button, Qt::KeyboardModifiers modifier, QPoint pos = QPoint(), int delay=-1)
1376
1377 Simulates double clicking a mouse \a button with an optional \a
1378 modifier on a \a widget. The position of the click is defined by
1379 \a pos; the default position is the center of the widget. If \a
1380 delay is specified, the test will wait for the specified amount of
1381 milliseconds before each press and release.
1382
1383 \sa QTest::mouseClick()
1384*/
1385
1386/*! \fn void QTest::mouseDClick(QWindow *window, Qt::MouseButton button, Qt::KeyboardModifiers stateKey, QPoint pos = QPoint(), int delay=-1)
1387 \overload
1388 \since 5.0
1389
1390 Simulates double clicking a mouse \a button with an optional \a stateKey
1391 modifier on a \a window. The position of the click is defined by
1392 \a pos; the default position is the center of the window. If \a
1393 delay is specified, the test will wait for the specified amount of
1394 milliseconds before each press and release.
1395
1396 \sa QTest::mouseClick()
1397*/
1398
1399/*! \fn void QTest::mouseMove(QWidget *widget, QPoint pos = QPoint(), int delay=-1)
1400
1401 Moves the mouse pointer to a \a widget. If \a pos is not
1402 specified, the mouse pointer moves to the center of the widget. If
1403 a \a delay (in milliseconds) is given, the test will wait before
1404 moving the mouse pointer.
1405*/
1406
1407/*! \fn void QTest::mouseMove(QWindow *window, QPoint pos = QPoint(), int delay=-1)
1408 \overload
1409 \since 5.0
1410
1411 Moves the mouse pointer to a \a window. If \a pos is not
1412 specified, the mouse pointer moves to the center of the window. If
1413 a \a delay (in milliseconds) is given, the test will wait before
1414 moving the mouse pointer.
1415*/
1416
1417/*! \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)
1418 \since 6.8
1419
1420 Simulates a wheel event within \a window at position \a pos in local
1421 window coordinates. \a angleDelta contains the wheel rotation angle.
1422 A positive value means forward rotation, and a negative one means backward.
1423 \a pixelDelta contains the scrolling distance in pixels on screen. This value can be null.
1424 The keyboard states at the time of the event are specified by \a stateKey.
1425 The scrolling phase of the event is specified by \a phase.
1426*/
1427
1428/*!
1429 \fn template <typename T1, typename T2> char *QTest::toString(const std::pair<T1, T2> &pair)
1430 \overload
1431 \since 5.11
1432 Returns a textual representation of the \a pair.
1433*/
1434
1435/*!
1436 \fn char *QTest::toString(const QVector2D &v)
1437 \overload
1438 \since 5.11
1439 Returns a textual representation of the 2D vector \a v.
1440*/
1441
1442/*!
1443 \fn char *QTest::toString(const QVector3D &v)
1444 \overload
1445 \since 5.11
1446 Returns a textual representation of the 3D vector \a v.
1447*/
1448
1449/*!
1450 \fn char *QTest::toString(const QVector4D &v)
1451 \overload
1452 \since 5.11
1453 Returns a textual representation of the 4D vector \a v.
1454*/
1455
1456/*!
1457 \fn template <typename T> char *QTest::toString(const T &value)
1458
1459 Returns a textual representation of \a value. This function is used by
1460 \l QCOMPARE() to output verbose information in case of a test failure.
1461
1462 You can add specializations or overloads of this function to your test to enable
1463 verbose output.
1464
1465 \note Starting with Qt 5.5, you should prefer to provide a toString() function
1466 in the type's namespace instead of specializing this template.
1467 If your code needs to continue to work with the QTestLib from Qt 5.4 or
1468 earlier, you need to continue to use specialization.
1469
1470 \note The caller of toString() must delete the returned data
1471 using \c{delete[]}. Your implementation should return a string
1472 created with \c{new[]} or qstrdup(). The easiest way to do so is to
1473 create a QByteArray or QString and call QTest::toString() on it
1474 (see second example below).
1475
1476 Example for specializing (Qt ≤ 5.4):
1477
1478 \snippet code/src_qtestlib_qtestcase_snippet.cpp 16
1479
1480 The example above defines a toString() specialization for a class
1481 called \c MyPoint. Whenever a comparison of two instances of \c
1482 MyPoint fails, \l QCOMPARE() will call this function to output the
1483 contents of \c MyPoint to the test log.
1484
1485 Same example, but with overloading (Qt ≥ 5.5):
1486
1487 \snippet code/src_qtestlib_qtestcase_snippet.cpp toString-overload
1488
1489 \sa QCOMPARE()
1490*/
1491
1492/*!
1493 \fn char *QTest::toString(const QLatin1StringView &string)
1494 \overload
1495
1496 Returns a textual representation of the given \a string.
1497*/
1498
1499/*!
1500 \fn char *QTest::toString(std::nullptr_t)
1501 \overload
1502 \since 5.8
1503
1504 Returns a string containing \nullptr.
1505*/
1506
1507/*!
1508 \fn char *QTest::toString(const QStringView &string)
1509 \overload
1510 \since 5.11
1511
1512 Returns a textual representation of the given \a string.
1513*/
1514
1515/*!
1516 \fn char *QTest::toString(const QUuid &uuid)
1517 \overload
1518 \since 5.11
1519
1520 Returns a textual representation of the given \a uuid.
1521*/
1522
1523/*!
1524 \fn char *QTest::toString(const QString &string)
1525 \overload
1526
1527 Returns a textual representation of the given \a string.
1528*/
1529
1530/*!
1531 \fn char *QTest::toString(const QByteArray &ba)
1532 \overload
1533
1534 Returns a textual representation of the byte array \a ba.
1535
1536 \sa QTest::toHexRepresentation()
1537*/
1538
1539/*!
1540 \fn char *QTest::toString(const QCborError &c)
1541 \overload
1542 \since 5.12
1543
1544 Returns a textual representation of the given CBOR error \a c.
1545*/
1546
1547/*!
1548 \fn template <class... Types> char *QTest::toString(const std::tuple<Types...> &tuple)
1549 \overload
1550 \since 5.12
1551
1552 Returns a textual representation of the given \a tuple.
1553*/
1554
1555/*!
1556 \fn char *QTest::toString(const QTime &time)
1557 \overload
1558
1559 Returns a textual representation of the given \a time.
1560*/
1561
1562/*!
1563 \fn char *QTest::toString(const QDate &date)
1564 \overload
1565
1566 Returns a textual representation of the given \a date.
1567*/
1568
1569/*!
1570 \fn char *QTest::toString(const QDateTime &dateTime)
1571 \overload
1572
1573 Returns a textual representation of the date and time specified by
1574 \a dateTime.
1575*/
1576
1577/*!
1578 \fn char *QTest::toString(const QChar &character)
1579 \overload
1580
1581 Returns a textual representation of the given \a character.
1582*/
1583
1584/*!
1585 \fn char *QTest::toString(const QPoint &point)
1586 \overload
1587
1588 Returns a textual representation of the given \a point.
1589*/
1590
1591/*!
1592 \fn char *QTest::toString(const QSize &size)
1593 \overload
1594
1595 Returns a textual representation of the given \a size.
1596*/
1597
1598/*!
1599 \fn char *QTest::toString(const QRect &rectangle)
1600 \overload
1601
1602 Returns a textual representation of the given \a rectangle.
1603*/
1604
1605/*!
1606 \fn char *QTest::toString(const QUrl &url)
1607 \since 4.4
1608 \overload
1609
1610 Returns a textual representation of the given \a url.
1611*/
1612
1613/*!
1614 \fn char *QTest::toString(const QPointF &point)
1615 \overload
1616
1617 Returns a textual representation of the given \a point.
1618*/
1619
1620/*!
1621 \fn char *QTest::toString(const QSizeF &size)
1622 \overload
1623
1624 Returns a textual representation of the given \a size.
1625*/
1626
1627/*!
1628 \fn char *QTest::toString(const QRectF &rectangle)
1629 \overload
1630
1631 Returns a textual representation of the given \a rectangle.
1632*/
1633
1634/*!
1635 \fn char *QTest::toString(const QVariant &variant)
1636 \overload
1637
1638 Returns a textual representation of the given \a variant.
1639*/
1640
1641/*!
1642 \fn char *toString(QSizePolicy::ControlType ct)
1643 \relates QTest
1644 \overload
1645 \since 5.5
1646
1647 Returns a textual representation of control type \a ct.
1648*/
1649
1650/*!
1651 \fn char *toString(QSizePolicy::ControlTypes cts)
1652 \relates QTest
1653 \overload
1654 \since 5.5
1655
1656 Returns a textual representation of control types \a cts.
1657*/
1658
1659/*!
1660 \fn char *toString(QSizePolicy::Policy p)
1661 \relates QTest
1662 \overload
1663 \since 5.5
1664
1665 Returns a textual representation of policy \a p.
1666*/
1667
1668/*!
1669 \fn char *toString(QSizePolicy sp)
1670 \relates QTest
1671 \overload
1672 \since 5.5
1673
1674 Returns a textual representation of size policy \a sp.
1675*/
1676
1677/*!
1678 \fn char *QTest::toString(const QKeySequence &ks)
1679 \overload
1680 \since 6.5
1681 Returns a textual representation of the key sequence \a ks.
1682*/
1683
1684/*!
1685 \fn QPointingDevice * QTest::createTouchDevice(QInputDevice::DeviceType devType = QInputDevice::DeviceType::TouchScreen, QInputDevice::Capabilities caps = QInputDevice::Capability::Position)
1686 \since 5.8
1687
1688 Creates a dummy touch device of type \a devType with capabilities \a caps for
1689 simulation of touch events.
1690
1691 The touch device will be registered with the Qt window system interface.
1692 You should typically use createTouchDevice() to initialize a QPointingDevice
1693 member variable in your test case class, use the same instance for all tests and
1694 delete it when no longer needed.
1695
1696 \sa QTest::QTouchEventSequence, touchEvent()
1697*/
1698
1699/*!
1700 \class QTest::QTouchEventSequence
1701 \inmodule QtTest
1702 \since 4.6
1703
1704 \brief The QTouchEventSequence class is used to simulate a sequence of touch events.
1705
1706 To simulate a sequence of touch events on a specific device for a window or widget, call
1707 QTest::touchEvent to create a QTouchEventSequence instance. Add touch events to
1708 the sequence by calling press(), move(), release() and stationary(), and let the
1709 instance run out of scope to commit the sequence to the event system.
1710
1711 Example:
1712 \snippet code/src_qtestlib_qtestcase_snippet.cpp 25
1713*/
1714
1715/*!
1716 \class QTest::QTouchEventWidgetSequence
1717 \inmodule QtTest
1718 \brief The QTouchEventWidgetSequence class is used to simulate a sequence
1719 of touch events for a widget.
1720
1721 To simulate a sequence of touch events on a widget, call
1722 \l {QTest::touchEvent(QWidget*, QPointingDevice*, bool)}{QTest::touchEvent()}
1723 with a pointer to a QWidget instance. Add touch events to the returned
1724 QTouchEventWidgetSequence object by calling \l press(),
1725 \l move(), \l release() and \l stationary(), and let the instance run out of
1726 scope to commit the sequence to the event system.
1727*/
1728
1729/*!
1730 \fn QTest::QTouchEventSequence::~QTouchEventSequence()
1731
1732 Commits this sequence of touch events, unless autoCommit was disabled, and frees allocated resources.
1733*/
1734
1735/*!
1736 \fn bool QTest::QTouchEventSequence::commit(bool processEvents)
1737
1738 Commits this touch event to the event system, and returns whether it was
1739 accepted after delivery.
1740
1741 Normally there is no need to call this function because it is called from
1742 the destructor. However, if autoCommit is disabled, the events only get
1743 committed upon explicitly calling this function. Another reason to call it
1744 explicitly is to check the return value.
1745
1746 In special cases, tests may want to disable the processing of the event.
1747 This can be achieved by setting \a processEvents to false. This results in
1748 merely queuing the event: the event loop will not be forced to process it.
1749
1750 Returns whether the event was accepted after delivery.
1751*/
1752
1753/*!
1754 \fn QTouchEventSequence &QTest::QTouchEventSequence::press(int touchId, const QPoint &pt, QWindow *window)
1755 \since 5.0
1756
1757 Adds a press event for touchpoint \a touchId at position \a pt to this sequence and returns
1758 a reference to this QTouchEventSequence.
1759
1760 The position \a pt is interpreted as relative to \a window. If \a window is the null pointer, then
1761 \a pt is interpreted as relative to the window provided when instantiating this QTouchEventSequence.
1762
1763 Simulates that the user pressed the touch screen or pad with the finger identified by \a touchId.
1764*/
1765
1766/*!
1767 \fn QTouchEventWidgetSequence &QTest::QTouchEventWidgetSequence::press(int touchId, const QPoint &pt, QWidget *widget)
1768
1769 Adds a press event for touchpoint \a touchId at position \a pt to this sequence and returns
1770 a reference to this QTouchEventWidgetSequence.
1771
1772 The position \a pt is interpreted as relative to \a widget. If \a widget is the null pointer, then
1773 \a pt is interpreted as relative to the widget provided when instantiating this QTouchEventWidgetSequence.
1774
1775 Simulates that the user pressed the touch screen or pad with the finger identified by \a touchId.
1776*/
1777
1778/*!
1779 \fn QTouchEventSequence &QTest::QTouchEventSequence::move(int touchId, const QPoint &pt, QWindow *window)
1780 \since 5.0
1781
1782 Adds a move event for touchpoint \a touchId at position \a pt to this sequence and returns
1783 a reference to this QTouchEventSequence.
1784
1785 The position \a pt is interpreted as relative to \a window. If \a window is the null pointer, then
1786 \a pt is interpreted as relative to the window provided when instantiating this QTouchEventSequence.
1787
1788 Simulates that the user moved the finger identified by \a touchId.
1789*/
1790
1791/*!
1792 \fn QTouchEventWidgetSequence &QTest::QTouchEventWidgetSequence::move(int touchId, const QPoint &pt, QWidget *widget)
1793
1794 Adds a move event for touchpoint \a touchId at position \a pt to this sequence and returns
1795 a reference to this QTouchEventWidgetSequence.
1796
1797 The position \a pt is interpreted as relative to \a widget. If \a widget is the null pointer, then
1798 \a pt is interpreted as relative to the widget provided when instantiating this QTouchEventWidgetSequence.
1799
1800 Simulates that the user moved the finger identified by \a touchId.
1801*/
1802
1803/*!
1804 \fn QTouchEventSequence &QTest::QTouchEventSequence::release(int touchId, const QPoint &pt, QWindow *window)
1805 \since 5.0
1806
1807 Adds a release event for touchpoint \a touchId at position \a pt to this sequence and returns
1808 a reference to this QTouchEventSequence.
1809
1810 The position \a pt is interpreted as relative to \a window. If \a window is the null pointer, then
1811 \a pt is interpreted as relative to the window provided when instantiating this QTouchEventSequence.
1812
1813 Simulates that the user lifted the finger identified by \a touchId.
1814*/
1815
1816/*!
1817 \fn QTouchEventWidgetSequence &QTest::QTouchEventWidgetSequence::release(int touchId, const QPoint &pt, QWidget *widget)
1818
1819 Adds a release event for touchpoint \a touchId at position \a pt to this sequence and returns
1820 a reference to this QTouchEventWidgetSequence.
1821
1822 The position \a pt is interpreted as relative to \a widget. If \a widget is the null pointer, then
1823 \a pt is interpreted as relative to the widget provided when instantiating this QTouchEventWidgetSequence.
1824
1825 Simulates that the user lifted the finger identified by \a touchId.
1826*/
1827
1828/*!
1829 \fn QTouchEventSequence &QTest::QTouchEventSequence::stationary(int touchId)
1830
1831 Adds a stationary event for touchpoint \a touchId to this sequence and returns
1832 a reference to this QTouchEventSequence.
1833
1834 Simulates that the user did not move the finger identified by \a touchId.
1835*/
1836
1837/*!
1838 \fn QTouchEventSequence QTest::touchEvent(QWindow *window, QPointingDevice *device, bool autoCommit)
1839 \since 5.0
1840
1841 Creates and returns a QTouchEventSequence for the \a device to
1842 simulate events for \a window.
1843
1844 When adding touch events to the sequence, \a window will also be used to translate
1845 the position provided to screen coordinates, unless another window is provided in the
1846 respective calls to press(), move() etc.
1847
1848 The touch events are committed to the event system when the destructor of the
1849 QTouchEventSequence is called (ie when the object returned runs out of scope), unless
1850 \a autoCommit is set to false. When \a autoCommit is false, commit() has to be called
1851 manually.
1852
1853 \l createTouchDevice() can be called to create a test touch device for use with this
1854 function.
1855*/
1856
1857/*!
1858 \fn QTouchEventSequence QTest::touchEvent(QWidget *widget, QPointingDevice *device, bool autoCommit)
1859
1860 Creates and returns a QTouchEventSequence for the \a device to
1861 simulate events for \a widget.
1862
1863 When adding touch events to the sequence, \a widget will also be used to translate
1864 the position provided to screen coordinates, unless another widget is provided in the
1865 respective calls to press(), move() etc.
1866
1867 The touch events are committed to the event system when the destructor of the
1868 QTouchEventSequence is called (ie when the object returned runs out of scope), unless
1869 \a autoCommit is set to false. When \a autoCommit is false, commit() has to be called
1870 manually.
1871
1872 \l createTouchDevice() can be called to create a test touch device for use with this
1873 function.
1874*/
1875
1876// Internals of qtestmouse.h:
1877
1878/*! \fn void QTest::mouseEvent(MouseAction action, QWidget *widget, Qt::MouseButton button, Qt::KeyboardModifiers stateKey, QPoint pos, int delay=-1)
1879 \internal
1880*/
1881
1882/*! \fn void QTest::mouseEvent(MouseAction action, QWindow *window, Qt::MouseButton button, Qt::KeyboardModifiers stateKey, QPoint pos, int delay=-1)
1883 \internal
1884*/