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>

6 files changed, 161 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
diff --git a/src/qmltest/quicktest.h b/src/qmltest/quicktest.h
index d8054498ed..8e3510c9a5 100644
--- a/src/qmltest/quicktest.h
+++ b/src/qmltest/quicktest.h
@@ -102,6 +102,7 @@ Q_QUICK_TEST_EXPORT int quick_test_main_with_setup(int argc, char **argv, const
 
 namespace QQuickTest {
 Q_QUICK_TEST_EXPORT bool qIsPolishScheduled(const QQuickItem *item);
+Q_QUICK_TEST_EXPORT bool qWaitForItemPolished(const QQuickItem *item, int timeout = 5000);
 }
 
 QT_END_NAMESPACE
diff --git a/tests/auto/quicktest/polish/data/polish.qml b/tests/auto/quicktest/polish/data/polish.qml
new file mode 100644
index 0000000000..0ab3afda2e
--- /dev/null
+++ b/tests/auto/quicktest/polish/data/polish.qml
@@ -0,0 +1,32 @@
+/****************************************************************************
+**
+** Copyright (C) 2018 The Qt Company Ltd.
+** Contact: https://www.qt.io/licensing/
+**
+** This file is part of the test suite of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:GPL-EXCEPT$
+** 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 General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU
+** General Public License version 3 as published by the Free Software
+** Foundation with exceptions as appearing in the file LICENSE.GPL3-EXCEPT
+** included in the packaging of this file. Please review the following
+** information to ensure the GNU General Public License requirements will
+** be met: https://www.gnu.org/licenses/gpl-3.0.html.
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+import QtQuick 2.0
+import Test 1.0
+
+CustomItem {}
diff --git a/tests/auto/quicktest/polish/polish.pro b/tests/auto/quicktest/polish/polish.pro
new file mode 100644
index 0000000000..0dfb4bdf5e
--- /dev/null
+++ b/tests/auto/quicktest/polish/polish.pro
@@ -0,0 +1,12 @@
+CONFIG += qmltestcase
+macos:CONFIG -= app_bundle
+TARGET = tst_polish
+
+QT += testlib quick quick-private
+
+include (../../shared/util.pri)
+
+SOURCES += tst_polish.cpp
+
+TESTDATA += \
+    $$PWD/data/*.qml
diff --git a/tests/auto/quicktest/polish/tst_polish.cpp b/tests/auto/quicktest/polish/tst_polish.cpp
new file mode 100644
index 0000000000..3b96002cd2
--- /dev/null
+++ b/tests/auto/quicktest/polish/tst_polish.cpp
@@ -0,0 +1,88 @@
+/****************************************************************************
+**
+** Copyright (C) 2018 The Qt Company Ltd.
+** Contact: https://www.qt.io/licensing/
+**
+** This file is part of the test suite of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:GPL-EXCEPT$
+** 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 General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU
+** General Public License version 3 as published by the Free Software
+** Foundation with exceptions as appearing in the file LICENSE.GPL3-EXCEPT
+** included in the packaging of this file. Please review the following
+** information to ensure the GNU General Public License requirements will
+** be met: https://www.gnu.org/licenses/gpl-3.0.html.
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+#include <QtTest/qtest.h>
+#include <QtQml/qqmlengine.h>
+#include <QtQml/qqmlcontext.h>
+#include <QtQuick/qquickitem.h>
+#include <QQuickView>
+#include <QtQuickTest/quicktest.h>
+
+#include "../../shared/util.h"
+
+class CustomItem : public QQuickItem
+{
+    Q_OBJECT
+
+public:
+    CustomItem() {}
+
+    void updatePolish() override
+    {
+        updatePolishCalled = true;
+    }
+
+    bool updatePolishCalled = false;
+};
+
+class tst_Polish : public QQmlDataTest
+{
+    Q_OBJECT
+
+public:
+    tst_Polish();
+
+private slots:
+    void testPolish();
+};
+
+tst_Polish::tst_Polish()
+{
+    qmlRegisterType<CustomItem>("Test", 1, 0, "CustomItem");
+}
+
+void tst_Polish::testPolish()
+{
+    QQuickView view;
+    view.setSource(testFileUrl("polish.qml"));
+    view.show();
+    QVERIFY(QTest::qWaitForWindowExposed(&view));
+
+    CustomItem *item = qobject_cast<CustomItem*>(view.rootObject());
+    QVERIFY(item);
+
+    item->polish();
+    QVERIFY(QQuickTest::qIsPolishScheduled(item));
+    QVERIFY(!item->updatePolishCalled);
+    QVERIFY(QQuickTest::qWaitForItemPolished(item));
+    QVERIFY(item->updatePolishCalled);
+}
+
+QTEST_MAIN(tst_Polish)
+
+#include "tst_polish.moc"
diff --git a/tests/auto/quicktest/quicktest.pro b/tests/auto/quicktest/quicktest.pro
index 0e3f257e33..6d09f76c1d 100644
--- a/tests/auto/quicktest/quicktest.pro
+++ b/tests/auto/quicktest/quicktest.pro
@@ -1,5 +1,6 @@
 TEMPLATE = subdirs
 SUBDIRS = \
+    polish \
     signalspy \
     quicktestmainwithsetup \
     testfiltering