From f27588348bccc0e36236500f2257f8006609318f Mon Sep 17 00:00:00 2001 From: Andreas Eliasson Date: Tue, 20 May 2025 13:26:31 +0200 Subject: [PATCH] Doc: Add \note to QTest::qWait() to consider QTRY_*() macros instead MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit There seems to be a case that qWait() is a source of eventual pain. Add \note to encourage the use of the QTRY_*() macros. Fixes: QTBUG-136538 Pick-to: 6.10 6.9 6.8 Change-Id: I52daa8c38a55f8db66d8c941c7cbfff7b7060a5b Reviewed-by: Topi Reiniö --- src/corelib/kernel/qtestsupport_core.cpp | 17 ++++++++++++++++- 1 file changed, 16 insertions(+), 1 deletion(-) diff --git a/src/corelib/kernel/qtestsupport_core.cpp b/src/corelib/kernel/qtestsupport_core.cpp index 2ac44bb13df..0d11f0bd666 100644 --- a/src/corelib/kernel/qtestsupport_core.cpp +++ b/src/corelib/kernel/qtestsupport_core.cpp @@ -107,7 +107,22 @@ Q_CORE_EXPORT void QTest::qWait(int msecs) The code above will wait until the network server is responding for a maximum of about 12.5 seconds. - \sa QTest::qSleep(), QSignalSpy::wait() + The \l{QTRY_COMPARE()}{QTRY_*} macros are usually a better choice than + qWait(). qWait() always pauses for the full timeout, which can leave the + test idle and slow down execution. + + The \c {QTRY_*} macros poll the condition until it succeeds or the timeout + expires. Your test therefore continues as soon as possible and stays more + reliable. If the condition still fails, the macros double the timeout once + and report the new value so that you can adjust it. + + For example, rewrite the code above as: + + \code + QTRY_VERIFY_WITH_TIMEOUT(!myNetworkServerNotResponding(), 12.5s); + \endcode + + \sa QTest::qSleep(), QSignalSpy::wait(), QTRY_VERIFY_WITH_TIMEOUT() */ Q_CORE_EXPORT void QTest::qWait(std::chrono::milliseconds msecs) {