diff options
Diffstat (limited to 'src/testlib/qtestcase.qdoc')
| -rw-r--r-- | src/testlib/qtestcase.qdoc | 572 |
1 files changed, 482 insertions, 90 deletions
diff --git a/src/testlib/qtestcase.qdoc b/src/testlib/qtestcase.qdoc index 2a480fb349..973899e4d3 100644 --- a/src/testlib/qtestcase.qdoc +++ b/src/testlib/qtestcase.qdoc @@ -1,29 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2020 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2020 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! \namespace QTest @@ -46,8 +22,10 @@ You can use \l QVERIFY2() when it is practical and valuable to put additional information into the test failure report. +//! [macro-usage-limitation] \note This macro can only be used in a test function that is invoked by the test framework. +//! [macro-usage-limitation] For example, the following code shows this macro being used to verify that a \l QSignalSpy object is valid: @@ -58,7 +36,8 @@ \c QVERIFY(x == y), because it reports both the expected and actual value when the comparison fails. - \sa QCOMPARE(), QTRY_VERIFY(), QSignalSpy, QEXPECT_FAIL() + \sa QCOMPARE(), QTRY_VERIFY(), QSignalSpy, QEXPECT_FAIL(), QCOMPARE_EQ(), + QCOMPARE_NE(), QCOMPARE_LT(), QCOMPARE_LE(), QCOMPARE_GT(), QCOMPARE_GE() */ /*! \macro QVERIFY2(condition, message) @@ -97,7 +76,8 @@ \c {FAIL! : tst_QFile::open_write() 'opened' returned FALSE. (open /tmp/qt.a3B42Cd: No space left on device)} - \sa QVERIFY(), QCOMPARE(), QEXPECT_FAIL() + \sa QVERIFY(), QCOMPARE(), QEXPECT_FAIL(), QCOMPARE_EQ(), QCOMPARE_NE(), + QCOMPARE_LT(), QCOMPARE_LE(), QCOMPARE_GT(), QCOMPARE_GE() */ /*! \macro QCOMPARE(actual, expected) @@ -123,25 +103,27 @@ \snippet code/src_qtestlib_qtestcase.cpp 2 When comparing floating-point types (\c float, \c double, and \c qfloat16), - \l {qFuzzyCompare()} is used for finite values. If \l {qFuzzyIsNull()} is true for - both values, they are also considered equal. Infinities match if they have - the same sign, and any NaN as actual value matches with any NaN as expected - value (even though NaN != NaN, even when they're identical). + \l {qFuzzyCompare()} is used for finite values. If \l {<QtNumeric>::}{qFuzzyIsNull()} + is true for both values, they are also considered equal. Infinities + match if they have the same sign, and any NaN as actual value matches + with any NaN as expected value (even though NaN != NaN, even when + they're identical). When comparing QList, arrays and initializer lists of the value type can be passed as expected value: \snippet code/src_qtestlib_qtestcase.cpp 34 - Note that using initializer lists requires a defining a helper macro + Note that using initializer lists requires defining a helper macro to prevent the preprocessor from interpreting the commas as macro argument delimiters: \snippet code/src_qtestlib_qtestcase.cpp 35 - \note QCOMPARE() can only be used in a test function that is invoked - by the test framework. + \include qtestcase.qdoc macro-usage-limitation - For your own classes, you can use \l QTest::toString() to format values for - outputting into the test log. +//! [to-string-overload-desc] + For your own classes, you can overload \l QTest::toString() to format values + for output into the test log. +//! [to-string-overload-desc] Example: \snippet code/src_qtestlib_qtestcase_snippet.cpp 34 @@ -150,23 +132,217 @@ be released with \c delete[] (rather than \c free() or plain \c delete) once the calling code is done with it. - \sa QVERIFY(), QTRY_COMPARE(), QTest::toString(), QEXPECT_FAIL() + \sa QVERIFY(), QTRY_COMPARE(), QTest::toString(), QEXPECT_FAIL(), + QCOMPARE_EQ(), QCOMPARE_NE(), QCOMPARE_LT(), QCOMPARE_LE(), + QCOMPARE_GT(), QCOMPARE_GE() +*/ + +/*! \macro QCOMPARE_EQ(computed, baseline) + \since 6.4 + + \relates QTest + + The QCOMPARE_EQ() macro checks that \a computed is equal to \a baseline using + the equality operator. If that is true, execution continues. If not, a + failure is recorded in the test log and the test function returns without + attempting any later checks. + + It is generally similar to calling \c {QVERIFY(computed == baseline);} + but prints a formatted error message reporting \a computed and \a baseline argument + expressions and values in case of failure. + + \include qtestcase.qdoc macro-usage-limitation + + \include qtestcase.qdoc to-string-overload-desc + + \note Unlike QCOMPARE(), this macro does not provide overloads for custom + types and pointers. So passing e.g. two \c {const char *} values as + parameters will compare \e pointers, while QCOMPARE() does a comparison of + C-style strings. + + \sa QCOMPARE(), QCOMPARE_NE(), QCOMPARE_LT(), QCOMPARE_LE(), QCOMPARE_GT(), + QCOMPARE_GE() +*/ + +/*! \macro QCOMPARE_NE(computed, baseline) + \since 6.4 + + \relates QTest + + The QCOMPARE_NE() macro checks that \a computed is not equal to \a baseline using + the inequality operator. If that is true, execution continues. If not, a + failure is recorded in the test log and the test function returns without + attempting any later checks. + + It is generally similar to calling \c {QVERIFY(computed != baseline);} + but prints a formatted error message reporting \a computed and \a baseline argument + expressions and values in case of failure. + + \include qtestcase.qdoc macro-usage-limitation + + \include qtestcase.qdoc to-string-overload-desc + + \sa QCOMPARE_EQ(), QCOMPARE_LT(), QCOMPARE_LE(), QCOMPARE_GT(), QCOMPARE_GE() +*/ + +/*! \macro QCOMPARE_LT(computed, baseline) + \since 6.4 + + \relates QTest + + The QCOMPARE_LT() macro checks that \a computed is less than \a baseline using the + less-than operator. If that is true, execution continues. If not, a failure + is recorded in the test log and the test function returns without attempting + any later checks. + + It is generally similar to calling \c {QVERIFY(computed < baseline);} + but prints a formatted error message reporting \a computed and \a baseline argument + expressions and values in case of failure. + + \include qtestcase.qdoc macro-usage-limitation + + \include qtestcase.qdoc to-string-overload-desc + + \sa QCOMPARE_EQ(), QCOMPARE_NE(), QCOMPARE_LE(), QCOMPARE_GT(), QCOMPARE_GE() +*/ + +/*! \macro QCOMPARE_LE(computed, baseline) + \since 6.4 + + \relates QTest + + The QCOMPARE_LE() macro checks that \a computed is at most \a baseline using the + less-than-or-equal-to operator. If that is true, execution continues. If + not, a failure is recorded in the test log and the test function returns + without attempting any later checks. + + It is generally similar to calling \c {QVERIFY(computed <= baseline);} + but prints a formatted error message reporting \a computed and \a baseline argument + expressions and values in case of failure. + + \include qtestcase.qdoc macro-usage-limitation + + \include qtestcase.qdoc to-string-overload-desc + + \sa QCOMPARE_EQ(), QCOMPARE_NE(), QCOMPARE_LT(), QCOMPARE_GT(), QCOMPARE_GE() +*/ + +/*! \macro QCOMPARE_GT(computed, baseline) + \since 6.4 + + \relates QTest + + The QCOMPARE_GT() macro checks that \a computed is greater than \a baseline using + the greater-than operator. If that is true, execution continues. If not, a + failure is recorded in the test log and the test function returns without + attempting any later checks. + + It is generally similar to calling \c {QVERIFY(computed > baseline);} + but prints a formatted error message reporting \a computed and \a baseline argument + expressions and values in case of failure. + + \include qtestcase.qdoc macro-usage-limitation + + \include qtestcase.qdoc to-string-overload-desc + + \sa QCOMPARE_EQ(), QCOMPARE_NE(), QCOMPARE_LT(), QCOMPARE_LE(), QCOMPARE_GE() +*/ + +/*! \macro QCOMPARE_GE(computed, baseline) + \since 6.4 + + \relates QTest + + The QCOMPARE_GE() macro checks that \a computed is at least \a baseline using the + greater-than-or-equal-to operator. If that is true, execution continues. If + not, a failure is recorded in the test log and the test function returns + without attempting any later checks. + + It is generally similar to calling \c {QVERIFY(computed >= baseline);} + but prints a formatted error message reporting \a computed and \a baseline argument + expressions and values in case of failure. + + \include qtestcase.qdoc macro-usage-limitation + + \include qtestcase.qdoc to-string-overload-desc + + \sa QCOMPARE_EQ(), QCOMPARE_NE(), QCOMPARE_LT(), QCOMPARE_LE(), QCOMPARE_GT() */ /*! \macro QVERIFY_EXCEPTION_THROWN(expression, exceptiontype) \since 5.3 \relates QTest + \deprecated [6.3] Use \c{QVERIFY_THROWS_EXCEPTION(exceptiontype, expression)} instead. +*/ - The QVERIFY_EXCEPTION_THROWN macro executes an \a expression and tries - to catch an exception thrown from the \a expression. If the \a expression - throws an exception and its type is the same as \a exceptiontype - or \a exceptiontype is substitutable with the type of thrown exception - (i.e. usually the type of thrown exception is publicly derived - from \a exceptiontype) then execution will be continued. If not-substitutable - type of exception is thrown or the \a expression doesn't throw an exception - at all, then a failure will be recorded in the test log and - the test won't be executed further. +/*! + \macro QVERIFY_THROWS_EXCEPTION(exceptiontype, ...) + \relates QTest + \since 6.3 + + The QVERIFY_THROWS_EXCEPTION macro executes the expression given in the variadic + argument and expects to catch an exception thrown from the expression. + + There are several possible outcomes: + + \list + \li If the expression throws an exception that is either the same as + \a exceptiontype or derived from \a exceptiontype, then execution will continue. + + \li Otherwise, if the expression throws no exception, or the + exception thrown derives from \c{std::exception}, then a failure + will be recorded in the test log and the macro returns early + (from enclosing function). + + \li If the thrown exception derives neither from \c{std::exception} nor from + \a exceptiontype, a failure will be recorded in the test log, and the exception is + re-thrown. This avoids problems with e.g. pthread cancellation exceptions. + \endlist + + The macro uses variadic arguments so the expression can contain commas that the + preprocessor considers argument separators, e.g. as in + \code + QVERIFY_THROWS_EXCEPTION(std::bad_alloc, + // macro arguments: ^ exceptiontype + std::vector<std::pair<int, long>>{42'000'000'000, {42, 42L}}); + // macro arguments: \---------- 1 ----------/ \-------- 2 --------/ \3/ \ 4 / + // \----------------------- expression -----------------------/ + \endcode + + \note This macro can only be used in a test function that is invoked + by the test framework. +*/ + +/*! + \macro QVERIFY_THROWS_NO_EXCEPTION(...) + \since 6.3 + + \relates QTest + + The QVERIFY_THROWS_NO_EXCEPTION macro executes the expression given in its + variadic argument and tries to catch any exception thrown from the expression. + + There are several different outcomes: + + \list + \li If the expression does not throw an exception, then execution will continue. + + \li Otherwise, if an exception derived from \c{std::exception} is caught, a failure + will be recorded in the test log and the macro returns early (implicit return from + enclosing function). + + \li If an exception not derived from \c{std::exception} is caught, a failure will be + recorded in the test log and the exception will be re-thrown. This avoids problems + with e.g. pthread cancellation exceptions. + \endlist + + The macro uses variadic arguments so the expression can contain commas that the + preprocessor considers argument separators, e.g. as in + \code + QVERIFY_THROWS_NO_EXCEPTION(std::pair<int, long>{42, 42L}); + // macro arguments: \---- 1 ----/ \-- 2 -/ \3 / + \endcode \note This macro can only be used in a test function that is invoked by the test framework. @@ -183,6 +359,10 @@ is reached, a failure is recorded in the test log and the test won't be executed further. + //![chrono-timeout] + Since Qt 6.8, the \a timeout can also be a \c{std::chrono} literal such as \c{2s}. + //![chrono-timeout] + \note This macro can only be used in a test function that is invoked by the test framework. @@ -214,9 +394,11 @@ except that it outputs a verbose \a message when \a condition is still false after the specified \a timeout (in milliseconds). The \a message is a plain C string. + \include qtestcase.qdoc chrono-timeout + Example: \code - QTRY_VERIFY2_WITH_TIMEOUT(list.size() > 2, QByteArray::number(list.size()).constData(), 10000); + QTRY_VERIFY2_WITH_TIMEOUT(list.size() > 2, QByteArray::number(list.size()).constData(), 10s); \endcode \note This macro can only be used in a test function that is invoked @@ -237,7 +419,7 @@ Example: \code - QTRY_VERIFY2_WITH_TIMEOUT(list.size() > 2, QByteArray::number(list.size()).constData()); + QTRY_VERIFY2(list.size() > 2, QByteArray::number(list.size()).constData()); \endcode \note This macro can only be used in a test function that is invoked @@ -258,6 +440,8 @@ will be processed. If the timeout is reached, a failure is recorded in the test log and the test won't be executed further. + \include qtestcase.qdoc chrono-timeout + \note This macro can only be used in a test function that is invoked by the test framework. @@ -279,6 +463,180 @@ QEXPECT_FAIL() */ +/*! \macro QTRY_COMPARE_EQ_WITH_TIMEOUT(computed, baseline, timeout) + \since 6.4 + \relates QTest + + This macro is similar to QCOMPARE_EQ(), but performs the comparison of the + \a computed and \a baseline values repeatedly, until either the comparison returns + \c true or the \a timeout (in milliseconds) is reached. Between each + comparison, events will be processed. If the timeout is reached, a failure + is recorded in the test log and the test won't be executed further. + + \include qtestcase.qdoc chrono-timeout + + \include qtestcase.qdoc macro-usage-limitation + + \sa QCOMPARE_EQ(), QTRY_COMPARE_EQ() +*/ + +/*! \macro QTRY_COMPARE_EQ(computed, baseline) + \since 6.4 + \relates QTest + + Performs comparison of \a computed and \a baseline values by invoking + QTRY_COMPARE_EQ_WITH_TIMEOUT with a timeout of five seconds. + + \include qtestcase.qdoc macro-usage-limitation + + \sa QCOMPARE_EQ(), QTRY_COMPARE_EQ_WITH_TIMEOUT() +*/ + +/*! \macro QTRY_COMPARE_NE_WITH_TIMEOUT(computed, baseline, timeout) + \since 6.4 + \relates QTest + + This macro is similar to QCOMPARE_NE(), but performs the comparison of the + \a computed and \a baseline values repeatedly, until either the comparison returns + \c true or the \a timeout (in milliseconds) is reached. Between each + comparison, events will be processed. If the timeout is reached, a failure + is recorded in the test log and the test won't be executed further. + + \include qtestcase.qdoc chrono-timeout + + \include qtestcase.qdoc macro-usage-limitation + + \sa QCOMPARE_NE(), QTRY_COMPARE_NE() +*/ + +/*! \macro QTRY_COMPARE_NE(computed, baseline) + \since 6.4 + \relates QTest + + Performs comparison of \a computed and \a baseline values by invoking + QTRY_COMPARE_NE_WITH_TIMEOUT with a timeout of five seconds. + + \include qtestcase.qdoc macro-usage-limitation + + \sa QCOMPARE_NE(), QTRY_COMPARE_NE_WITH_TIMEOUT() +*/ + +/*! \macro QTRY_COMPARE_LT_WITH_TIMEOUT(computed, baseline, timeout) + \since 6.4 + \relates QTest + + This macro is similar to QCOMPARE_LT(), but performs the comparison of the + \a computed and \a baseline values repeatedly, until either the comparison returns + \c true or the \a timeout (in milliseconds) is reached. Between each + comparison, events will be processed. If the timeout is reached, a failure + is recorded in the test log and the test won't be executed further. + + \include qtestcase.qdoc chrono-timeout + + \include qtestcase.qdoc macro-usage-limitation + + \sa QCOMPARE_LT(), QTRY_COMPARE_LT() +*/ + +/*! \macro QTRY_COMPARE_LT(computed, baseline) + \since 6.4 + \relates QTest + + Performs comparison of \a computed and \a baseline values by invoking + QTRY_COMPARE_LT_WITH_TIMEOUT with a timeout of five seconds. + + \include qtestcase.qdoc macro-usage-limitation + + \sa QCOMPARE_LT(), QTRY_COMPARE_LT_WITH_TIMEOUT() +*/ + +/*! \macro QTRY_COMPARE_LE_WITH_TIMEOUT(computed, baseline, timeout) + \since 6.4 + \relates QTest + + This macro is similar to QCOMPARE_LE(), but performs the comparison of the + \a computed and \a baseline values repeatedly, until either the comparison returns + \c true or the \a timeout (in milliseconds) is reached. Between each + comparison, events will be processed. If the timeout is reached, a failure + is recorded in the test log and the test won't be executed further. + + \include qtestcase.qdoc chrono-timeout + + \include qtestcase.qdoc macro-usage-limitation + + \sa QCOMPARE_LE(), QTRY_COMPARE_LE() +*/ + +/*! \macro QTRY_COMPARE_LE(computed, baseline) + \since 6.4 + \relates QTest + + Performs comparison of \a computed and \a baseline values by invoking + QTRY_COMPARE_LE_WITH_TIMEOUT with a timeout of five seconds. + + \include qtestcase.qdoc macro-usage-limitation + + \sa QCOMPARE_LE(), QTRY_COMPARE_LE_WITH_TIMEOUT() +*/ + +/*! \macro QTRY_COMPARE_GT_WITH_TIMEOUT(computed, baseline, timeout) + \since 6.4 + \relates QTest + + This macro is similar to QCOMPARE_GT(), but performs the comparison of the + \a computed and \a baseline values repeatedly, until either the comparison returns + \c true or the \a timeout (in milliseconds) is reached. Between each + comparison, events will be processed. If the timeout is reached, a failure + is recorded in the test log and the test won't be executed further. + + \include qtestcase.qdoc chrono-timeout + + \include qtestcase.qdoc macro-usage-limitation + + \sa QCOMPARE_GT(), QTRY_COMPARE_GT() +*/ + +/*! \macro QTRY_COMPARE_GT(computed, baseline) + \since 6.4 + \relates QTest + + Performs comparison of \a computed and \a baseline values by invoking + QTRY_COMPARE_GT_WITH_TIMEOUT with a timeout of five seconds. + + \include qtestcase.qdoc macro-usage-limitation + + \sa QCOMPARE_GT(), QTRY_COMPARE_GT_WITH_TIMEOUT() +*/ + +/*! \macro QTRY_COMPARE_GE_WITH_TIMEOUT(computed, baseline, timeout) + \since 6.4 + \relates QTest + + This macro is similar to QCOMPARE_GE(), but performs the comparison of the + \a computed and \a baseline values repeatedly, until either the comparison returns + \c true or the \a timeout (in milliseconds) is reached. Between each + comparison, events will be processed. If the timeout is reached, a failure + is recorded in the test log and the test won't be executed further. + + \include qtestcase.qdoc chrono-timeout + + \include qtestcase.qdoc macro-usage-limitation + + \sa QCOMPARE_GE(), QTRY_COMPARE_GE() +*/ + +/*! \macro QTRY_COMPARE_GE(computed, baseline) + \since 6.4 + \relates QTest + + Performs comparison of \a computed and \a baseline values by invoking + QTRY_COMPARE_GE_WITH_TIMEOUT with a timeout of five seconds. + + \include qtestcase.qdoc macro-usage-limitation + + \sa QCOMPARE_GE(), QTRY_COMPARE_GE_WITH_TIMEOUT() +*/ + /*! \macro QFETCH(type, name) \relates QTest @@ -336,6 +694,7 @@ \relates QTest \threadsafe + \deprecated Use qWarning() instead. Appends \a message as a warning to the test log. This macro can be used anywhere in your tests. @@ -443,7 +802,8 @@ failure will be reported. If a \l QVERIFY() or \l QCOMPARE() is marked as an expected failure, - but passes instead, an unexpected pass (XPASS) is written to the test log. + but passes instead, an unexpected pass (XPASS) is written to the test log + and will be counted as a test failure. The parameter \a dataIndex describes for which entry in the test data the failure is expected. Pass an empty string (\c{""}) if the failure @@ -452,7 +812,8 @@ \a comment will be appended to the test log for the expected failure. \a mode is a \l QTest::TestFailMode and sets whether the test should - continue to execute or not. + continue to execute or not. The \a mode is applied regardless of + whether the expected test failure occurs. \note This macro can only be used in a test function that is invoked by the test framework. @@ -469,7 +830,7 @@ \snippet code/src_qtestlib_qtestcase.cpp 10 The above testfunction will not continue executing for the test data - entry \c{data27}. + entry \c{data27} (regardless of the value of \c i). \sa QTest::TestFailMode, QVERIFY(), QCOMPARE() */ @@ -621,8 +982,8 @@ this macro. Unlike QBENCHMARK, the contents of the contained code block is only run - once. The elapsed time will be reported as "0" if it's to short to - be measured by the selected backend. (Use) + once. The elapsed time will be reported as "0" if it's too short to + be measured by the selected backend. \sa {Qt Test Overview#Creating a Benchmark}{Creating a Benchmark}, {Chapter 5: Writing a Benchmark}{Writing a Benchmark} @@ -630,14 +991,16 @@ /*! \enum QTest::TestFailMode - This enum describes the modes for handling an expected failure of the - \l QVERIFY() or \l QCOMPARE() macros. + This enum describes the modes for handling a check, such as by \l + QVERIFY() or \l QCOMPARE() macros, that is known to fail. The mode + applies regardless of whether the check fails or succeeds. - \value Abort Aborts the execution of the test. Use this mode when it - doesn't make sense to execute the test any further after the - expected failure. + \value Abort Aborts the execution of the test. Use this mode when + it doesn't make sense to execute the test any further after + the problematic check. - \value Continue Continues execution of the test after the expected failure. + \value Continue Continues execution of the test after the + problematic check. \sa QEXPECT_FAIL() */ @@ -888,7 +1251,7 @@ \sa QTest::keyClick() */ -/*! \fn void QTest::mousePress(QWidget *widget, Qt::MouseButton button, Qt::KeyboardModifiers modifier = 0, QPoint pos = QPoint(), int delay=-1) +/*! \fn void QTest::mousePress(QWidget *widget, Qt::MouseButton button, Qt::KeyboardModifiers modifier, QPoint pos = QPoint(), int delay=-1) Simulates pressing a mouse \a button with an optional \a modifier on a \a widget. The position is defined by \a pos; the default @@ -899,7 +1262,7 @@ \sa QTest::mouseRelease(), QTest::mouseClick() */ -/*! \fn void QTest::mousePress(QWindow *window, Qt::MouseButton button, Qt::KeyboardModifiers stateKey = 0, QPoint pos = QPoint(), int delay=-1) +/*! \fn void QTest::mousePress(QWindow *window, Qt::MouseButton button, Qt::KeyboardModifiers stateKey, QPoint pos = QPoint(), int delay=-1) \overload \since 5.0 @@ -912,18 +1275,27 @@ \sa QTest::mouseRelease(), QTest::mouseClick() */ -/*! \fn void QTest::mouseRelease(QWidget *widget, Qt::MouseButton button, Qt::KeyboardModifiers modifier = 0, QPoint pos = QPoint(), int delay=-1) +/*! \fn void QTest::mouseRelease(QWidget *widget, Qt::MouseButton button, Qt::KeyboardModifiers modifier, QPoint pos = QPoint(), int delay=-1) Simulates releasing a mouse \a button with an optional \a modifier on a \a widget. The position of the release is defined by \a pos; the default position is the center of the widget. If \a delay is specified, the test will wait for the specified amount of - milliseconds before releasing the button. + milliseconds before releasing the button; otherwise, it will wait for a + default amount of time (1 ms), which can be overridden via + \l {Testing Options}{command-line arguments}. + + \note If you wish to test a double-click by sending events individually, + specify a short delay, greater than the default, on both mouse release events. + The total of the delays for the press, release, press and release must be + less than QStyleHints::mouseDoubleClickInterval(). But if you don't need + to check state between events, it's better to use QTest::mouseDClick(). + \snippet code/src_qtestlib_qtestcase_snippet.cpp 35 \sa QTest::mousePress(), QTest::mouseClick() */ -/*! \fn void QTest::mouseRelease(QWindow *window, Qt::MouseButton button, Qt::KeyboardModifiers stateKey = 0, QPoint pos = QPoint(), int delay=-1) +/*! \fn void QTest::mouseRelease(QWindow *window, Qt::MouseButton button, Qt::KeyboardModifiers stateKey, QPoint pos = QPoint(), int delay=-1) \overload \since 5.0 @@ -931,12 +1303,21 @@ on a \a window. The position of the release is defined by \a pos; the default position is the center of the window. If \a delay is specified, the test will wait for the specified amount of - milliseconds before releasing the button. + milliseconds before releasing the button; otherwise, it will wait for a + default amount of time (1 ms), which can be overridden via + \l {Testing Options}{command-line arguments}. + + \note If you wish to test a double-click by sending events individually, + specify a short delay, greater than the default, on both mouse release events. + The total of the delays for the press, release, press and release must be + less than QStyleHints::mouseDoubleClickInterval(). But if you don't need + to check state between events, it's better to use QTest::mouseDClick(). + \snippet code/src_qtestlib_qtestcase_snippet.cpp 35 \sa QTest::mousePress(), QTest::mouseClick() */ -/*! \fn void QTest::mouseClick(QWidget *widget, Qt::MouseButton button, Qt::KeyboardModifiers modifier = 0, QPoint pos = QPoint(), int delay=-1) +/*! \fn void QTest::mouseClick(QWidget *widget, Qt::MouseButton button, Qt::KeyboardModifiers modifier, QPoint pos = QPoint(), int delay=-1) Simulates clicking a mouse \a button with an optional \a modifier on a \a widget. The position of the click is defined by \a pos; @@ -947,7 +1328,7 @@ \sa QTest::mousePress(), QTest::mouseRelease() */ -/*! \fn void QTest::mouseClick(QWindow *window, Qt::MouseButton button, Qt::KeyboardModifiers stateKey = 0, QPoint pos = QPoint(), int delay=-1) +/*! \fn void QTest::mouseClick(QWindow *window, Qt::MouseButton button, Qt::KeyboardModifiers stateKey, QPoint pos = QPoint(), int delay=-1) \overload \since 5.0 @@ -960,7 +1341,7 @@ \sa QTest::mousePress(), QTest::mouseRelease() */ -/*! \fn void QTest::mouseDClick(QWidget *widget, Qt::MouseButton button, Qt::KeyboardModifiers modifier = 0, QPoint pos = QPoint(), int delay=-1) +/*! \fn void QTest::mouseDClick(QWidget *widget, Qt::MouseButton button, Qt::KeyboardModifiers modifier, QPoint pos = QPoint(), int delay=-1) Simulates double clicking a mouse \a button with an optional \a modifier on a \a widget. The position of the click is defined by @@ -971,7 +1352,7 @@ \sa QTest::mouseClick() */ -/*! \fn void QTest::mouseDClick(QWindow *window, Qt::MouseButton button, Qt::KeyboardModifiers stateKey = 0, QPoint pos = QPoint(), int delay=-1) +/*! \fn void QTest::mouseDClick(QWindow *window, Qt::MouseButton button, Qt::KeyboardModifiers stateKey, QPoint pos = QPoint(), int delay=-1) \overload \since 5.0 @@ -1002,11 +1383,15 @@ moving the mouse pointer. */ -/*! - \fn template <typename T1, typename T2> char *QTest::toString(const QPair<T1, T2> &pair) - \overload - \since 5.11 - Returns a textual representation of the \a pair. +/*! \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) + \since 6.8 + + Simulates a wheel event within \a window at position \a pos in local + window coordinates. \a angleDelta contains the wheel rotation angle. + A positive value means forward rotation, and a negative one means backward. + \a pixelDelta contains the scrolling distance in pixels on screen. This value can be null. + The keyboard states at the time of the event are specified by \a stateKey. + The scrolling phase of the event is specified by \a phase. */ /*! @@ -1074,7 +1459,7 @@ */ /*! - \fn char *QTest::toString(const QLatin1String &string) + \fn char *QTest::toString(const QLatin1StringView &string) \overload Returns a textual representation of the given \a string. @@ -1255,9 +1640,10 @@ */ /*! - \fn template <typename Tuple, int... I> char *QTest::toString(const Tuple &tuple, QtPrivate::IndexesList<I...> ) - \internal - \since 5.12 + \fn char *QTest::toString(const QKeySequence &ks) + \overload + \since 6.5 + Returns a textual representation of the key sequence \a ks. */ /*! @@ -1267,10 +1653,10 @@ Creates a dummy touch device of type \a devType with capabilities \a caps for simulation of touch events. - The touch device will be registered with the QPA window system interface, - and deleted automatically when the QCoreApplication is deleted. So you - should typically use createTouchDevice() to initialize a QPointingDevice - member variable in your test case class, and use the same instance for all tests. + The touch device will be registered with the Qt window system interface. + You should typically use createTouchDevice() to initialize a QPointingDevice + member variable in your test case class, use the same instance for all tests and + delete it when no longer needed. \sa QTest::QTouchEventSequence, touchEvent() */ @@ -1298,15 +1684,21 @@ */ /*! - \fn void QTest::QTouchEventSequence::commit(bool processEvents) + \fn bool QTest::QTouchEventSequence::commit(bool processEvents) + + Commits this touch event to the event system, and returns whether it was + accepted after delivery. + + Normally there is no need to call this function because it is called from + the destructor. However, if autoCommit is disabled, the events only get + committed upon explicitly calling this function. Another reason to call it + explicitly is to check the return value. - Commits this sequence of touch events to the event system. Normally there is no need to call this - function because it is called from the destructor. However, if autoCommit is disabled, the events - only get committed upon explicitly calling this function. + In special cases, tests may want to disable the processing of the event. + This can be achieved by setting \a processEvents to false. This results in + merely queuing the event: the event loop will not be forced to process it. - In special cases tests may want to disable the processing of the events. This can be achieved by - setting \a processEvents to false. This results in merely queuing the events, the event loop will - not be forced to process them. + Returns whether the event was accepted after delivery. */ /*! |