summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
Diffstat
-rw-r--r--src/testlib/doc/qttest.qdocconf92
-rw-r--r--src/testlib/doc/snippets/code/doc_src_qsignalspy.cpp (renamed from doc/src/snippets/code/doc_src_qsignalspy.cpp)0
-rw-r--r--src/testlib/doc/snippets/code/doc_src_qtestevent.cpp (renamed from doc/src/snippets/code/doc_src_qtestevent.cpp)0
-rw-r--r--src/testlib/doc/snippets/code/doc_src_qtestlib.cpp88
-rw-r--r--src/testlib/doc/snippets/code/doc_src_qtestlib.pro47
-rw-r--r--src/testlib/doc/snippets/code/doc_src_qtestlib.qdoc87
-rw-r--r--src/testlib/doc/snippets/code/doc_src_qttest.cpp43
-rw-r--r--src/testlib/doc/snippets/code/doc_src_qttest.pro43
-rw-r--r--src/testlib/doc/snippets/code/src_qtestlib_qtestcase.cpp (renamed from doc/src/snippets/code/src_qtestlib_qtestcase.cpp)0
-rw-r--r--src/testlib/doc/src/qttest.qdoc54
-rw-r--r--src/testlib/doc/src/qttestlib-manual.qdoc840
-rw-r--r--src/testlib/qsignalspy.qdoc10
-rw-r--r--src/testlib/qtestcase.cpp54
-rw-r--r--src/testlib/qtestevent.qdoc2
14 files changed, 1327 insertions, 33 deletions
diff --git a/src/testlib/doc/qttest.qdocconf b/src/testlib/doc/qttest.qdocconf
new file mode 100644
index 0000000000..5f9ea96a28
--- /dev/null
+++ b/src/testlib/doc/qttest.qdocconf
@@ -0,0 +1,92 @@
+include(../../../doc/global/qt-cpp-ignore.qdocconf)
+
+project = QtTest
+description = Qt Test Reference Documentation
+url = http://qt-project.org/doc/qt-5.0/qttest
+version = 5.0.0
+
+sourceencoding = UTF-8
+outputencoding = UTF-8
+naturallanguage = en_US
+qhp.projects = QtTest
+
+qhp.QtTest.file = qttest.qhp
+qhp.QtTest.namespace = org.qt-project.qttest.500
+qhp.QtTest.virtualFolder = qdoc
+qhp.QtTest.indexTitle = Qt Test Reference Documentation
+qhp.QtTest.indexRoot =
+
+qhp.QtTest.filterAttributes = qttest 5.0.0 qtrefdoc
+qhp.QtTest.customFilters.Qt.name = QtTest 5.0.0
+qhp.QtTest.customFilters.Qt.filterAttributes = qttest 5.0.0
+qhp.QtTest.subprojects = classes overviews examples
+qhp.QtTest.subprojects.classes.title = Classes
+qhp.QtTest.subprojects.classes.indexTitle = Qt Test's Classes
+qhp.QtTest.subprojects.classes.selectors = class fake:headerfile
+qhp.QtTest.subprojects.classes.sortPages = true
+qhp.QtTest.subprojects.overviews.title = Overviews
+qhp.QtTest.subprojects.overviews.indexTitle = All Overviews and HOWTOs
+qhp.QtTest.subprojects.overviews.selectors = fake:page,group,module
+qhp.QtTest.subprojects.examples.title = Qt Test Examples
+qhp.QtTest.subprojects.examples.indexTitle = Qt Test Examples
+qhp.QtTest.subprojects.examples.selectors = fake:example
+
+dita.metadata.default.author = Qt Project
+dita.metadata.default.permissions = all
+dita.metadata.default.publisher = Qt Project
+dita.metadata.default.copyryear = 2012
+dita.metadata.default.copyrholder = Nokia
+dita.metadata.default.audience = programmer
+
+sources.fileextensions = "*.c++ *.cc *.cpp *.cxx *.mm *.qml *.qdoc"
+headers.fileextensions = "*.ch *.h *.h++ *.hh *.hpp *.hxx"
+
+examples.fileextensions = "*.cpp *.h *.js *.xq *.svg *.xml *.ui *.qhp *.qhcp *.qml *.css"
+examples.imageextensions = "*.png"
+
+outputdir = ../../../doc/qttest
+tagfile = ../../../doc/qttest/qttest.tags
+
+HTML.generatemacrefs = "true"
+HTML.nobreadcrumbs = "true"
+
+HTML.templatedir = .
+
+HTML.stylesheets = ../../../doc/global/style/offline.css
+
+HTML.headerstyles = \
+ " <link rel=\"stylesheet\" type=\"text/css\" href=\"style/offline.css\" />\n"
+
+HTML.endheader = \
+ "</head>\n" \
+
+defines = Q_QDOC \
+ QT_.*_SUPPORT \
+ QT_.*_LIB \
+ QT_COMPAT \
+ QT_KEYPAD_NAVIGATION \
+ QT_NO_EGL \
+ Q_WS_.* \
+ Q_OS_.* \
+ Q_BYTE_ORDER \
+ QT_DEPRECATED \
+ QT_DEPRECATED_* \
+ Q_NO_USING_KEYWORD \
+ __cplusplus \
+ Q_COMPILER_INITIALIZER_LISTS
+
+versionsym = QT_VERSION_STR
+
+codeindent = 1
+
+depends += qtcore
+
+headerdirs += ..
+
+sourcedirs += ..
+
+exampledirs += ../../../examples \
+ ../ \
+ snippets
+
+imagedirs += images
diff --git a/doc/src/snippets/code/doc_src_qsignalspy.cpp b/src/testlib/doc/snippets/code/doc_src_qsignalspy.cpp
index a957285cea..a957285cea 100644
--- a/doc/src/snippets/code/doc_src_qsignalspy.cpp
+++ b/src/testlib/doc/snippets/code/doc_src_qsignalspy.cpp
diff --git a/doc/src/snippets/code/doc_src_qtestevent.cpp b/src/testlib/doc/snippets/code/doc_src_qtestevent.cpp
index 787a8e666b..787a8e666b 100644
--- a/doc/src/snippets/code/doc_src_qtestevent.cpp
+++ b/src/testlib/doc/snippets/code/doc_src_qtestevent.cpp
diff --git a/src/testlib/doc/snippets/code/doc_src_qtestlib.cpp b/src/testlib/doc/snippets/code/doc_src_qtestlib.cpp
new file mode 100644
index 0000000000..8bad7cca48
--- /dev/null
+++ b/src/testlib/doc/snippets/code/doc_src_qtestlib.cpp
@@ -0,0 +1,88 @@
+/****************************************************************************
+**
+** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:BSD$
+** You may use this file under the terms of the BSD license as follows:
+**
+** "Redistribution and use in source and binary forms, with or without
+** modification, are permitted provided that the following conditions are
+** met:
+** * Redistributions of source code must retain the above copyright
+** notice, this list of conditions and the following disclaimer.
+** * Redistributions in binary form must reproduce the above copyright
+** notice, this list of conditions and the following disclaimer in
+** the documentation and/or other materials provided with the
+** distribution.
+** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor
+** the names of its contributors may be used to endorse or promote
+** products derived from this software without specific prior written
+** permission.
+**
+** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+//! [0]
+class MyFirstTest: public QObject
+{
+ Q_OBJECT
+private slots:
+ void initTestCase()
+ { qDebug("called before everything else"); }
+ void myFirstTest()
+ { QVERIFY(1 == 1); }
+ void mySecondTest()
+ { QVERIFY(1 != 2); }
+ void cleanupTestCase()
+ { qDebug("called after myFirstTest and mySecondTest"); }
+};
+//! [0]
+
+
+//! [8]
+void TestQString::toUpper()
+{
+ QString str = "Hello";
+ QVERIFY(str.toUpper() == "HELLO");
+}
+//! [8]
+
+
+//! [11]
+QCOMPARE(QString("hello").toUpper(), QString("HELLO"));
+QCOMPARE(QString("Hello").toUpper(), QString("HELLO"));
+QCOMPARE(QString("HellO").toUpper(), QString("HELLO"));
+QCOMPARE(QString("HELLO").toUpper(), QString("HELLO"));
+//! [11]
+
+//! [12]
+class MyFirstBenchmark: public QObject
+{
+ Q_OBJECT
+private slots:
+ void myFirstBenchmark()
+ {
+ QString string1;
+ QString string2;
+ QBENCHMARK {
+ string1.localeAwareCompare(string2);
+ }
+ }
+};
+//! [12]
diff --git a/src/testlib/doc/snippets/code/doc_src_qtestlib.pro b/src/testlib/doc/snippets/code/doc_src_qtestlib.pro
new file mode 100644
index 0000000000..e6de136bec
--- /dev/null
+++ b/src/testlib/doc/snippets/code/doc_src_qtestlib.pro
@@ -0,0 +1,47 @@
+/****************************************************************************
+**
+** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:BSD$
+** You may use this file under the terms of the BSD license as follows:
+**
+** "Redistribution and use in source and binary forms, with or without
+** modification, are permitted provided that the following conditions are
+** met:
+** * Redistributions of source code must retain the above copyright
+** notice, this list of conditions and the following disclaimer.
+** * Redistributions in binary form must reproduce the above copyright
+** notice, this list of conditions and the following disclaimer in
+** the documentation and/or other materials provided with the
+** distribution.
+** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor
+** the names of its contributors may be used to endorse or promote
+** products derived from this software without specific prior written
+** permission.
+**
+** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+#! [1]
+QT += testlib
+#! [1]
+
+#! [2]
+CONFIG += testcase
+#! [2]
diff --git a/src/testlib/doc/snippets/code/doc_src_qtestlib.qdoc b/src/testlib/doc/snippets/code/doc_src_qtestlib.qdoc
new file mode 100644
index 0000000000..05759b0ccb
--- /dev/null
+++ b/src/testlib/doc/snippets/code/doc_src_qtestlib.qdoc
@@ -0,0 +1,87 @@
+/****************************************************************************
+**
+** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:BSD$
+** You may use this file under the terms of the BSD license as follows:
+**
+** "Redistribution and use in source and binary forms, with or without
+** modification, are permitted provided that the following conditions are
+** met:
+** * Redistributions of source code must retain the above copyright
+** notice, this list of conditions and the following disclaimer.
+** * Redistributions in binary form must reproduce the above copyright
+** notice, this list of conditions and the following disclaimer in
+** the documentation and/or other materials provided with the
+** distribution.
+** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor
+** the names of its contributors may be used to endorse or promote
+** products derived from this software without specific prior written
+** permission.
+**
+** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+//! [2]
+testname [options] [testfunctions[:testdata]]...
+//! [2]
+
+
+//! [3]
+/myTestDirectory$ testQString toUpper
+//! [3]
+
+
+//! [4]
+/myTestDirectory$ testQString toUpper toInt:zero
+//! [4]
+
+
+//! [5]
+/myTestDirectory$ testMyWidget -vs -eventdelay 500
+//! [5]
+
+
+//! [6]
+cetest [options] ...
+//! [6]
+
+
+//! [7]
+set INCLUDE=C:\Program Files\Windows CE Tools\wce500\Windows Mobile 5.0 Pocket PC SDK\Activesync\Inc;%INCLUDE%
+set LIB=C:\Program Files\Windows CE Tools\wce500\Windows Mobile 5.0 Pocket PC SDK\Activesync\Lib;%LIB%
+//! [7]
+
+
+//! [9]
+/myTestDirectory$ qmake -project "QT += testlib"
+/myTestDirectory$ qmake
+/myTestDirectory$ make
+//! [9]
+
+
+//! [10]
+********* Start testing of TestQString *********
+Config: Using QTest library %VERSION%, Qt %VERSION%
+PASS : TestQString::initTestCase()
+PASS : TestQString::toUpper()
+PASS : TestQString::cleanupTestCase()
+Totals: 3 passed, 0 failed, 0 skipped
+********* Finished testing of TestQString *********
+//! [10]
diff --git a/src/testlib/doc/snippets/code/doc_src_qttest.cpp b/src/testlib/doc/snippets/code/doc_src_qttest.cpp
new file mode 100644
index 0000000000..21860fd7c4
--- /dev/null
+++ b/src/testlib/doc/snippets/code/doc_src_qttest.cpp
@@ -0,0 +1,43 @@
+/****************************************************************************
+**
+** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:BSD$
+** You may use this file under the terms of the BSD license as follows:
+**
+** "Redistribution and use in source and binary forms, with or without
+** modification, are permitted provided that the following conditions are
+** met:
+** * Redistributions of source code must retain the above copyright
+** notice, this list of conditions and the following disclaimer.
+** * Redistributions in binary form must reproduce the above copyright
+** notice, this list of conditions and the following disclaimer in
+** the documentation and/or other materials provided with the
+** distribution.
+** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor
+** the names of its contributors may be used to endorse or promote
+** products derived from this software without specific prior written
+** permission.
+**
+** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+//! [0]
+#include <QtTest>
+//! [0]
diff --git a/src/testlib/doc/snippets/code/doc_src_qttest.pro b/src/testlib/doc/snippets/code/doc_src_qttest.pro
new file mode 100644
index 0000000000..15cbfc5694
--- /dev/null
+++ b/src/testlib/doc/snippets/code/doc_src_qttest.pro
@@ -0,0 +1,43 @@
+/****************************************************************************
+**
+** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:BSD$
+** You may use this file under the terms of the BSD license as follows:
+**
+** "Redistribution and use in source and binary forms, with or without
+** modification, are permitted provided that the following conditions are
+** met:
+** * Redistributions of source code must retain the above copyright
+** notice, this list of conditions and the following disclaimer.
+** * Redistributions in binary form must reproduce the above copyright
+** notice, this list of conditions and the following disclaimer in
+** the documentation and/or other materials provided with the
+** distribution.
+** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor
+** the names of its contributors may be used to endorse or promote
+** products derived from this software without specific prior written
+** permission.
+**
+** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+#! [1]
+QT += testlib
+#! [1]
diff --git a/doc/src/snippets/code/src_qtestlib_qtestcase.cpp b/src/testlib/doc/snippets/code/src_qtestlib_qtestcase.cpp
index 2c6565edf5..2c6565edf5 100644
--- a/doc/src/snippets/code/src_qtestlib_qtestcase.cpp
+++ b/src/testlib/doc/snippets/code/src_qtestlib_qtestcase.cpp
diff --git a/src/testlib/doc/src/qttest.qdoc b/src/testlib/doc/src/qttest.qdoc
new file mode 100644
index 0000000000..b1242202a8
--- /dev/null
+++ b/src/testlib/doc/src/qttest.qdoc
@@ -0,0 +1,54 @@
+/****************************************************************************
+**
+** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** GNU Free Documentation License
+** 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.
+**
+** Other Usage
+** Alternatively, this file may be used in accordance with the terms
+** and conditions contained in a signed written agreement between you
+** and Nokia.
+**
+**
+**
+**
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+ \module QtTest
+ \title QtTest Module
+ \ingroup modules
+
+ \keyword QtTest
+
+ \brief The QtTest module provides classes for unit testing Qt applications and libraries.
+
+ Applications that use Qt's unit testing classes need to
+ be configured to be built against the QtTest module.
+ To include the definitions of the module's classes, use the
+ following directive:
+
+ \snippet code/doc_src_qttest.cpp 0
+
+ To link against the module, add this line to your \l qmake \c
+ .pro file:
+
+ \snippet code/doc_src_qttest.pro 1
+
+ See the \l{QTestLib Manual} for a detailed introduction on how to use
+ Qt's unit testing features with your applications.
+
+ The QtTest module is part of all \l{Qt editions}.
+*/
+
diff --git a/src/testlib/doc/src/qttestlib-manual.qdoc b/src/testlib/doc/src/qttestlib-manual.qdoc
new file mode 100644
index 0000000000..06b1ea7861
--- /dev/null
+++ b/src/testlib/doc/src/qttestlib-manual.qdoc
@@ -0,0 +1,840 @@
+/****************************************************************************
+**
+** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** GNU Free Documentation License
+** 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.
+**
+** Other Usage
+** Alternatively, this file may be used in accordance with the terms
+** and conditions contained in a signed written agreement between you
+** and Nokia.
+**
+**
+**
+**
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+ \page qtestlib-manual.html
+ \title QTestLib Manual
+ \brief An overview of Qt's unit testing framework.
+
+ \ingroup frameworks-technologies
+ \ingroup qt-basic-concepts
+
+ \keyword qtestlib
+
+ The QTestLib framework, provided by Nokia, is a tool for unit
+ testing Qt based applications and libraries. QTestLib provides
+ all the functionality commonly found in unit testing frameworks as
+ well as extensions for testing graphical user interfaces.
+
+ \section1 QTestLib Features
+
+ QTestLib is designed to ease the writing of unit tests for Qt
+ based applications and libraries:
+
+ \table
+ \header \li Feature \li Details
+ \row
+ \li \b Lightweight
+ \li QTestLib consists of about 6000 lines of code and 60
+ exported symbols.
+ \row
+ \li \b Self-contained
+ \li QTestLib requires only a few symbols from the Qt Core library
+ for non-gui testing.
+ \row
+ \li \b {Rapid testing}
+ \li QTestLib needs no special test-runners; no special
+ registration for tests.
+ \row
+ \li \b {Data-driven testing}
+ \li A test can be executed multiple times with different test data.
+ \row
+ \li \b {Basic GUI testing}
+ \li QTestLib offers functionality for mouse and keyboard simulation.
+ \row
+ \li \b {Benchmarking}
+ \li QTestLib supports benchmarking and provides several measurement back-ends.
+ \row
+ \li \b {IDE friendly}
+ \li QTestLib outputs messages that can be interpreted by Visual
+ Studio and KDevelop.
+ \row
+ \li \b Thread-safety
+ \li The error reporting is thread safe and atomic.
+ \row
+ \li \b Type-safety
+ \li Extensive use of templates prevent errors introduced by
+ implicit type casting.
+ \row
+ \li \b {Easily extendable}
+ \li Custom types can easily be added to the test data and test output.
+ \endtable
+
+ \note For higher-level GUI and application testing needs, please
+ see the \l{Partner Directory} for Qt testing products provided by
+ Nokia partners.
+
+
+ \section1 QTestLib API
+
+ All public methods are in the \l QTest namespace. In addition, the
+ \l QSignalSpy class provides easy introspection for Qt's signals and slots.
+
+
+ \section1 Using QTestLib
+
+ \section2 Creating a Test
+
+ To create a test, subclass QObject and add one or more private slots to it. Each
+ private slot is a testfunction in your test. QTest::qExec() can be used to execute
+ all testfunctions in the test object.
+
+ In addition, there are four private slots that are \e not treated as testfunctions.
+ They will be executed by the testing framework and can be used to initialize and
+ clean up either the entire test or the current test function.
+
+ \list
+ \li \c{initTestCase()} will be called before the first testfunction is executed.
+ \li \c{cleanupTestCase()} will be called after the last testfunction was executed.
+ \li \c{init()} will be called before each testfunction is executed.
+ \li \c{cleanup()} will be called after every testfunction.
+ \endlist
+
+ If \c{initTestCase()} fails, no testfunction will be executed. If \c{init()} fails,
+ the following testfunction will not be executed, the test will proceed to the next
+ testfunction.
+
+ Example:
+ \snippet code/doc_src_qtestlib.cpp 0
+
+ For more examples, refer to the \l{QTestLib Tutorial}.
+
+ \section2 Building a Test
+
+ If you are using \c qmake as your build tool, just add the
+ following to your project file:
+
+ \snippet code/doc_src_qtestlib.pro 1
+
+ If you would like to run the test via \c{make check}, add the
+ additional line:
+
+ \snippet code/doc_src_qtestlib.pro 2
+
+ See \l{qmake Common Projects#building-a-testcase}{the qmake manual} for
+ more information about \c{make check}.
+
+ If you are using other build tools, make sure that you add the location
+ of the QTestLib header files to your include path (usually \c{include/QtTest}
+ under your Qt installation directory). If you are using a release build
+ of Qt, link your test to the \c QtTest library. For debug builds, use
+ \c{QtTest_debug}.
+
+ See \l {Chapter 1: Writing a Unit Test}{Writing a Unit Test} for a step by
+ step explanation.
+
+ \section2 QTestLib Command Line Arguments
+
+ \section3 Syntax
+
+ The syntax to execute an autotest takes the following simple form:
+
+ \snippet code/doc_src_qtestlib.qdoc 2
+
+ Substitute \c testname with the name of your executable. \c
+ testfunctions can contain names of test functions to be
+ executed. If no \c testfunctions are passed, all tests are run. If you
+ append the name of an entry in \c testdata, the test function will be
+ run only with that test data.
+
+ For example:
+
+ \snippet code/doc_src_qtestlib.qdoc 3
+
+ Runs the test function called \c toUpper with all available test data.
+
+ \snippet code/doc_src_qtestlib.qdoc 4
+
+ Runs the \c toUpper test function with all available test data,
+ and the \c toInt test function with the testdata called \c
+ zero (if the specified test data doesn't exist, the associated test
+ will fail).
+
+ \snippet code/doc_src_qtestlib.qdoc 5
+
+ Runs the testMyWidget function test, outputs every signal
+ emission and waits 500 milliseconds after each simulated
+ mouse/keyboard event.
+
+ \section3 Options
+
+ \section4 Logging Options
+
+ The following command line options determine how test results are reported:
+
+ \list
+ \li \c -o \e{filename,format} \BR
+ write output to the specified file, in the specified format (one of
+ \c txt, \c xml, \c lightxml or \c xunitxml). The special filename \c -
+ may be used to log to standard output.
+ \li \c -o \e filename \BR
+ write output to the specified file.
+ \li \c -txt \BR
+ outputs results in plain text.
+ \li \c -xml \BR
+ outputs results as an XML document.
+ \li \c -lightxml \BR
+ outputs results as a stream of XML tags.
+ \li \c -xunitxml \BR
+ outputs results as an Xunit XML document.
+ \endlist
+
+ The first version of the \c -o option may be repeated in order to log
+ test results in multiple formats, but no more than one instance of this
+ option can log test results to standard output.
+
+ If the first version of the \c -o option is used, neither the second version
+ of the \c -o option nor the \c -txt, \c -xml, \c -lightxml or \c -xunitxml
+ options should be used.
+
+ If neither version of the \c -o option is used, test results will be logged to
+ standard output. If no format option is used, test results will be logged in
+ plain text.
+
+ \section4 Test Log Detail Options
+
+ The following command line options control how much detail is reported
+ in test logs:
+
+ \list
+ \li \c -silent \BR
+ silent output, only shows fatal errors, test failures and minimal status messages.
+ \li \c -v1 \BR
+ verbose output; shows when each test function is entered.
+ (This option only affects plain text output.)
+ \li \c -v2 \BR
+ extended verbose output; shows each \l QCOMPARE() and \l QVERIFY().
+ (This option affects all output formats and implies \c -v1 for plain text output.)
+ \li \c -vs \BR
+ shows every signal that gets emitted and the slot invocations resulting from those signals.
+ (This option affects all output formats.)
+ \endlist
+
+ \section4 Testing Options
+
+ The following command-line options influence how tests are run:
+
+ \list
+ \li \c -functions \BR
+ outputs all test functions available in the test, then quits.
+ \li \c -datatags \BR
+ outputs all data tags available in the test.
+ A global data tag is preceded by ' __global__ '.
+ \li \c -eventdelay \e ms \BR
+ if no delay is specified for keyboard or mouse simulation
+ (\l QTest::keyClick(),
+ \l QTest::mouseClick() etc.), the value from this parameter
+ (in milliseconds) is substituted.
+ \li \c -keydelay \e ms \BR
+ like -eventdelay, but only influences keyboard simulation and not mouse
+ simulation.
+ \li \c -mousedelay \e ms \BR
+ like -eventdelay, but only influences mouse simulation and not keyboard
+ simulation.
+ \li \c -maxwarnings \e number\BR
+ sets the maximum number of warnings to output. 0 for unlimited, defaults to 2000.
+ \li \c -nocrashhandler \BR
+ disables the crash handler on Unix platforms.
+ \endlist
+
+ \section4 Benchmarking Options
+
+ The following command line options control benchmark testing:
+
+ \list
+ \li \c -callgrind \BR
+ use callgrind to time benchmarks (Linux only).
+ \li \c -tickcounter \BR
+ use CPU tick counters to time benchmarks.
+ \li \c -eventcounter \BR
+ counts events received during benchmarks.
+ \li \c -minimumvalue \e n \BR
+ sets the minimum acceptable measurement value.
+ \li \c -iterations \e n \BR
+ sets the number of accumulation iterations.
+ \li \c -median \e n \BR
+ sets the number of median iterations.
+ \li \c -vb \BR
+ output verbose benchmarking information.
+ \endlist
+
+ \section4 Miscellaneous Options
+
+ \list
+ \li \c -help \BR
+ outputs the possible command line arguments and give some useful help.
+ \endlist
+
+ \section2 Creating a Benchmark
+
+ To create a benchmark, follow the instructions for creating a test and then add a
+ QBENCHMARK macro to the test function that you want to benchmark.
+
+ \snippet code/doc_src_qtestlib.cpp 12
+
+ The code inside the QBENCHMARK macro will be measured, and possibly also repeated
+ several times in order to get an accurate measurement. This depends on the selected
+ measurement back-end. Several back-ends are available. They can be selected on the
+ command line:
+
+ \target testlib-benchmarking-measurement
+
+ \table
+ \header \li Name
+ \li Commmand-line Argument
+ \li Availability
+ \row \li Walltime
+ \li (default)
+ \li All platforms
+ \row \li CPU tick counter
+ \li -tickcounter
+ \li Windows, Mac OS X, Linux, many UNIX-like systems.
+ \row \li Valgrind/Callgrind
+ \li -callgrind
+ \li Linux (if installed)
+ \row \li Event Counter
+ \li -eventcounter
+ \li All platforms
+ \endtable
+
+ In short, walltime is always available but requires many repetitions to
+ get a useful result.
+ Tick counters are usually available and can provide
+ results with fewer repetitions, but can be susceptible to CPU frequency
+ scaling issues.
+ Valgrind provides exact results, but does not take
+ I/O waits into account, and is only available on a limited number of
+ platforms.
+ Event counting is available on all platforms and it provides the number of events
+ that were received by the event loop before they are sent to their corresponding
+ targets (this might include non-Qt events).
+
+ \note Depending on the device configuration, Tick counters on the
+ Windows CE platform may not be as fine-grained, compared to other platforms.
+ Devices that do not support high-resolution timers default to
+ one-millisecond granularity.
+
+ See the chapter 5 in the \l{QTestLib Tutorial} for more benchmarking examples.
+
+ \section1 Using QTestLib remotely on Windows CE
+ \c cetest is a convenience application which helps the user to launch an
+ application remotely on a Windows CE device or emulator.
+
+ It needs to be executed after the unit test has been successfully compiled.
+
+ Prior to launching, the following files are copied to the device:
+
+ \list
+ \li all Qt libraries the project links to
+ \li \l {QtRemote}{QtRemote.dll}
+ \li the c runtime library specified during installation
+ \li all files specified in the \c .pro file following the \l DEPLOYMENT rules.
+ \endlist
+
+ \section2 Using \c cetest
+ \section3 Syntax
+ The syntax to execute an autotest takes the following simple form:
+
+ \snippet code/doc_src_qtestlib.qdoc 6
+
+ \section3 Options
+ \c cetest provides the same options as those for unit-testing on non cross-compiled
+ platforms. See \l {QTestLib Command Line Arguments} {Command Line Arguments} for
+ more information.
+
+ The following commands are also included:
+
+ \list
+ \li \c -debug \BR
+ Test version compiled in debug mode.
+ \li \c -release \BR
+ Test version compiled in release mode.
+ \li \c -libpath \e path \BR
+ Target path to copy Qt libraries to.
+ \li \c -qt-delete \BR
+ Delete Qt libraries after execution.
+ \li \c -project-delete \BR
+ Delete project files after execution.
+ \li \c -delete \BR
+ Delete project and Qt libraries after execution.
+ \li \c -conf \BR
+ Specifies a qt.conf file to be deployed to remote directory.
+ \endlist
+
+ \note \c{debug} is the default build option.
+
+ \section2 QtRemote
+ \c QtRemote is a small library which is build after QTestLib. It allows the host
+ system to create a process on a remote device and waits until its execution has
+ been finished.
+
+ \section2 Requirements
+ \c cetest uses Microsoft ActiveSync to establish a remote connection between the
+ host computer and the device. Thus header files and libraries are needed to compile
+ cetest and QtRemote successfully.
+
+ Prior to \l{Installing Qt for Windows CE}{installation} of Qt, you need to set your
+ \c INCLUDE and \c LIB environment variables properly.
+
+ A default installation of Windows Mobile 5 for Pocket PC can be obtained by:
+
+ \snippet code/doc_src_qtestlib.qdoc 7
+
+ Note that Qt will remember the path, so you do not need to set it again
+ after switching the environments for cross-compilation.
+
+ \section1 3rd Party Code
+
+ The CPU tick counters used for benchmarking is licensed under the following
+ license: (from src/testlib/3rdparty/cycle.h)
+
+ \legalese
+ Copyright (c) 2003, 2006 Matteo Frigo\br
+ Copyright (c) 2003, 2006 Massachusetts Institute of Technology
+
+ Permission is hereby granted, free of charge, to any person obtaining
+ a copy of this software and associated documentation files (the
+ "Software"), to deal in the Software without restriction, including
+ without limitation the rights to use, copy, modify, merge, publish,
+ distribute, sublicense, and/or sell copies of the Software, and to
+ permit persons to whom the Software is furnished to do so, subject to
+ the following conditions:
+
+ The above copyright notice and this permission notice shall be
+ included in all copies or substantial portions of the Software.
+
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+ EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+ MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+ NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+ LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+ OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+ WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ \endlegalese
+*/
+
+/*!
+ \page qtestlib-tutorial.html
+ \brief A short introduction to testing with QTestLib.
+ \contentspage QTestLib Manual
+ \nextpage {Chapter 1: Writing a Unit Test}{Chapter 1}
+ \ingroup best-practices
+
+ \title QTestLib Tutorial
+
+ This tutorial gives a short introduction to how to use some of the
+ features of the QTestLib framework. It is divided into five
+ chapters:
+
+ \list 1
+ \li \l {Chapter 1: Writing a Unit Test}{Writing a Unit Test}
+ \li \l {Chapter 2: Data Driven Testing}{Data Driven Testing}
+ \li \l {Chapter 3: Simulating GUI Events}{Simulating GUI Events}
+ \li \l {Chapter 4: Replaying GUI Events}{Replaying GUI Events}
+ \li \l {Chapter 5: Writing a Benchmark}{Writing a Benchmark}
+ \endlist
+
+*/
+
+
+/*!
+ \example qtestlib/tutorial1
+
+ \contentspage {QTestLib Tutorial}{Contents}
+ \nextpage {Chapter 2: Data Driven Testing}{Chapter 2}
+
+ \title Chapter 1: Writing a Unit Test
+
+ In this first chapter we will see how to write a simple unit test
+ for a class, and how to execute it.
+
+ \section1 Writing a Test
+
+ Let's assume you want to test the behavior of our QString class.
+ First, you need a class that contains your test functions. This class
+ has to inherit from QObject:
+
+ \snippet qtestlib/tutorial1/testqstring.cpp 0
+
+ Note that you need to include the QTest header, and that the
+ test functions have to be declared as private slots so the
+ test framework finds and executes it.
+
+ Then you need to implement the test function itself. The
+ implementation could look like this:
+
+ \snippet code/doc_src_qtestlib.cpp 8
+
+ The \l QVERIFY() macro evaluates the expression passed as its
+ argument. If the expression evaluates to true, the execution of
+ the test function continues. Otherwise, a message describing the
+ failure is appended to the test log, and the test function stops
+ executing.
+
+ But if you want a more verbose output to the test log, you should
+ use the \l QCOMPARE() macro instead:
+
+ \snippet qtestlib/tutorial1/testqstring.cpp 1
+
+ If the strings are not equal, the contents of both strings is
+ appended to the test log, making it immediately visible why the
+ comparison failed.
+
+ Finally, to make our test case a stand-alone executable, the
+ following two lines are needed:
+
+ \snippet qtestlib/tutorial1/testqstring.cpp 2
+
+ The \l QTEST_MAIN() macro expands to a simple \c main()
+ method that runs all the test functions. Note that if both the
+ declaration and the implementation of our test class are in a \c
+ .cpp file, we also need to include the generated moc file to make
+ Qt's introspection work.
+
+ \section1 Executing a Test
+
+ Now that we finished writing our test, we want to execute
+ it. Assuming that our test was saved as \c testqstring.cpp in an
+ empty directory: we build the test using qmake to create a project
+ and generate a makefile.
+
+ \snippet code/doc_src_qtestlib.qdoc 9
+
+ \b {Note:}If you're using windows, replace \c make with \c
+ nmake or whatever build tool you use.
+
+ Running the resulting executable should give you the following
+ output:
+
+ \snippet code/doc_src_qtestlib.qdoc 10
+
+ Congratulations! You just wrote and executed your first unit test
+ using the QTestLib framework.
+*/
+
+/*!
+ \example qtestlib/tutorial2
+
+ \previouspage {Chapter 1: Writing a Unit Test}{Chapter 1}
+ \contentspage {QTestLib Tutorial}{Contents}
+ \nextpage {Chapter 3: Simulating Gui Events}{Chapter 3}
+
+ \title Chapter 2: Data Driven Testing
+
+ In this chapter we will demonstrate how to execute a test
+ multiple times with different test data.
+
+ So far, we have hard coded the data we wanted to test into our
+ test function. If we add more test data, the function might look like
+ this:
+
+ \snippet code/doc_src_qtestlib.cpp 11
+
+ To prevent that the function ends up being cluttered by repetitive
+ code, QTestLib supports adding test data to a test function. All
+ we need is to add another private slot to our test class:
+
+ \snippet qtestlib/tutorial2/testqstring.cpp 0
+
+ \section1 Writing the Data Function
+
+ A test function's associated data function carries the same name,
+ appended by \c{_data}. Our data function looks like this:
+
+ \snippet qtestlib/tutorial2/testqstring.cpp 1
+
+ First, we define the two elements of our test table using the \l
+ QTest::addColumn() function: A test string, and the
+ expected result of applying the QString::toUpper() function to
+ that string.
+
+ Then we add some data to the table using the \l
+ QTest::newRow() function. Each set of data will become a
+ separate row in the test table.
+
+ \l QTest::newRow() takes one argument: A name that will be
+ associated with the data set. If the test fails, the name will be
+ used in the test log, referencing the failed data. Then we
+ stream the data set into the new table row: First an arbitrary
+ string, and then the expected result of applying the
+ QString::toUpper() function to that string.
+
+ You can think of the test data as a two-dimensional table. In
+ our case, it has two columns called \c string and \c result and
+ three rows. In addition a name as well as an index is associated
+ with each row:
+
+ \table
+ \header
+ \li index
+ \li name
+ \li string
+ \li result
+ \row
+ \li 0
+ \li all lower
+ \li "hello"
+ \li HELLO
+ \row
+ \li 1
+ \li mixed
+ \li "Hello"
+ \li HELLO
+ \row
+ \li 2
+ \li all upper
+ \li "HELLO"
+ \li HELLO
+ \endtable
+
+ \section1 Rewriting the Test Function
+
+ Our test function can now be rewritten:
+
+ \snippet qtestlib/tutorial2/testqstring.cpp 2
+
+ The TestQString::toUpper() function will be executed three times,
+ once for each entry in the test table that we created in the
+ associated TestQString::toUpper_data() function.
+
+ First, we fetch the two elements of the data set using the \l
+ QFETCH() macro. \l QFETCH() takes two arguments: The data type of
+ the element and the element name. Then we perform the test using
+ the \l QCOMPARE() macro.
+
+ This approach makes it very easy to add new data to the test
+ without modifying the test itself.
+
+ And again, to make our test case a stand-alone executable,
+ the following two lines are needed:
+
+ \snippet qtestlib/tutorial2/testqstring.cpp 3
+
+ As before, the QTEST_MAIN() macro expands to a simple main()
+ method that runs all the test functions, and since both the
+ declaration and the implementation of our test class are in a .cpp
+ file, we also need to include the generated moc file to make Qt's
+ introspection work.
+*/
+
+/*!
+ \example qtestlib/tutorial3
+
+ \previouspage {Chapter 2: Data Driven Testing}{Chapter 2}
+ \contentspage {QTestLib Tutorial}{Contents}
+ \nextpage {Chapter 4: Replaying GUI Events}{Chapter 4}
+
+ \title Chapter 3: Simulating GUI Events
+
+ QTestLib features some mechanisms to test graphical user
+ interfaces. Instead of simulating native window system events,
+ QTestLib sends internal Qt events. That means there are no
+ side-effects on the machine the tests are running on.
+
+ In this chapter we will se how to write a simple GUI test.
+
+ \section1 Writing a GUI test
+
+ This time, let's assume you want to test the behavior of our
+ QLineEdit class. As before, you will need a class that contains
+ your test function:
+
+ \snippet qtestlib/tutorial3/testgui.cpp 0
+
+ The only difference is that you need to include the QtGui class
+ definitions in addition to the QTest namespace.
+
+ \snippet qtestlib/tutorial3/testgui.cpp 1
+
+ In the implementation of the test function we first create a
+ QLineEdit. Then we simulate writing "hello world" in the line edit
+ using the \l QTest::keyClicks() function.
+
+ \note The widget must also be shown in order to correctly test keyboard
+ shortcuts.
+
+ QTest::keyClicks() simulates clicking a sequence of keys on a
+ widget. Optionally, a keyboard modifier can be specified as well
+ as a delay (in milliseconds) of the test after each key click. In
+ a similar way, you can use the QTest::keyClick(),
+ QTest::keyPress(), QTest::keyRelease(), QTest::mouseClick(),
+ QTest::mouseDClick(), QTest::mouseMove(), QTest::mousePress()
+ and QTest::mouseRelease() functions to simulate the associated
+ GUI events.
+
+ Finally, we use the \l QCOMPARE() macro to check if the line edit's
+ text is as expected.
+
+ As before, to make our test case a stand-alone executable, the
+ following two lines are needed:
+
+ \snippet qtestlib/tutorial3/testgui.cpp 2
+
+ The QTEST_MAIN() macro expands to a simple main() method that
+ runs all the test functions, and since both the declaration and
+ the implementation of our test class are in a .cpp file, we also
+ need to include the generated moc file to make Qt's introspection
+ work.
+*/
+
+/*!
+ \example qtestlib/tutorial4
+
+ \previouspage {Chapter 3: Simulating GUI Event}{Chapter 3}
+ \contentspage {QTestLib Tutorial}{Contents}
+ \nextpage {Chapter 5: Writing a Benchmark}{Chapter 5}
+
+ \title Chapter 4: Replaying GUI Events
+
+ In this chapter, we will show how to simulate a GUI event,
+ and how to store a series of GUI events as well as replay them on
+ a widget.
+
+ The approach to storing a series of events and replay them, is
+ quite similar to the approach explained in \l {Chapter 2:
+ Data Driven Testing}{chapter 2}; all you need is to add a data
+ function to your test class:
+
+ \snippet qtestlib/tutorial4/testgui.cpp 0
+
+ \section1 Writing the Data Function
+
+ As before, a test function's associated data function carries the
+ same name, appended by \c{_data}.
+
+ \snippet qtestlib/tutorial4/testgui.cpp 1
+
+ First, we define the elements of the table using the
+ QTest::addColumn() function: A list of GUI events, and the
+ expected result of applying the list of events on a QWidget. Note
+ that the type of the first element is \l QTestEventList.
+
+ A QTestEventList can be populated with GUI events that can be
+ stored as test data for later usage, or be replayed on any
+ QWidget.
+
+ In our current data function, we create two \l
+ {QTestEventList}s. The first list consists of a single click to
+ the 'a' key. We add the event to the list using the
+ QTestEventList::addKeyClick() function. Then we use the
+ QTest::newRow() function to give the data set a name, and
+ stream the event list and the expected result into the table.
+
+ The second list consists of two key clicks: an 'a' with a
+ following 'backspace'. Again we use the
+ QTestEventList::addKeyClick() to add the events to the list, and
+ QTest::newRow() to put the event list and the expected
+ result into the table with an associated name.
+
+ \section1 Rewriting the Test Function
+
+ Our test can now be rewritten:
+
+ \snippet qtestlib/tutorial4/testgui.cpp 2
+
+ The TestGui::testGui() function will be executed two times,
+ once for each entry in the test data that we created in the
+ associated TestGui::testGui_data() function.
+
+ First, we fetch the two elements of the data set using the \l
+ QFETCH() macro. \l QFETCH() takes two arguments: The data type of
+ the element and the element name. Then we create a QLineEdit, and
+ apply the list of events on that widget using the
+ QTestEventList::simulate() function.
+
+ Finally, we use the QCOMPARE() macro to check if the line edit's
+ text is as expected.
+
+ As before, to make our test case a stand-alone executable,
+ the following two lines are needed:
+
+ \snippet qtestlib/tutorial4/testgui.cpp 3
+
+ The QTEST_MAIN() macro expands to a simple main() method that
+ runs all the test functions, and since both the declaration and
+ the implementation of our test class are in a .cpp file, we also
+ need to include the generated moc file to make Qt's introspection
+ work.
+*/
+
+/*!
+ \example qtestlib/tutorial5
+
+ \previouspage {Chapter 4: Replaying GUI Events}{Chapter 4}
+ \contentspage {QTestLib Tutorial}{Contents}
+
+ \title Chapter 5: Writing a Benchmark
+
+ In this final chapter we will demonstrate how to write benchmarks
+ using QTestLib.
+
+ \section1 Writing a Benchmark
+ To create a benchmark we extend a test function with a QBENCHMARK macro.
+ A benchmark test function will then typically consist of setup code and
+ a QBENCHMARK macro that contains the code to be measured. This test
+ function benchmarks QString::localeAwareCompare().
+
+ \snippet qtestlib/tutorial5/benchmarking.cpp 0
+
+ Setup can be done at the beginning of the function, the clock is not
+ running at this point. The code inside the QBENCHMARK macro will be
+ measured, and possibly repeated several times in order to get an
+ accurate measurement.
+
+ Several \l {testlib-benchmarking-measurement}{back-ends} are available
+ and can be selected on the command line.
+
+ \section1 Data Functions
+
+ Data functions are useful for creating benchmarks that compare
+ multiple data inputs, for example locale aware compare against standard
+ compare.
+
+ \snippet qtestlib/tutorial5/benchmarking.cpp 1
+
+ The test function then uses the data to determine what to benchmark.
+
+ \snippet qtestlib/tutorial5/benchmarking.cpp 2
+
+ The "if (useLocaleCompare)" switch is placed outside the QBENCHMARK
+ macro to avoid measuring its overhead. Each benchmark test function
+ can have one active QBENCHMARK macro.
+
+ \section1 External Tools
+
+ Tools for handling and visualizing test data are available as part of
+ the \l {qtestlib-tools} project in the \l{Qt Labs} web site.
+ These include a tool for comparing performance data obtained from test
+ runs and a utility to generate Web-based graphs of performance data.
+
+ See the \l{qtestlib-tools Announcement}{qtestlib-tools announcement}
+ for more information on these tools and a simple graphing example.
+
+*/
+
+
+
diff --git a/src/testlib/qsignalspy.qdoc b/src/testlib/qsignalspy.qdoc
index dddaed74f6..7ce0a51505 100644
--- a/src/testlib/qsignalspy.qdoc
+++ b/src/testlib/qsignalspy.qdoc
@@ -38,7 +38,7 @@
The following example records all signal emissions for the \c clicked() signal
of a QCheckBox:
- \snippet doc/src/snippets/code/doc_src_qsignalspy.cpp 0
+ \snippet code/doc_src_qsignalspy.cpp 0
\c{spy.takeFirst()} returns the arguments for the first emitted signal, as a
list of QVariant objects. The \c clicked() signal has a single bool argument,
@@ -46,17 +46,17 @@
The example below catches a signal from a custom object:
- \snippet doc/src/snippets/code/doc_src_qsignalspy.cpp 1
+ \snippet code/doc_src_qsignalspy.cpp 1
\b {Note:} Non-standard data types need to be registered, using
the qRegisterMetaType() function, before you can create a
QSignalSpy. For example:
- \snippet doc/src/snippets/code/doc_src_qsignalspy.cpp 2
+ \snippet code/doc_src_qsignalspy.cpp 2
To retrieve the \c QModelIndex, you can use qvariant_cast:
- \snippet doc/src/snippets/code/doc_src_qsignalspy.cpp 3
+ \snippet code/doc_src_qsignalspy.cpp 3
*/
/*! \fn QSignalSpy::QSignalSpy(QObject *object, const char *signal)
@@ -69,7 +69,7 @@
return false.
Example:
- \snippet doc/src/snippets/code/doc_src_qsignalspy.cpp 4
+ \snippet code/doc_src_qsignalspy.cpp 4
*/
/*! \fn QSignalSpy::isValid() const
diff --git a/src/testlib/qtestcase.cpp b/src/testlib/qtestcase.cpp
index 245245e1ca..21468f0585 100644
--- a/src/testlib/qtestcase.cpp
+++ b/src/testlib/qtestcase.cpp
@@ -113,7 +113,7 @@ QT_BEGIN_NAMESPACE
by the test framework.
Example:
- \snippet doc/src/snippets/code/src_qtestlib_qtestcase.cpp 0
+ \snippet code/src_qtestlib_qtestcase.cpp 0
\sa QCOMPARE(), QTRY_VERIFY()
*/
@@ -127,7 +127,7 @@ QT_BEGIN_NAMESPACE
C string.
Example:
- \snippet doc/src/snippets/code/src_qtestlib_qtestcase.cpp 1
+ \snippet code/src_qtestlib_qtestcase.cpp 1
\sa QVERIFY(), QCOMPARE()
*/
@@ -160,7 +160,7 @@ QT_BEGIN_NAMESPACE
by the test framework.
Example:
- \snippet doc/src/snippets/code/src_qtestlib_qtestcase.cpp 2
+ \snippet code/src_qtestlib_qtestcase.cpp 2
\sa QVERIFY(), QTRY_COMPARE(), QTest::toString()
*/
@@ -236,12 +236,12 @@ QT_BEGIN_NAMESPACE
Assuming a test has the following data:
- \snippet doc/src/snippets/code/src_qtestlib_qtestcase.cpp 3
+ \snippet code/src_qtestlib_qtestcase.cpp 3
The test data has two elements, a QString called \c aString and an integer
called \c expected. To fetch these values in the actual test:
- \snippet doc/src/snippets/code/src_qtestlib_qtestcase.cpp 4
+ \snippet code/src_qtestlib_qtestcase.cpp 4
\c aString and \c expected are variables on the stack that are initialized with
the current test data.
@@ -271,7 +271,7 @@ QT_BEGIN_NAMESPACE
Example:
- \snippet doc/src/snippets/code/src_qtestlib_qtestcase.cpp 5
+ \snippet code/src_qtestlib_qtestcase.cpp 5
*/
/*! \macro QTEST(actual, testElement)
@@ -286,11 +286,11 @@ QT_BEGIN_NAMESPACE
Instead of writing:
- \snippet doc/src/snippets/code/src_qtestlib_qtestcase.cpp 6
+ \snippet code/src_qtestlib_qtestcase.cpp 6
you can write:
- \snippet doc/src/snippets/code/src_qtestlib_qtestcase.cpp 7
+ \snippet code/src_qtestlib_qtestcase.cpp 7
\sa QCOMPARE()
*/
@@ -320,7 +320,7 @@ QT_BEGIN_NAMESPACE
function that is invoked by the test framework.
Example:
- \snippet doc/src/snippets/code/src_qtestlib_qtestcase.cpp 8
+ \snippet code/src_qtestlib_qtestcase.cpp 8
*/
/*! \macro QEXPECT_FAIL(dataIndex, comment, mode)
@@ -347,7 +347,7 @@ QT_BEGIN_NAMESPACE
by the test framework.
Example 1:
- \snippet doc/src/snippets/code/src_qtestlib_qtestcase.cpp 9
+ \snippet code/src_qtestlib_qtestcase.cpp 9
In the example above, an expected fail will be written into the test output
if the variable \c i is not 42. If the variable \c i is 42, an unexpected pass
@@ -355,7 +355,7 @@ QT_BEGIN_NAMESPACE
statement in the example.
Example 2:
- \snippet doc/src/snippets/code/src_qtestlib_qtestcase.cpp 10
+ \snippet code/src_qtestlib_qtestcase.cpp 10
The above testfunction will not continue executing for the test data
entry \c{data27}.
@@ -391,7 +391,7 @@ QT_BEGIN_NAMESPACE
a warning is printed to the test log.
For example, in this code:
- \snippet doc/src/snippets/code/src_qtestlib_qtestcase.cpp 26
+ \snippet code/src_qtestlib_qtestcase.cpp 26
The testdata file will be resolved as the first existing file from:
@@ -441,7 +441,7 @@ QT_BEGIN_NAMESPACE
\l {QApplication::setNavigationMode()}.
Example:
- \snippet doc/src/snippets/code/src_qtestlib_qtestcase.cpp 11
+ \snippet code/src_qtestlib_qtestcase.cpp 11
\sa QTEST_APPLESS_MAIN(), QTEST_GUILESS_MAIN(), QTest::qExec(),
QApplication::setNavigationMode()
@@ -486,7 +486,7 @@ QT_BEGIN_NAMESPACE
For example:
- \snippet examples/qtestlib/tutorial5/benchmarking.cpp 0
+ \snippet qtestlib/tutorial5/benchmarking.cpp 0
\sa {QTestLib Manual#Creating a Benchmark}{Creating a Benchmark},
{Chapter 5: Writing a Benchmark}{Writing a Benchmark}
@@ -556,7 +556,7 @@ QT_BEGIN_NAMESPACE
before clicking the key.
Example:
- \snippet doc/src/snippets/code/src_qtestlib_qtestcase.cpp 13
+ \snippet code/src_qtestlib_qtestcase.cpp 13
The example above simulates clicking \c a on \c myWidget without
any keyboard modifiers and without delay of the test.
@@ -571,7 +571,7 @@ QT_BEGIN_NAMESPACE
before clicking the key.
Examples:
- \snippet doc/src/snippets/code/src_qtestlib_qtestcase.cpp 14
+ \snippet code/src_qtestlib_qtestcase.cpp 14
The first example above simulates clicking the \c escape key on \c
myWidget without any keyboard modifiers and without delay. The
@@ -650,7 +650,7 @@ QT_BEGIN_NAMESPACE
click.
Example:
- \snippet doc/src/snippets/code/src_qtestlib_qtestcase.cpp 15
+ \snippet code/src_qtestlib_qtestcase.cpp 15
The example above simulates clicking the sequence of keys
representing "hello world" on \c myWidget without any keyboard
@@ -726,7 +726,7 @@ QT_BEGIN_NAMESPACE
Example:
- \snippet doc/src/snippets/code/src_qtestlib_qtestcase.cpp 16
+ \snippet code/src_qtestlib_qtestcase.cpp 16
The example above defines a toString() specialization for a class
called \c MyPoint. Whenever a comparison of two instances of \c
@@ -851,7 +851,7 @@ QT_BEGIN_NAMESPACE
your test will stay responsive to user interface events or network communication.
Example:
- \snippet doc/src/snippets/code/src_qtestlib_qtestcase.cpp 17
+ \snippet code/src_qtestlib_qtestcase.cpp 17
The code above will wait until the network server is responding for a
maximum of about 12.5 seconds.
@@ -867,7 +867,7 @@ QT_BEGIN_NAMESPACE
time after being asked to show itself on the screen. Returns true.
Example:
- \snippet doc/src/snippets/code/src_qtestlib_qtestcase.cpp 24
+ \snippet code/src_qtestlib_qtestcase.cpp 24
*/
/*! \fn bool QTest::qWaitForWindowShown(QWindow *window, int timeout)
@@ -914,7 +914,7 @@ QT_BEGIN_NAMESPACE
instance run out of scope to commit the sequence to the event system.
Example:
- \snippet doc/src/snippets/code/src_qtestlib_qtestcase.cpp 25
+ \snippet code/src_qtestlib_qtestcase.cpp 25
*/
/*!
@@ -2023,7 +2023,7 @@ FatalSignalHandler::~FatalSignalHandler()
The following example will run all tests in \c MyTestObject:
- \snippet doc/src/snippets/code/src_qtestlib_qtestcase.cpp 18
+ \snippet code/src_qtestlib_qtestcase.cpp 18
This function returns 0 if no tests failed, or a value other than 0 if one
or more tests failed or in case of unhandled exceptions. (Skipped tests do
@@ -2237,7 +2237,7 @@ void QTest::qWarn(const char *message, const char *file, int line)
call ignoreMessage() twice, too.
Example:
- \snippet doc/src/snippets/code/src_qtestlib_qtestcase.cpp 19
+ \snippet code/src_qtestlib_qtestcase.cpp 19
The example above tests that QDir::mkdir() outputs the right warning when invoked
with an invalid file name.
@@ -2397,7 +2397,7 @@ void QTest::addColumnInternal(int id, const char *name)
that can be used to stream in data.
Example:
- \snippet doc/src/snippets/code/src_qtestlib_qtestcase.cpp 20
+ \snippet code/src_qtestlib_qtestcase.cpp 20
\b {Note:} This macro can only be used in a test's data function
that is invoked by the test framework.
@@ -2427,7 +2427,7 @@ QTestData &QTest::newRow(const char *dataTag)
\l QFETCH() to fetch the data in the actual test.
Example:
- \snippet doc/src/snippets/code/src_qtestlib_qtestcase.cpp 21
+ \snippet code/src_qtestlib_qtestcase.cpp 21
To add custom types to the testdata, the type must be registered with
QMetaType via \l Q_DECLARE_METATYPE().
@@ -2446,7 +2446,7 @@ QTestData &QTest::newRow(const char *dataTag)
Example:
- \snippet doc/src/snippets/code/src_qtestlib_qtestcase.cpp 22
+ \snippet code/src_qtestlib_qtestcase.cpp 22
*/
const char *QTest::currentTestFunction()
{
@@ -2483,7 +2483,7 @@ bool QTest::currentTestFailed()
qSleep() depends on the operating system.
Example:
- \snippet doc/src/snippets/code/src_qtestlib_qtestcase.cpp 23
+ \snippet code/src_qtestlib_qtestcase.cpp 23
\sa qWait()
*/
diff --git a/src/testlib/qtestevent.qdoc b/src/testlib/qtestevent.qdoc
index d20cfa95d6..b9290045f7 100644
--- a/src/testlib/qtestevent.qdoc
+++ b/src/testlib/qtestevent.qdoc
@@ -39,7 +39,7 @@
QWidget.
Example:
- \snippet doc/src/snippets/code/doc_src_qtestevent.cpp 0
+ \snippet code/doc_src_qtestevent.cpp 0
The example above simulates the user entering the character \c a
followed by a backspace, waiting for 200 milliseconds and
View Lorry Controller Status