doc/src/declarative/qmltest.qdoc

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