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>

1 files changed, 66 insertions, 0 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('"')))