1// Copyright (C) 2018 The Qt Company Ltd.
2// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
5 \page qtquicktest-index.html
7 \brief Unit testing framework for QML.
9 \target Introduction to Qt Quick Test
10 \section1 Introduction
12 \l {Qt Quick Test QML Types}{Qt Quick Test} is a unit test framework for QML applications.
13 Test cases are written as JavaScript functions within a \l [QML] TestCase
23 function test_math() {
24 compare(2 + 2, 4, "2 + 2 = 4")
27 function test_fail() {
28 compare(2 + 2, 5, "2 + 2 = 5")
33 Functions whose names start with \c{test_} are treated as test cases
34 to be executed. See the documentation for the \l [QML] TestCase and
35 \l [QML] SignalSpy types for more information on writing test cases.
37 \note There is no binary compatibility guarantee for the Qt Quick Test
38 module. This means that an application that uses Qt Quick Test is
39 only guaranteed to work with the Qt version it was developed against.
40 However, source compatibility is guaranteed.
42 \section1 Using the Module
46 The QML types in Qt Quick Test are available through the \c QtTest import.
47 To use the types, add the following import statement to your .qml file:
55 Using the \l{Qt Quick Test C++ API}{C++ API} requires linking against the
56 module library, either directly or through other dependencies. Several
57 build tools have dedicated support for this, including
58 \l{CMake Documentation}{CMake} and \l{qmake}.
60 \section3 Building with CMake
62 Use the \c find_package() command to locate the needed module components in
65 \snippet overview.cmake cmake_use
67 See also the \l{Build with CMake} overview.
69 \section3 Building with qmake
71 There are two ways to link against the corresponding C++ library. If your
72 test project uses a QML \l TestCase, you should already have the following
73 line in your project file:
79 This will cause the test to link to the C++ \QtQuickTest library.
81 If you have a C++-only test project, you can add the following line
88 \target Running Qt Quick Tests
89 \section1 Running Tests
91 Test cases are launched by a C++ harness that consists of
94 \snippet src_qmltest_qquicktest_snippet.cpp 1
96 Where "example" is the identifier to use to uniquely identify
99 \if defined(onlinedocs)
100 \tab {run-qtquicktest}{tab-cmake}{CMake}{checked}
101 \tab {run-qtquicktest}{tab-qmake}{qmake}{}
102 \tabcontent {tab-cmake}
104 \section1 Using CMake
106 Configure your CMakeLists.txt file and build your project using your
109 cmake_minimum_required(VERSION 3.2)
111 project(tst_example LANGUAGES CXX)
115 find_package(Qt6 REQUIRED COMPONENTS QuickTest Qml)
117 #[[The test harness scans the specified source directory recursively
118 for "tst_*.qml" files. By default, it looks in the current directory,
119 which is usually where the executable is. This command makes it look
120 in the project's source directory instead.]]
121 add_definitions(-DQUICK_TEST_SOURCE_DIR="${CMAKE_CURRENT_SOURCE_DIR}")
123 qt_standard_project_setup(REQUIRES 6.6)
125 add_executable(tst_example tst_example.cpp)
127 add_test(NAME tst_example COMMAND tst_example)
129 target_link_libraries(tst_example
135 \if defined(onlinedocs)
137 \tabcontent {tab-qmake}
139 \section1 Using qmake
141 Add \c{CONFIG += qmltestcase} to your project file:
145 CONFIG += warn_on qmltestcase
146 SOURCES += tst_example.cpp
149 If \c IMPORTPATH is specified in your .pro file, each import path added to \c IMPORTPATH
150 will be passed as a command-line argument when the test is run using "make check":
153 IMPORTPATH += $$PWD/../imports/my_module1 $$PWD/../imports/my_module2
155 \if defined(onlinedocs)
159 The test harness scans the specified source directory recursively
160 for "tst_*.qml" files. If \c{QUICK_TEST_SOURCE_DIR} is not defined,
161 then the current directory will be scanned when the harness is run.
162 Other *.qml files may appear for auxillary QML components that are
165 The \c{-input} command-line option can be set at runtime to run
166 test cases from a different directory. This may be needed to run
167 tests on a target device where the compiled-in directory name refers
168 to a host. For example:
171 tst_example -input /mnt/SDCard/qmltests
174 It is also possible to run a single file using the \c{-input} option.
178 tst_example -input data/test.qml
182 tst_example -input <full_path>/test.qml
185 \note Specifying the full path to the qml test file is for example
186 needed for shadow builds.
188 If your test case needs QML imports, then you can add them as
189 \c{-import} options to the test program command-line.
192 The \c{-functions} command-line option will return a list of the current
193 tests functions. It is possible to run a single test function using the name
194 of the test function as an argument. For example:
197 tst_example Test_Name::function1
200 The \c{-help} command-line option will return all the options available.
206 \note Running a Qt Quick test case will always show a window on the screen,
207 even if the test code doesn't involve any Quick UI. To avoid that, run the
208 test executable with \c {-platform offscreen}.
210 \section1 Executing C++ Before QML Tests
212 To execute C++ code before any of the QML tests are run, the
213 \l QUICK_TEST_MAIN_WITH_SETUP macro can be used. This can be useful for
214 setting context properties on the QML engine, amongst other things.
216 The macro is identical to \c QUICK_TEST_MAIN, except that it takes an
217 additional type argument. The test framework will call slots and
218 invokable functions with the following names:
226 \li \c {void applicationAvailable()}
227 \li Called right after the QApplication object was instantiated.
228 Use this function to perform setup that does not require a
229 \l QQmlEngine instance.
232 \li \c {void qmlEngineAvailable(QQmlEngine *)}
233 \li Called when the QML engine is available.
234 Any \l {QQmlEngine::addImportPath}{import paths},
235 \l {QQmlEngine::addPluginPath}{plugin paths},
236 and \l {QQmlFileSelector::setExtraSelectors}{extra file selectors}
237 will have been set on the engine by this point.
239 This function is called once for each QML test file,
240 so any arguments are unique to that test. For example, this
241 means that each QML test file will have its own QML engine.
243 This function can be used to \l {Choosing the Correct Integration
244 Method Between C++ and QML}{register QML types} and
245 \l {QQmlEngine::addImportPath()}{add import paths},
246 amongst other things.
249 \li \c {void cleanupTestCase()}
250 \li Called right after the test execution has finished.
251 Use this function to clean up before everything will start to be destructed.
255 The following example demonstrates how the macro can be used to set context
256 properties on the QML engine:
258 \snippet src_qmltest_qquicktest.cpp 2
260 The \c .moc include is based on the file name of the \c .cpp file.
261 For example, in the example above, the \c .cpp file is named
262 \c src_qmltest_qquicktest.cpp. If the file was named \c MyTest.cpp, the include would
266 #include "MyTest.moc"
272 \li \l{Qt Quick Test QML Types}{QML Types}
273 \li \l{Qt Quick Test C++ API}{C++ API}
278 Qt Quick Tests is available under commercial licenses from \l{The Qt Company}.
279 In addition, it is available under free software licenses. Since Qt 5.4,
280 these free software licenses are
281 \l{GNU Lesser General Public License, version 3}, or
282 the \l{GNU General Public License, version 2}.
283 See \l{Qt Licensing} for further details.