doc/src/declarative/qmltest.qdoc

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).
   4 ** All rights reserved.
   5 ** Contact: Nokia Corporation (qt-info@nokia.com)
   6 **
   7 ** This file is part of the documentation of the Qt Toolkit.
   8 **
   9 ** $QT_BEGIN_LICENSE:FDL$
  10 ** GNU Free Documentation License
  11 ** Alternatively, this file may be used under the terms of the GNU Free
  12 ** Documentation License version 1.3 as published by the Free Software
  13 ** Foundation and appearing in the file included in the packaging of
  14 ** this file.
  15 **
  16 ** Other Usage
  17 ** Alternatively, this file may be used in accordance with the terms
  18 ** and conditions contained in a signed written agreement between you
  19 ** and Nokia.
  20 **
  21 **
  22 **
  23 **
  24 ** $QT_END_LICENSE$
  25 **
  26 ****************************************************************************/
  27
  28 /*!
  29     \page qmltest.html
  30     \title QtQuickTest Reference Documentation
  31     \keyword QtQuickTest Reference Documentation
  32
  33     \section1 Introduction
  34
  35     QtQuickTest is a unit test framework for Qt Quick (QML) applications.
  36     Test cases are written as JavaScript functions within a TestCase
  37     element:
  38
  39     \code
  40     import QtQuick 2.0
  41     import QtTest 1.0
  42
  43     TestCase {
  44         name: "MathTests"
  45
  46         function test_math() {
  47             compare(2 + 2, 4, "2 + 2 = 4")
  48         }
  49
  50         function test_fail() {
  51             compare(2 + 2, 5, "2 + 2 = 5")
  52         }
  53     }
  54     \endcode
  55
  56     Functions whose names start with \c{test_} are treated as test cases
  57     to be executed.  See the documentation for the \l TestCase and
  58     \l SignalSpy elements for more information on writing test cases.
  59
  60     \section1 Running tests
  61
  62     Test cases are launched by a C++ harness that consists of
  63     the following code:
  64
  65     \code
  66     #include <QtQuickTest/quicktest.h>
  67     QUICK_TEST_MAIN(example)
  68     \endcode
  69
  70     Where "example" is an identifier to use to uniquely identify
  71     this set of tests.  You should add \c{CONFIG += qmltestcase}.
  72     for example:
  73
  74     \code
  75     TEMPLATE = app
  76     TARGET = tst_example
  77     CONFIG += warn_on qmltestcase
  78     SOURCES += tst_example.cpp
  79     \endcode
  80
  81     The test harness scans the specified source directory recursively
  82     for "tst_*.qml" files.  If \c{QUICK_TEST_SOURCE_DIR} is not defined,
  83     then the current directory will be scanned when the harness is run.
  84     Other *.qml files may appear for auxillary QML components that are
  85     used by the test.
  86
  87     The \c{-input} command-line option can be set at runtime to run
  88     test cases from a different directory.  This may be needed to run
  89     tests on a target device where the compiled-in directory name refers
  90     to a host.  For example:
  91
  92     \code
  93     tst_example -input /mnt/SDCard/qmltests
  94     \endcode
  95
  96     See \c{tests/qmlauto} in the source tree for an example of creating a
  97     test harness that uses the \c{QUICK_TEST_SOURCE_DIR} macro.
  98
  99     If your test case needs QML imports, then you can add them as
 100     \c{-import} options to the the test program command-line by adding
 101     the following line to your .pro file:
 102
 103     \code
 104     IMPORTPATH += $$PWD/../imports/my_module1 $$PWD/../imports/my_module2
 105     \endcode
 106
 107     \section1 Running tests with QtQuick 1
 108
 109     The \c{-qtquick1} option can be passed to a test binary to run
 110     the tests using QDeclarativeView (QtQuick 1) rather than QSGView (QtQuick 2):
 111
 112     \code
 113     tst_example -qtquick1
 114     \endcode
 115
 116     To run tests with either QtQuick 1 or QtQuick 2, use
 117     "import QtQuick 1.0" in your unit tests and then specify
 118     compatibility mode to the QtQuick2 engine:
 119
 120     \code
 121     QMLSCENE_IMPORT_NAME=quick1 tst_example
 122     \endcode
 123 */