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>

3 files changed, 88 insertions, 4 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
 */
diff --git a/src/qmltest/quicktest.cpp b/src/qmltest/quicktest.cpp
index 463833a100..817f9a5389 100644
--- a/src/qmltest/quicktest.cpp
+++ b/src/qmltest/quicktest.cpp
@@ -327,6 +327,11 @@ private:
 
 int quick_test_main(int argc, char **argv, const char *name, const char *sourceDir)
 {
+    return quick_test_main_with_setup(argc, argv, name, sourceDir, nullptr);
+}
+
+int quick_test_main_with_setup(int argc, char **argv, const char *name, const char *sourceDir, QObject *setup)
+{
     // Peek at arguments to check for '-widgets' argument
 #ifdef QT_QMLTEST_WITH_WIDGETS
     bool withWidgets = false;
@@ -516,6 +521,14 @@ int quick_test_main(int argc, char **argv, const char *name, const char *sourceD
         view.rootContext()->setContextProperty
             (QLatin1String("qtest"), QTestRootObject::instance()); // Deprecated. Use QTestRootObject from Qt.test.qtestroot instead
 
+        // Do this down here so that import paths, plugin paths,
+        // file selectors, etc. are available in case the user needs access to them.
+        if (setup) {
+            // Don't check the return value; it's OK if it doesn't exist.
+            // If we add more callbacks in the future, it makes sense if the user only implements one of them.
+            QMetaObject::invokeMethod(setup, "qmlEngineAvailable", Q_ARG(QQmlEngine*, view.engine()));
+        }
+
         view.setObjectName(fi.baseName());
         view.setTitle(view.objectName());
         QTestRootObject::instance()->init();
diff --git a/src/qmltest/quicktest.h b/src/qmltest/quicktest.h
index 6486accb9e..62ed749722 100644
--- a/src/qmltest/quicktest.h
+++ b/src/qmltest/quicktest.h
@@ -48,6 +48,7 @@ QT_BEGIN_NAMESPACE
 QTEST_ADD_GPU_BLACKLIST_SUPPORT_DEFS
 
 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);
 
 #ifdef QUICK_TEST_SOURCE_DIR
 
@@ -67,6 +68,15 @@ Q_QUICK_TEST_EXPORT int quick_test_main(int argc, char **argv, const char *name,
         return quick_test_main(argc, argv, #name, QUICK_TEST_SOURCE_DIR); \
     }
 
+#define QUICK_TEST_MAIN_WITH_SETUP(name, QuickTestSetupClass) \
+    int main(int argc, char **argv) \
+    { \
+        QTEST_ADD_GPU_BLACKLIST_SUPPORT \
+        QTEST_SET_MAIN_SOURCE_PATH \
+        QuickTestSetupClass setup; \
+        return quick_test_main_with_setup(argc, argv, #name, QUICK_TEST_SOURCE_DIR, &setup); \
+    }
+
 #else
 
 #define QUICK_TEST_MAIN(name) \
@@ -74,7 +84,7 @@ Q_QUICK_TEST_EXPORT int quick_test_main(int argc, char **argv, const char *name,
     { \
         QTEST_ADD_GPU_BLACKLIST_SUPPORT \
         QTEST_SET_MAIN_SOURCE_PATH \
-        return quick_test_main(argc, argv, #name, 0); \
+        return quick_test_main(argc, argv, #name, nullptr); \
     }
 
 #define QUICK_TEST_OPENGL_MAIN(name) \
@@ -82,7 +92,16 @@ Q_QUICK_TEST_EXPORT int quick_test_main(int argc, char **argv, const char *name,
     { \
         QTEST_ADD_GPU_BLACKLIST_SUPPORT \
         QTEST_SET_MAIN_SOURCE_PATH \
-        return quick_test_main(argc, argv, #name, 0); \
+        return quick_test_main(argc, argv, #name, nullptr); \
+    }
+
+#define QUICK_TEST_MAIN_WITH_SETUP(name, QuickTestSetupClass) \
+    int main(int argc, char **argv) \
+    { \
+        QTEST_ADD_GPU_BLACKLIST_SUPPORT \
+        QTEST_SET_MAIN_SOURCE_PATH \
+        QuickTestSetupClass setup; \
+        return quick_test_main_with_setup(argc, argv, #name, nullptr, &setup); \
     }
 
 #endif