Add QUICK_TEST_MAIN_WITH_SETUP to allow executing C++ before a QML test

This macro is the same as QUICK_TEST_MAIN, but takes the user's
QObject subclass as an argument, and calls pre-defined slots/invokable
functions on it, similar to how e.g. init() is called for C++ tests.

This allows e.g. context properties to be set for the QML tests.

By basing the API on invokable functions, we give ourselves the freedom
to easily add more functions in the future.

[ChangeLog][QtQuickTest] Added QUICK_TEST_MAIN_WITH_SETUP macro to
allow executing C++ before a QML test (such as registering context
properties).

Task-number: QTBUG-50064
Change-Id: Id566e388553811c220871248403d32545f8ae1eb
Reviewed-by: Shawn Rutledge <shawn.rutledge@qt.io>

1 files changed, 54 insertions, 2 deletions

diff --git a/src/qmltest/doc/src/qtquicktest-index.qdoc b/src/qmltest/doc/src/qtquicktest-index.qdoc
index d2b3f0e1f4..6b5f8fdf4c 100644
--- a/src/qmltest/doc/src/qtquicktest-index.qdoc
+++ b/src/qmltest/doc/src/qtquicktest-index.qdoc
@@ -68,8 +68,8 @@
     \endcode
 
     Where "example" is the identifier to use to uniquely identify
-    this set of tests. You should add \c{CONFIG += qmltestcase}.
-    For example:
+    this set of tests. Finally, add \c{CONFIG += qmltestcase} to the project
+    file:
 
     \badcode
     TEMPLATE = app
@@ -130,4 +130,56 @@
     \badcode
     tst_example -help
     \endcode
+
+    \section1 Executing C++ Before QML Tests
+
+    To execute C++ code before any of the QML tests are run, the
+    \c QUICK_TEST_MAIN_WITH_SETUP macro can be used. This can be useful for
+    setting context properties on the QML engine, amongst other things.
+
+    The macro is identical to \l QUICK_TEST_MAIN, except that it takes an
+    additional \c QObject* argument. The test framework will call slots and
+    invokable functions with the following names:
+
+    \table
+        \header
+            \li Name
+            \li Purpose
+        \row
+            \li void qmlEngineAvailable(QQmlEngine*)
+            \li Called when the QML engine is available.
+                Any \l {QQmlEngine::addImportPath}{import paths},
+                \l {QQmlEngine::addPluginPath}{plugin paths},
+                and \l {QQmlFileSelector::setExtraSelectors}{extra file selectors}
+                will have been set on the engine by this point.
+    \endtable
+
+    Each function will be called once for each \c tst_*.qml file, so any
+    arguments are unique to that test. For example, this means that each QML
+    test file will have its own QML engine.
+
+    The following example demonstrates how the macro can be used to set context
+    properties on the QML engine:
+
+    \code
+    #include <QtQuickTest>
+    #include <QQmlEngine>
+    #include <QQmlContext>
+
+    class Setup : public QObject
+    {
+    public:
+        Setup() {}
+
+    public slots:
+        void qmlEngineAvailable(QQmlEngine *engine)
+        {
+            engine->rootContext()->setContextProperty("myContextProperty", QVariant(true));
+        }
+    };
+
+    QUICK_TEST_MAIN_WITH_SETUP(mytest, Setup)
+
+    #include "tst_mytest.moc"
+    \endcode
 */