14 files changed, 326 insertions, 18 deletions
diff --git a/src/qmltest/doc/qtqmltest.qdocconf b/src/qmltest/doc/qtqmltest.qdocconf
index 2dbe68011e..75099bf15f 100644
--- a/src/qmltest/doc/qtqmltest.qdocconf
+++ b/src/qmltest/doc/qtqmltest.qdocconf
@@ -37,5 +37,5 @@ navigation.landingpage = "Qt Quick Test"
 navigation.cppclassespage = "Qt Quick Test C++ API"
 navigation.qmltypespage = "Qt Quick Test QML Types"
 
-# Fail the documentation build if there are more warnings than the limit
+# Enforce zero documentation warnings
 warninglimit = 0
diff --git a/src/qmltest/doc/snippets/modules_MyModule_CMakeLists.txt b/src/qmltest/doc/snippets/modules_MyModule_CMakeLists.txt
new file mode 100644
index 0000000000..c43434f8d3
--- /dev/null
+++ b/src/qmltest/doc/snippets/modules_MyModule_CMakeLists.txt
@@ -0,0 +1,42 @@
+# Copyright (C) 2022 The Qt Company Ltd.
+# SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause
+
+cmake_minimum_required(VERSION 3.20)
+
+set(MODULE_NAME "SecondPlugin")
+project(${MODULE_NAME} LANGUAGES CXX)
+
+set(CMAKE_AUTOMOC ON)
+set(QT_QML_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR})
+
+find_package(Qt6 REQUIRED COMPONENTS Core Gui Qml Quick)
+
+file(GLOB QML_SOURCES RELATIVE ${CMAKE_CURRENT_SOURCE_DIR} *.qml)
+source_group("Qml Files" FILES ${QML_SOURCES})
+
+# file(GLOB CPP_SOURCES *.cpp)
+# file(GLOB HPP_SOURCES *.h)
+//! [add library]
+qt_add_library(${MyModule} STATIC)
+
+qt6_add_qml_module(${MyModule}
+    URI ${MyModule}
+    VERSION 1.0
+    QML_FILES ${QML_SOURCES}
+    # SOURCES ${CPP_SOURCES} ${HPP_SOURCES}
+)
+//! [add library]
+set_target_properties(${MODULE_NAME} PROPERTIES
+    MACOSX_BUNDLE TRUE
+    WIN32_EXECUTABLE FALSE
+)
+
+
+target_link_libraries(${MODULE_NAME} PRIVATE
+    Qt::Core
+    Qt::Gui
+    Qt::Qml
+    Qt::Quick
+)
+
+target_include_directories(${MODULE_NAME} PUBLIC ${CMAKE_CURRENT_SOURCE_DIR})
diff --git a/src/qmltest/doc/snippets/overview.cmake b/src/qmltest/doc/snippets/overview.cmake
index 4c239b4f9c..11119b0701 100644
--- a/src/qmltest/doc/snippets/overview.cmake
+++ b/src/qmltest/doc/snippets/overview.cmake
@@ -1,5 +1,5 @@
 # Copyright (C) 2022 The Qt Company Ltd.
-# SPDX-License-Identifier: BSD-3-Clause
+# SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause
 
 #! [cmake_use]
 find_package(Qt6 REQUIRED COMPONENTS QuickTest)
diff --git a/src/qmltest/doc/snippets/src_qmltest_qquicktest.cpp b/src/qmltest/doc/snippets/src_qmltest_qquicktest.cpp
index 1486e26696..32e5c984ac 100644
--- a/src/qmltest/doc/snippets/src_qmltest_qquicktest.cpp
+++ b/src/qmltest/doc/snippets/src_qmltest_qquicktest.cpp
@@ -6,6 +6,7 @@
 #include <QtQuickTest>
 #include <QQmlEngine>
 #include <QQmlContext>
+#include <QGuiApplication>
 
 class Setup : public QObject
 {
@@ -15,10 +16,21 @@ public:
     Setup() {}
 
 public slots:
+    void applicationAvailable()
+    {
+        // Initialization that only requires the QGuiApplication object to be available
+    }
+
     void qmlEngineAvailable(QQmlEngine *engine)
     {
+        // Initialization requiring the QQmlEngine to be constructed
         engine->rootContext()->setContextProperty("myContextProperty", QVariant(true));
     }
+
+    void cleanupTestCase()
+    {
+        // Implement custom resource cleanup
+    }
 };
 
 QUICK_TEST_MAIN_WITH_SETUP(mytest, Setup)
diff --git a/src/qmltest/doc/snippets/testApp/CMakeLists.txt b/src/qmltest/doc/snippets/testApp/CMakeLists.txt
new file mode 100644
index 0000000000..cdf7b9555e
--- /dev/null
+++ b/src/qmltest/doc/snippets/testApp/CMakeLists.txt
@@ -0,0 +1,46 @@
+# Copyright (C) 2023 The Qt Company Ltd.
+# SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause
+
+cmake_minimum_required(VERSION 3.20)
+
+project(MyApplication VERSION 0.1 LANGUAGES CXX)
+
+qt_standard_project_setup(REQUIRES 6.6)
+
+find_package(Qt6 COMPONENTS REQUIRED Quick QuickControls2)
+
+#! [project-cmake]
+add_subdirectory(MyModule)
+add_subdirectory(tests)
+
+qt_add_executable(MyApplication
+    src/main.cpp
+)
+
+qt_add_qml_module(MyApplication
+    URI MyApplication
+    QML_FILES main.qml
+)
+#! [project-cmake]
+
+set_target_properties(MyApplication PROPERTIES
+    MACOSX_BUNDLE_GUI_IDENTIFIER my.demoapp.com
+    MACOSX_BUNDLE TRUE
+    WIN32_EXECUTABLE TRUE
+)
+
+target_include_directories(MyApplication
+    PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/src
+)
+
+target_link_libraries(MyApplication
+    PRIVATE
+       Qt6::Quick
+       Qt6::QuickControls2
+       MyModule
+)
+
+install(TARGETS MyApplication
+    BUNDLE DESTINATION .
+    LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR}
+)
diff --git a/src/qmltest/doc/snippets/testApp/MyModule/CMakeLists.txt b/src/qmltest/doc/snippets/testApp/MyModule/CMakeLists.txt
new file mode 100644
index 0000000000..4d293c27d8
--- /dev/null
+++ b/src/qmltest/doc/snippets/testApp/MyModule/CMakeLists.txt
@@ -0,0 +1,32 @@
+# Copyright (C) 2023 The Qt Company Ltd.
+# SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause
+
+cmake_minimum_required(VERSION 3.20)
+
+project(${MODULE_NAME} LANGUAGES CXX)
+
+qt_standard_project_setup(REQUIRES 6.6)
+
+find_package(Qt6 REQUIRED COMPONENTS Core Gui Qml Quick)
+
+#! [add library]
+qt_add_library(MyModule STATIC)
+
+qt6_add_qml_module(MyModule
+    URI MyModule
+    QML_FILES MyButton.qml
+)
+#! [add library]
+
+set_target_properties(MyModule PROPERTIES
+    MACOSX_BUNDLE TRUE
+)
+
+target_link_libraries(MyModule PRIVATE
+    Qt::Core
+    Qt::Gui
+    Qt::Qml
+    Qt::Quick
+)
+
+target_include_directories(MyModule PUBLIC ${CMAKE_CURRENT_SOURCE_DIR})
diff --git a/src/qmltest/doc/snippets/testApp/MyModule/MyButton.qml b/src/qmltest/doc/snippets/testApp/MyModule/MyButton.qml
new file mode 100644
index 0000000000..47e32c3b6c
--- /dev/null
+++ b/src/qmltest/doc/snippets/testApp/MyModule/MyButton.qml
@@ -0,0 +1,12 @@
+// Copyright (C) 2023 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause
+//! [define]
+import QtQuick
+import QtQuick.Controls
+
+Button {
+    width: 50
+    height: 50
+    onClicked: width = 100
+}
+//! [define]
diff --git a/src/qmltest/doc/snippets/testApp/tests/CMakeLists.txt b/src/qmltest/doc/snippets/testApp/tests/CMakeLists.txt
new file mode 100644
index 0000000000..5533403bdc
--- /dev/null
+++ b/src/qmltest/doc/snippets/testApp/tests/CMakeLists.txt
@@ -0,0 +1,29 @@
+# Copyright (C) 2023 The Qt Company Ltd.
+# SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause
+
+cmake_minimum_required(VERSION 3.2)
+
+project(TestMyApplication LANGUAGES CXX)
+
+enable_testing()
+
+find_package(Qt6 REQUIRED COMPONENTS QuickTest Qml)
+
+qt_standard_project_setup(REQUIRES 6.6)
+
+add_definitions(-DQUICK_TEST_SOURCE_DIR="${CMAKE_CURRENT_SOURCE_DIR}")
+
+#! [link against library]
+add_executable(TestMyApplication main.cpp
+               setup.cpp setup.h)
+
+add_test(NAME TestMyApplication COMMAND TestMyApplication)
+
+target_link_libraries(TestMyApplication
+    PRIVATE
+        Qt6::QuickTest
+        Qt6::Qml
+        MyModule
+        MyModuleplugin
+)
+#! [link against library]
diff --git a/src/qmltest/doc/snippets/testApp/tests/main.cpp b/src/qmltest/doc/snippets/testApp/tests/main.cpp
new file mode 100644
index 0000000000..cf68ddb5de
--- /dev/null
+++ b/src/qmltest/doc/snippets/testApp/tests/main.cpp
@@ -0,0 +1,9 @@
+// # Copyright (C) 2023 The Qt Company Ltd.
+// # SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause
+
+//! [main]
+#include <QtQuickTest/quicktest.h>
+#include "setup.h"
+
+QUICK_TEST_MAIN_WITH_SETUP(TestQML, Setup)
+//! [main]
diff --git a/src/qmltest/doc/snippets/testApp/tests/setup.cpp b/src/qmltest/doc/snippets/testApp/tests/setup.cpp
new file mode 100644
index 0000000000..4ecac48d35
--- /dev/null
+++ b/src/qmltest/doc/snippets/testApp/tests/setup.cpp
@@ -0,0 +1,21 @@
+// # Copyright (C) 2023 The Qt Company Ltd.
+// # SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause
+
+//! [setup]
+#include "setup.h"
+
+void Setup::applicationAvailable()
+{
+    // custom code that doesn't require QQmlEngine
+}
+
+void Setup::qmlEngineAvailable(QQmlEngine *engine)
+{
+    // add import paths
+}
+
+void Setup::cleanupTestCase()
+{
+    // custom code to clean up before destruction starts
+}
+//! [setup]
diff --git a/src/qmltest/doc/snippets/testApp/tests/setup.h b/src/qmltest/doc/snippets/testApp/tests/setup.h
new file mode 100644
index 0000000000..ea6a699f2f
--- /dev/null
+++ b/src/qmltest/doc/snippets/testApp/tests/setup.h
@@ -0,0 +1,24 @@
+// # Copyright (C) 2023 The Qt Company Ltd.
+// # SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause
+
+//! [setup]
+#ifndef SETUP_H
+#define SETUP_H
+
+#include <QObject>
+#include <QQmlEngine>
+
+class Setup : public QObject
+{
+    Q_OBJECT
+public:
+    Setup() = default;
+
+public slots:
+    void applicationAvailable();
+    void qmlEngineAvailable(QQmlEngine *engine);
+    void cleanupTestCase();
+};
+
+#endif // SETUP_H
+//! [setup]
diff --git a/src/qmltest/doc/snippets/testApp/tests/tst_testqml.qml b/src/qmltest/doc/snippets/testApp/tests/tst_testqml.qml
new file mode 100644
index 0000000000..5973a31ebb
--- /dev/null
+++ b/src/qmltest/doc/snippets/testApp/tests/tst_testqml.qml
@@ -0,0 +1,31 @@
+// Copyright (C) 2023 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause
+//! [import]
+import QtQuick
+import QtQuick.Controls
+
+import QtTest
+import MyModule
+
+Item {
+    width: 800
+    height: 600
+
+    MyButton {
+        id: myButton
+        anchors.centerIn: parent
+    }
+
+    TestCase {
+        name: "MyButton"
+        when: windowShown
+
+        function test_clickToExpand() {
+            const widthBeforeClick = myButton.width;
+            mouseClick(myButton);
+            const widthAfterClick = myButton.width;
+            verify(widthBeforeClick < widthAfterClick);
+        }
+    }
+}
+//! [import]
diff --git a/src/qmltest/doc/src/qtquicktest-index.qdoc b/src/qmltest/doc/src/qtquicktest-index.qdoc
index d227f44bce..3fa6ccba6f 100644
--- a/src/qmltest/doc/src/qtquicktest-index.qdoc
+++ b/src/qmltest/doc/src/qtquicktest-index.qdoc
@@ -94,16 +94,68 @@
     \snippet src_qmltest_qquicktest_snippet.cpp 1
 
     Where "example" is the identifier to use to uniquely identify
-    this set of tests. Finally, add \c{CONFIG += qmltestcase} to the project
-    file:
+    this set of tests.
+
+    \if defined(onlinedocs)
+        \tab {run-qtquicktest}{tab-cmake}{CMake}{checked}
+        \tab {run-qtquicktest}{tab-qmake}{qmake}{}
+        \tabcontent {tab-cmake}
+    \else
+        \section1 Using CMake
+    \endif
+    Configure your CMakeLists.txt file and build your project using your
+    favorite generator.
+    \badcode
+        cmake_minimum_required(VERSION 3.2)
+
+        project(tst_example LANGUAGES CXX)
+
+        enable_testing()
+
+        find_package(Qt6 REQUIRED COMPONENTS QuickTest Qml)
+
+        #[[The test harness scans the specified source directory recursively
+        for "tst_*.qml" files. By default, it looks in the current directory,
+        which is usually where the executable is. This command makes it look
+        in the project's source directory instead.]]
+        add_definitions(-DQUICK_TEST_SOURCE_DIR="${CMAKE_CURRENT_SOURCE_DIR}")
+
+        qt_standard_project_setup(REQUIRES 6.6)
 
+        add_executable(tst_example tst_example.cpp)
+
+        add_test(NAME tst_example COMMAND tst_example)
+
+        target_link_libraries(tst_example
+            PRIVATE
+            Qt6::QuickTest
+            Qt6::Qml
+        )
+    \endcode
+    \if defined(onlinedocs)
+        \endtabcontent
+        \tabcontent {tab-qmake}
+    \else
+        \section1 Using qmake
+    \endif
+    Add \c{CONFIG += qmltestcase} to your project file:
     \badcode
-    TEMPLATE = app
-    TARGET = tst_example
-    CONFIG += warn_on qmltestcase
-    SOURCES += tst_example.cpp
+        TEMPLATE = app
+        TARGET = tst_example
+        CONFIG += warn_on qmltestcase
+        SOURCES += tst_example.cpp
     \endcode
 
+    If \c IMPORTPATH is specified in your .pro file, each import path added to \c IMPORTPATH
+    will be passed as a command-line argument when the test is run using "make check":
+
+    \badcode
+    IMPORTPATH += $$PWD/../imports/my_module1 $$PWD/../imports/my_module2
+    \endcode
+    \if defined(onlinedocs)
+        \endtabcontent
+    \endif
+
     The test harness scans the specified source directory recursively
     for "tst_*.qml" files. If \c{QUICK_TEST_SOURCE_DIR} is not defined,
     then the current directory will be scanned when the harness is run.
@@ -136,12 +188,6 @@
     If your test case needs QML imports, then you can add them as
     \c{-import} options to the test program command-line.
 
-    If \c IMPORTPATH is specified in your .pro file, each import path added to \c IMPORTPATH
-    will be passed as a command-line argument when the test is run using "make check":
-
-    \badcode
-    IMPORTPATH += $$PWD/../imports/my_module1 $$PWD/../imports/my_module2
-    \endcode
 
     The \c{-functions} command-line option will return a list of the current
     tests functions. It is possible to run a single test function using the name
@@ -157,6 +203,10 @@
     tst_example -help
     \endcode
 
+    \note Running a Qt Quick test case will always show a window on the screen,
+    even if the test code doesn't involve any Quick UI. To avoid that, run the
+    test executable with \c {-platform offscreen}.
+
     \section1 Executing C++ Before QML Tests
 
     To execute C++ code before any of the QML tests are run, the
@@ -164,7 +214,7 @@
     setting context properties on the QML engine, amongst other things.
 
     The macro is identical to \c QUICK_TEST_MAIN, except that it takes an
-    additional \c QObject* argument. The test framework will call slots and
+    additional type argument. The test framework will call slots and
     invokable functions with the following names:
 
     \table
diff --git a/src/qmltest/doc/src/qtquicktest.qdoc b/src/qmltest/doc/src/qtquicktest.qdoc
index 357aa9b524..d349a725f8 100644
--- a/src/qmltest/doc/src/qtquicktest.qdoc
+++ b/src/qmltest/doc/src/qtquicktest.qdoc
@@ -41,9 +41,9 @@
     The \a name argument uniquely identifies this set of tests.
 
     This macro is identical to QUICK_TEST_MAIN(), except that it takes an
-    additional argument \a QuickTestSetupClass, a pointer to a QObject-derived
-    class. With this class it is possible to define additional setup code to
-    execute before running the QML test.
+    additional argument \a QuickTestSetupClass, the type of a QObject-derived
+    class which will be instantiated. With this class it is possible to define
+    additional setup code to execute before running the QML test.
 
     \note The macro assumes that your test sources are in the current
     directory, unless the \c QUICK_TEST_SOURCE_DIR environment variable is set.