QtQuickTest: add API for checking for polish at window level

This adds a qIsPolishScheduled(QQuickWindow *) overload of
qIsPolishScheduled(QQuickItem *) (added in
40d6072bc8a4df0fe1a16025fe30fe653463a446) and deprecates
qWaitForItemPolished() (added in
7a3cad0619662b992154e075ec6b840bfc8a46a7) in favor of qWaitForPolish(),
which has QQuickItem* and QQuickWindow* overloads.

The existing functions that take QQuickItem are useful, but testing
Qt Quick applications can be made even easier by allowing users to
check if a window has any items that need to be polished. This
information is already present (in QQuickWindowPrivate::itemsToPolish),
so it's very efficient to check for.

This is especially useful now that Qt Quick Layouts using polishing for
their layouting, for example, as it's no longer necessary to find
individual polishable items in complex hierarchies before proceeding
to interact with child items.

[ChangeLog][QtQuickTest][QQuickTest] Added
QQuickTest::qIsPolishScheduled(QQuickWindow *) and
QQuickTest::qWaitForPolish(QQuickWindow *) functions for verifying that
updatePolish() was called on one or more items managed by a window.

[ChangeLog][QtQuickTest][QQuickTest] Deprecated
QQuickTest::qWaitForItemPolished(QQuickItem *). Use the new
QQuickTest::qWaitForPolish(QQuickItem *) function instead.

Fixes: QTBUG-93757
Change-Id: I95b6e051b3c9fd2fa93604f4d9ccda486bb29f9d
Reviewed-by: Richard Moe Gustavsen <richard.gustavsen@qt.io>
Reviewed-by: Qt CI Bot <qt_ci_bot@qt-project.org>

5 files changed, 83 insertions, 5 deletions

diff --git a/src/qmltest/quicktest.cpp b/src/qmltest/quicktest.cpp
index e7ad511fe1..e2deaf5533 100644
--- a/src/qmltest/quicktest.cpp
+++ b/src/qmltest/quicktest.cpp
@@ -45,8 +45,10 @@
 #include <QtQml/qqmlengine.h>
 #include <QtQml/qqmlcontext.h>
 #include <QtQuick/private/qquickitem_p.h>
+#include <QtQuick/private/qquickwindow_p.h>
 #include <QtQuick/qquickitem.h>
 #include <QtQuick/qquickview.h>
+#include <QtQuick/qquickwindow.h>
 #include <QtQml/qjsvalue.h>
 #include <QtQml/qjsengine.h>
 #include <QtQml/qqmlpropertymap.h>
@@ -110,7 +112,35 @@ bool QQuickTest::qIsPolishScheduled(const QQuickItem *item)
 }
 
 /*!
+    \since 6.4
+    \overload qIsPolishScheduled()
+
+    Returns \c true if there are any items managed by this window for
+    which \c qIsPolishScheduled(item) returns \c true, otherwise
+    returns \c false.
+
+    For example, if an item somewhere within the scene may or may not
+    be polished, but you need to wait for it if it is, you can use
+    the following code:
+
+    \code
+        if (QQuickTest::qIsPolishScheduled(window))
+            QVERIFY(QQuickTest::qWaitForPolish(window));
+    \endcode
+
+    \sa QQuickItem::polish(), QQuickItem::updatePolish(),
+        QQuickTest::qWaitForPolish()
+*/
+bool QQuickTest::qIsPolishScheduled(const QQuickWindow *window)
+{
+    return !QQuickWindowPrivate::get(window)->itemsToPolish.isEmpty();
+}
+
+#if QT_VERSION < QT_VERSION_CHECK(7, 0, 0)
+#if QT_DEPRECATED_SINCE(6, 4)
+/*!
     \since 5.13
+    \deprecated [6.4] Use \l qWaitForPolish() instead.
 
     Waits for \a timeout milliseconds or until
     \l {QQuickItem::}{updatePolish()} has been called on \a item.
@@ -126,9 +156,45 @@ bool QQuickTest::qIsPolishScheduled(const QQuickItem *item)
 */
 bool QQuickTest::qWaitForItemPolished(const QQuickItem *item, int timeout)
 {
+    return qWaitForPolish(item, timeout);
+}
+#endif
+#endif
+
+/*!
+    \since 6.4
+
+    Waits for \a timeout milliseconds or until
+    \l {QQuickItem::}{updatePolish()} has been called on \a item.
+
+    Returns \c true if \c updatePolish() was called on \a item within
+    \a timeout milliseconds, otherwise returns \c false.
+
+    \sa QQuickItem::polish(), QQuickItem::updatePolish(),
+        QQuickTest::qIsPolishScheduled()
+*/
+bool QQuickTest::qWaitForPolish(const QQuickItem *item, int timeout)
+{
     return QTest::qWaitFor([&]() { return !QQuickItemPrivate::get(item)->polishScheduled; }, timeout);
 }
 
+/*!
+    \since 6.4
+
+    Waits for \a timeout milliseconds or until \c qIsPolishScheduled(item)
+    returns \c false for all items managed by \a window.
+
+    Returns \c true if \c qIsPolishScheduled(item) returns false for all items
+    within \a timeout milliseconds, otherwise returns \c false.
+
+    \sa QQuickItem::polish(), QQuickItem::updatePolish(),
+        QQuickTest::qIsPolishScheduled()
+*/
+bool QQuickTest::qWaitForPolish(const QQuickWindow *window, int timeout)
+{
+    return QTest::qWaitFor([&]() { return QQuickWindowPrivate::get(window)->itemsToPolish.isEmpty(); }, timeout);
+}
+
 static inline QString stripQuotes(const QString &s)
 {
     if (s.length() >= 2 && s.startsWith(QLatin1Char('"')) && s.endsWith(QLatin1Char('"')))
diff --git a/src/qmltest/quicktest.h b/src/qmltest/quicktest.h
index 8e3510c9a5..c4d0612ed5 100644
--- a/src/qmltest/quicktest.h
+++ b/src/qmltest/quicktest.h
@@ -46,6 +46,7 @@
 QT_BEGIN_NAMESPACE
 
 class QQuickItem;
+class QQuickWindow;
 
 Q_QUICK_TEST_EXPORT int quick_test_main(int argc, char **argv, const char *name, const char *sourceDir);
 Q_QUICK_TEST_EXPORT int quick_test_main_with_setup(int argc, char **argv, const char *name, const char *sourceDir, QObject *setup);
@@ -101,8 +102,19 @@ Q_QUICK_TEST_EXPORT int quick_test_main_with_setup(int argc, char **argv, const
 #endif
 
 namespace QQuickTest {
+static const int defaultTimeout = 5000;
+
 Q_QUICK_TEST_EXPORT bool qIsPolishScheduled(const QQuickItem *item);
-Q_QUICK_TEST_EXPORT bool qWaitForItemPolished(const QQuickItem *item, int timeout = 5000);
+Q_QUICK_TEST_EXPORT bool qIsPolishScheduled(const QQuickWindow *window);
+
+#if QT_VERSION < QT_VERSION_CHECK(7, 0, 0)
+#if QT_DEPRECATED_SINCE(6, 4)
+    QT_DEPRECATED_X("Use qWaitForPolish(QQuickItem *) instead")
+    Q_QUICK_TEST_EXPORT bool qWaitForItemPolished(const QQuickItem *item, int timeout = defaultTimeout);
+#endif
+#endif
+Q_QUICK_TEST_EXPORT bool qWaitForPolish(const QQuickItem *item, int timeout = defaultTimeout);
+Q_QUICK_TEST_EXPORT bool qWaitForPolish(const QQuickWindow *window, int timeout = defaultTimeout);
 }
 
 QT_END_NAMESPACE
diff --git a/src/qmltest/quicktestresult.cpp b/src/qmltest/quicktestresult.cpp
index e4ef4e68ae..b0eaaa0db3 100644
--- a/src/qmltest/quicktestresult.cpp
+++ b/src/qmltest/quicktestresult.cpp
@@ -807,7 +807,7 @@ bool QuickTestResult::isPolishScheduled(QQuickItem *item) const
 
 bool QuickTestResult::waitForItemPolished(QQuickItem *item, int timeout)
 {
-    return QQuickTest::qWaitForItemPolished(item, timeout);
+    return QQuickTest::qWaitForPolish(item, timeout);
 }
 
 namespace QTest {
diff --git a/src/quickcontrolstestutils/dialogstestutils.cpp b/src/quickcontrolstestutils/dialogstestutils.cpp
index f989989a63..5d02705a48 100644
--- a/src/quickcontrolstestutils/dialogstestutils.cpp
+++ b/src/quickcontrolstestutils/dialogstestutils.cpp
@@ -45,7 +45,7 @@ bool QQuickDialogTestUtils::verifyFileDialogDelegates(QQuickListView *fileDialog
     const QStringList &expectedFiles, QString &failureMessage)
 {
     if (QQuickTest::qIsPolishScheduled(fileDialogListView)) {
-        if (!QQuickTest::qWaitForItemPolished(fileDialogListView)) {
+        if (!QQuickTest::qWaitForPolish(fileDialogListView)) {
             failureMessage = QLatin1String("Failed to polish fileDialogListView");
             return false;
         }
@@ -89,7 +89,7 @@ bool QQuickDialogTestUtils::verifyBreadcrumbDelegates(QQuickFolderBreadcrumbBar
     }
 
     if (QQuickTest::qIsPolishScheduled(breadcrumbBarListView)) {
-        if (!QQuickTest::qWaitForItemPolished(breadcrumbBarListView)) {
+        if (!QQuickTest::qWaitForPolish(breadcrumbBarListView)) {
             failureMessage = QLatin1String("Failed to polish breadcrumbBarListView");
             return false;
         }
diff --git a/src/quicktestutils/quick/visualtestutils.cpp b/src/quicktestutils/quick/visualtestutils.cpp
index 043b22d763..b030207e6e 100644
--- a/src/quicktestutils/quick/visualtestutils.cpp
+++ b/src/quicktestutils/quick/visualtestutils.cpp
@@ -147,7 +147,7 @@ bool QQuickVisualTestUtils::compareImages(const QImage &ia, const QImage &ib, QS
 QQuickItem *QQuickVisualTestUtils::findViewDelegateItem(QQuickItemView *itemView, int index, FindViewDelegateItemFlags flags)
 {
     if (QQuickTest::qIsPolishScheduled(itemView)) {
-        if (!QQuickTest::qWaitForItemPolished(itemView)) {
+        if (!QQuickTest::qWaitForPolish(itemView)) {
             qWarning() << "failed to polish" << itemView;
             return nullptr;
         }