--- /dev/null
+/****************************************************************************
+**
+** 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.
+
+*/
+
+
+
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()
*/
C string.
Example:
- \snippet doc/src/snippets/code/src_qtestlib_qtestcase.cpp 1
+ \snippet code/src_qtestlib_qtestcase.cpp 1
\sa QVERIFY(), QCOMPARE()
*/
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()
*/
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.
Example:
- \snippet doc/src/snippets/code/src_qtestlib_qtestcase.cpp 5
+ \snippet code/src_qtestlib_qtestcase.cpp 5
*/
/*! \macro QTEST(actual, testElement)
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()
*/
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)
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
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}.
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:
\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()
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}
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.
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
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
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
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.
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)
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
*/
/*!
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
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.
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.
\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().
Example:
- \snippet doc/src/snippets/code/src_qtestlib_qtestcase.cpp 22
+ \snippet code/src_qtestlib_qtestcase.cpp 22
*/
const char *QTest::currentTestFunction()
{
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()
*/
projects / profile / ivi / qtbase.git / commitdiff