Add QQuickTest::qWaitForItemPolished()

Verifying that an item was polished is quite common in Qt's auto tests:

- The Qt Quick auto tests have a util function for it in
  visualtestutil.h (line 103).
- "git grep polishScheduled -- tests/auto | wc -l" says that there are
  269 usages of polishScheduled in Qt Quick auto tests, almost all of
  which look like this:

  QTRY_COMPARE(QQuickItemPrivate::get(item)->polishScheduled, false);
- QQuickTableView's auto tests have their own function:

  #define WAIT_UNTIL_POLISHED \
      QVERIFY(tableViewPrivate->polishScheduled); \
      QTRY_VERIFY(!tableViewPrivate->polishScheduled)
- More recently, QQuickMenu started requiring it (see menuutil.h).

QQuickItem::polish() and QQuickItem::updatePolish() are both public
functions, so the notion of polishing in Qt Quick is not new or hidden.
This means that any user applications that have custom items that make
use of the polish() => updatePolish() system will benefit from having
a reliable method of testing their behavior. In addition, anyone
wanting to simulate interaction with items in e.g. QQuickMenu will
need this API if they don't want to use unreliable qWait() calls.

With this in mind, this and the previous patch aim to standardise/
simplify the various private API checks and utility functions, and
provide public API for users so that they can benefit from more
reliable tests. When used together, the code will look like this:

    QVERIFY(QQuickTest::qIsPolishScheduled(item));
    QVERIFY(QQuickTest::qWaitForItemPolished(item));

[ChangeLog][QtQuickTest][QQuickTest] Added
QQuickTest::qWaitForItemPolished() for verifying that updatePolish()
was called on an item.

Fixes: QTBUG-71224
Change-Id: I8841910212e7f1a431ba845cae8a1ba7b4f4da67
Reviewed-by: Gatis Paeglis <gatis.paeglis@qt.io>

1 files changed, 27 insertions, 0 deletions

diff --git a/src/qmltest/quicktest.cpp b/src/qmltest/quicktest.cpp
index 58fc5a99e1..814e03d6e3 100644
--- a/src/qmltest/quicktest.cpp
+++ b/src/qmltest/quicktest.cpp
@@ -44,6 +44,8 @@
 #include <QtQml/qqml.h>
 #include <QtQml/qqmlengine.h>
 #include <QtQml/qqmlcontext.h>
+#include <QtQuick/private/qquickitem_p.h>
+#include <QtQuick/qquickitem.h>
 #include <QtQuick/qquickview.h>
 #include <QtQml/qjsvalue.h>
 #include <QtQml/qjsengine.h>
@@ -90,6 +92,31 @@ bool QQuickTest::qIsPolishScheduled(const QQuickItem *item)
     return QQuickItemPrivate::get(item)->polishScheduled;
 }
 
+/*!
+    \fn bool qWaitForItemPolished(const QQuickItem *item, int timeout = 5000)
+    \relates QtQuickTest
+    \since 5.13
+
+    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.
+
+    To use this function, add the following line to your test's \c .pro file:
+
+    \code
+        QT += qmltest
+    \endcode
+
+    \sa QQuickItem::polish(), QQuickItem::updatePolish(),
+        QQuickTest::qIsPolishScheduled()
+*/
+bool QQuickTest::qWaitForItemPolished(const QQuickItem *item, int timeout)
+{
+    return QTest::qWaitFor([&]() { return !QQuickItemPrivate::get(item)->polishScheduled; }, timeout);
+}
+
 class QTestRootObject : public QObject
 {
     Q_OBJECT