diff options
Diffstat (limited to 'src/qmltest/doc/src/qtquicktest-index.qdoc')
| -rw-r--r-- | src/qmltest/doc/src/qtquicktest-index.qdoc | 198 |
1 files changed, 127 insertions, 71 deletions
diff --git a/src/qmltest/doc/src/qtquicktest-index.qdoc b/src/qmltest/doc/src/qtquicktest-index.qdoc index 4fad21e080..3fa6ccba6f 100644 --- a/src/qmltest/doc/src/qtquicktest-index.qdoc +++ b/src/qmltest/doc/src/qtquicktest-index.qdoc @@ -1,35 +1,12 @@ -/**************************************************************************** -** -** Copyright (C) 2018 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** 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 Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2018 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! \page qtquicktest-index.html \title Qt Quick Test \brief Unit testing framework for QML. + \target Introduction to Qt Quick Test \section1 Introduction \l {Qt Quick Test QML Types}{Qt Quick Test} is a unit test framework for QML applications. @@ -62,26 +39,122 @@ only guaranteed to work with the Qt version it was developed against. However, source compatibility is guaranteed. + \section1 Using the Module + + \section2 QML API + + The QML types in Qt Quick Test are available through the \c QtTest import. + To use the types, add the following import statement to your .qml file: + + \qml + import QtTest + \endqml + + \section2 C++ API + + Using the \l{Qt Quick Test C++ API}{C++ API} requires linking against the + module library, either directly or through other dependencies. Several + build tools have dedicated support for this, including + \l{CMake Documentation}{CMake} and \l{qmake}. + + \section3 Building with CMake + + Use the \c find_package() command to locate the needed module components in + the Qt6 package: + + \snippet overview.cmake cmake_use + + See also the \l{Build with CMake} overview. + + \section3 Building with qmake + + There are two ways to link against the corresponding C++ library. If your + test project uses a QML \l TestCase, you should already have the following + line in your project file: + + \badcode + CONFIG += qmltestcase + \endcode + + This will cause the test to link to the C++ \QtQuickTest library. + + If you have a C++-only test project, you can add the following line + to your project file: + + \badcode + QT += qmltest + \endcode + + \target Running Qt Quick Tests \section1 Running Tests Test cases are launched by a C++ harness that consists of the following code: - \code - #include <QtQuickTest/quicktest.h> - QUICK_TEST_MAIN(example) - \endcode + \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 + \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 - TEMPLATE = app - TARGET = tst_example - CONFIG += warn_on qmltestcase - SOURCES += tst_example.cpp + 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, @@ -115,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 @@ -136,14 +203,18 @@ 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 - \c QUICK_TEST_MAIN_WITH_SETUP macro can be used. This can be useful for + \l 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 \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 @@ -152,13 +223,13 @@ \li Purpose \li Since \row - \li void applicationAvailable() + \li \c {void applicationAvailable()} \li Called right after the QApplication object was instantiated. Use this function to perform setup that does not require a \l QQmlEngine instance. \li Qt 5.12 \row - \li void qmlEngineAvailable(QQmlEngine*) + \li \c {void qmlEngineAvailable(QQmlEngine *)} \li Called when the QML engine is available. Any \l {QQmlEngine::addImportPath}{import paths}, \l {QQmlEngine::addPluginPath}{plugin paths}, @@ -175,7 +246,7 @@ amongst other things. \li Qt 5.11 \row - \li void cleanupTestCase() + \li \c {void cleanupTestCase()} \li Called right after the test execution has finished. Use this function to clean up before everything will start to be destructed. \li Qt 5.12 @@ -184,39 +255,24 @@ 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 - { - Q_OBJECT - - 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 + \snippet src_qmltest_qquicktest.cpp 2 The \c .moc include is based on the file name of the \c .cpp file. For example, in the example above, the \c .cpp file is named - \c tst_mytest.cpp. If the file was named \c MyTest.cpp, the include would + \c src_qmltest_qquicktest.cpp. If the file was named \c MyTest.cpp, the include would be: \code #include "MyTest.moc" \endcode + \section1 Reference + + \list + \li \l{Qt Quick Test QML Types}{QML Types} + \li \l{Qt Quick Test C++ API}{C++ API} + \endlist + \section1 Licenses Qt Quick Tests is available under commercial licenses from \l{The Qt Company}. |