diff options
Diffstat (limited to 'src/testlib/doc')
| -rw-r--r-- | src/testlib/doc/qttest.qdocconf | 92 | ||||
| -rw-r--r-- | src/testlib/doc/snippets/code/doc_src_qsignalspy.cpp | 81 | ||||
| -rw-r--r-- | src/testlib/doc/snippets/code/doc_src_qtestevent.cpp | 51 | ||||
| -rw-r--r-- | src/testlib/doc/snippets/code/doc_src_qtestlib.cpp | 88 | ||||
| -rw-r--r-- | src/testlib/doc/snippets/code/doc_src_qtestlib.pro | 7 | ||||
| -rw-r--r-- | src/testlib/doc/snippets/code/doc_src_qtestlib.qdoc | 87 | ||||
| -rw-r--r-- | src/testlib/doc/snippets/code/doc_src_qttest.cpp | 43 | ||||
| -rw-r--r-- | src/testlib/doc/snippets/code/doc_src_qttest.pro | 3 | ||||
| -rw-r--r-- | src/testlib/doc/snippets/code/src_qtestlib_qtestcase.cpp | 250 | ||||
| -rw-r--r-- | src/testlib/doc/src/qttest.qdoc | 54 | ||||
| -rw-r--r-- | src/testlib/doc/src/qttestlib-manual.qdoc | 840 |
11 files changed, 1596 insertions, 0 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/src/testlib/doc/snippets/code/doc_src_qsignalspy.cpp b/src/testlib/doc/snippets/code/doc_src_qsignalspy.cpp new file mode 100644 index 0000000000..a957285cea --- /dev/null +++ b/src/testlib/doc/snippets/code/doc_src_qsignalspy.cpp @@ -0,0 +1,81 @@ +/**************************************************************************** +** +** 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] +QCheckBox *box = ...; +QSignalSpy spy(box, SIGNAL(clicked(bool))); + +// do something that triggers the signal +box->animateClick(); + +QCOMPARE(spy.count(), 1); // make sure the signal was emitted exactly one time +QList<QVariant> arguments = spy.takeFirst(); // take the first signal + +QVERIFY(arguments.at(0).toBool() == true); // verify the first argument +//! [0] + + +//! [1] +QSignalSpy spy(myCustomObject, SIGNAL(mySignal(int, QString, double))); + +myCustomObject->doSomething(); // trigger emission of the signal + +QList<QVariant> arguments = spy.takeFirst(); +QVERIFY(arguments.at(0).type() == QVariant::Int); +QVERIFY(arguments.at(1).type() == QVariant::QString); +QVERIFY(arguments.at(2).type() == QVariant::double); +//! [1] + + +//! [2] +qRegisterMetaType<QModelIndex>("QModelIndex"); +QSignalSpy spy(&model, SIGNAL(whatever(QModelIndex))); +//! [2] + + +//! [3] +// get the first argument from the first received signal: +QModelIndex result = qvariant_cast<QModelIndex>(spy.at(0).at(0)); +//! [3] + + +//! [4] +QSignalSpy spy(myPushButton, SIGNAL(clicked(bool))); +//! [4] diff --git a/src/testlib/doc/snippets/code/doc_src_qtestevent.cpp b/src/testlib/doc/snippets/code/doc_src_qtestevent.cpp new file mode 100644 index 0000000000..787a8e666b --- /dev/null +++ b/src/testlib/doc/snippets/code/doc_src_qtestevent.cpp @@ -0,0 +1,51 @@ +/**************************************************************************** +** +** 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] +QTestEventList events; +events.addKeyClick('a'); +events.addKeyClick(Qt::Key_Backspace); +events.addDelay(200); + +QLineEdit *lineEdit = new QLineEdit(myParent); +... +events.simulate(lineEdit); +events.simulate(lineEdit); +//! [0] 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..c514d26075 --- /dev/null +++ b/src/testlib/doc/snippets/code/doc_src_qtestlib.pro @@ -0,0 +1,7 @@ +#! [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..62b8fb064c --- /dev/null +++ b/src/testlib/doc/snippets/code/doc_src_qttest.pro @@ -0,0 +1,3 @@ +#! [1] +QT += testlib +#! [1] diff --git a/src/testlib/doc/snippets/code/src_qtestlib_qtestcase.cpp b/src/testlib/doc/snippets/code/src_qtestlib_qtestcase.cpp new file mode 100644 index 0000000000..2c6565edf5 --- /dev/null +++ b/src/testlib/doc/snippets/code/src_qtestlib_qtestcase.cpp @@ -0,0 +1,250 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ + + +void wrapInFunction() +{ + +//! [0] +QVERIFY(1 + 1 == 2); +//! [0] + + +//! [1] +QVERIFY2(1 + 1 == 2, "A breach in basic arithmetic occurred."); +//! [1] + + +//! [2] +QCOMPARE(QString("hello").toUpper(), QString("HELLO")); +//! [2] + + +//! [3] +void TestQString::toInt_data() +{ + QTest::addColumn<QString>("aString"); + QTest::addColumn<int>("expected"); + + QTest::newRow("positive value") << "42" << 42; + QTest::newRow("negative value") << "-42" << -42; + QTest::newRow("zero") << "0" << 0; +} +//! [3] + + +//! [4] +void TestQString::toInt() +{ + QFETCH(QString, aString); + QFETCH(int, expected); + + QCOMPARE(aString.toInt(), expected); +} +//! [4] + + +//! [5] +if (sizeof(int) != 4) + QFAIL("This test has not been ported to this platform yet."); +//! [5] + + +//! [6] +QFETCH(QString, myString); +QCOMPARE(QString("hello").toUpper(), myString); +//! [6] + + +//! [7] +QTEST(QString("hello").toUpper(), "myString"); +//! [7] + + +//! [8] +if (!QSqlDatabase::drivers().contains("SQLITE")) + QSKIP("This test requires the SQLITE database driver"); +//! [8] + + +//! [9] +QEXPECT_FAIL("", "Will fix in the next release", Continue); +QCOMPARE(i, 42); +QCOMPARE(j, 43); +//! [9] + + +//! [10] +QEXPECT_FAIL("data27", "Oh my, this is soooo broken", Abort); +QCOMPARE(i, 42); +//! [10] + + +//! [11] +class TestQString: public QObject { ... }; +QTEST_MAIN(TestQString) +//! [11] + + +//! [13] +QTest::keyClick(myWidget, 'a'); +//! [13] + + +//! [14] +QTest::keyClick(myWidget, Qt::Key_Escape); + +QTest::keyClick(myWidget, Qt::Key_Escape, Qt::ShiftModifier, 200); +//! [14] + + +//! [15] +QTest::keyClicks(myWidget, "hello world"); +//! [15] + + +//! [16] +namespace QTest { + template<> + char *toString(const MyPoint &point) + { + QByteArray ba = "MyPoint("; + ba += QByteArray::number(point.x()) + ", " + QByteArray::number(point.y()); + ba += ")"; + return qstrdup(ba.data()); + } +} +//! [16] + + +//! [17] +int i = 0; +while (myNetworkServerNotResponding() && i++ < 50) + QTest::qWait(250); +//! [17] + + +//! [18] +MyTestObject test1; +QTest::qExec(&test1); +//! [18] + + +//! [19] +QDir dir; + +QTest::ignoreMessage(QtWarningMsg, "QDir::mkdir: Empty or null file name(s)"); +dir.mkdir(""); +//! [19] + + +//! [20] +void myTestFunction_data() +{ + QTest::addColumn<QString>("aString"); + QTest::newRow("just hello") << QString("hello"); + QTest::newRow("a null string") << QString(); +} +//! [20] + + +//! [21] +void myTestFunction_data() { + QTest::addColumn<int>("intval"); + QTest::addColumn<QString>("str"); + QTest::addColumn<double>("dbl"); + + QTest::newRow("row1") << 1 << "hello" << 1.5; +} +//! [21] + + +//! [22] +void MyTestClass::cleanup() +{ + if (qstrcmp(currentTestFunction(), "myDatabaseTest") == 0) { + // clean up all database connections + closeAllDatabases(); + } +} +//! [22] + + +//! [23] +QTest::qSleep(250); +//! [23] + +//! [24] +QWidget widget; +widget.show(); +QTest::qWaitForWindowShown(&widget); +//! [24] + +//! [25] +QWidget widget; + +QTest::touchEvent(&widget) + .press(0, QPoint(10, 10)); +QTest::touchEvent(&widget) + .stationary(0) + .press(1, QPoint(40, 10)); +QTest::touchEvent(&widget) + .move(0, QPoint(12, 12)) + .move(1, QPoint(45, 5)); +QTest::touchEvent(&widget) + .release(0) + .release(1); +//! [25] + + +//! [26] +// Source: /home/user/sources/myxmlparser/tests/tst_myxmlparser/tst_myxmlparser.cpp +// Build: /home/user/build/myxmlparser/tests/tst_myxmlparser +// Qt: /usr/local/Qt-5.0.0 +void tst_MyXmlParser::parse() +{ + MyXmlParser parser; + QString input = QFINDTESTDATA("testxml/simple1.xml"); + QVERIFY(parser.parse(input)); +} +//! [26] + +} + 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. + +*/ + + + |