Testlib: Move documentation from qtestcase.cpp to qtestcase.qdoc.

Previously, one had to skip  1300 lines of documentation before
seeing the actual code in this file.

Task-number: QTBUG-38890
Change-Id: I5a375cbe6b62575f6040e952a0931ac8ea2dd557
Reviewed-by: Frederik Gladhorn <frederik.gladhorn@theqtcompany.com>

2 files changed, 1283 insertions, 1255 deletions

diff --git a/src/testlib/qtestcase.cpp b/src/testlib/qtestcase.cpp
index f5f399978e..63c01fc017 100644
--- a/src/testlib/qtestcase.cpp
+++ b/src/testlib/qtestcase.cpp
@@ -136,1261 +136,6 @@ static void stackTrace()
 #endif
 }
 
-/*!
-   \namespace QTest
-   \inmodule QtTest
-
-   \brief The QTest namespace contains all the functions and
-   declarations that are related to Qt Test.
-
-   See the \l{Qt Test Overview} for information about how to write unit tests.
-*/
-
-/*!
-   \namespace QTest::Internal
-   \internal
-*/
-
-/*! \macro QVERIFY(condition)
-
-   \relates QTest
-
-   The QVERIFY() macro checks whether the \a condition is true or not. If it is
-   true, execution continues. If not, a failure is recorded in the test log
-   and the test won't be executed further.
-
-   \b {Note:} This macro can only be used in a test function that is invoked
-   by the test framework.
-
-   Example:
-   \snippet code/src_qtestlib_qtestcase.cpp 0
-
-   \sa QCOMPARE(), QTRY_VERIFY()
-*/
-
-/*! \macro QVERIFY2(condition, message)
-
-    \relates QTest
-
-    The QVERIFY2() macro behaves exactly like QVERIFY(), except that it outputs
-    a verbose \a message when \a condition is false. The \a message is a plain
-    C string.
-
-    Example:
-    \snippet code/src_qtestlib_qtestcase.cpp 1
-
-    \sa QVERIFY(), QCOMPARE()
-*/
-
-/*! \macro QCOMPARE(actual, expected)
-
-   \relates QTest
-
-   The QCOMPARE macro compares an \a actual value to an \a expected value using
-   the equals operator. If \a actual and \a expected are identical, execution
-   continues. If not, a failure is recorded in the test log and the test
-   won't be executed further.
-
-   In the case of comparing floats and doubles, qFuzzyCompare() is used for
-   comparing. This means that comparing to 0 will likely fail. One solution
-   to this is to compare to 1, and add 1 to the produced output.
-
-   QCOMPARE tries to output the contents of the values if the comparison fails,
-   so it is visible from the test log why the comparison failed.
-
-   QCOMPARE is very strict on the data types. Both \a actual and \a expected
-   have to be of the same type, otherwise the test won't compile. This prohibits
-   unspecified behavior from being introduced; that is behavior that usually
-   occurs when the compiler implicitly casts the argument.
-
-   For your own classes, you can use \l QTest::toString() to format values for
-   outputting into the test log.
-
-   \note This macro can only be used in a test function that is invoked
-   by the test framework.
-
-   Example:
-   \snippet code/src_qtestlib_qtestcase.cpp 2
-
-   \sa QVERIFY(), QTRY_COMPARE(), QTest::toString()
-*/
-
-/*! \macro QVERIFY_EXCEPTION_THROWN(expression, exceptiontype)
-   \since 5.3
-
-   \relates QTest
-
-   The QVERIFY_EXCEPTION_THROWN macro executes an \a expression and tries
-   to catch an exception thrown from the \a expression. If the \a expression
-   throws an exception and its type is the same as \a exceptiontype
-   or \a exceptiontype is substitutable with the type of thrown exception
-   (i.e. usually the type of thrown exception is publically derived
-   from \a exceptiontype) then execution will be continued. If not-substitutable
-   type of exception is thrown or the \a expression doesn't throw an exception
-   at all, then a failure will be recorded in the test log and
-   the test won't be executed further.
-
-   \note This macro can only be used in a test function that is invoked
-   by the test framework.
-*/
-
-/*! \macro QTRY_VERIFY_WITH_TIMEOUT(condition, timeout)
-   \since 5.0
-
-   \relates QTest
-
-   The QTRY_VERIFY_WITH_TIMEOUT() macro is similar to QVERIFY(), but checks the \a condition
-   repeatedly, until either the condition becomes true or the \a timeout is
-   reached.  Between each evaluation, events will be processed.  If the timeout
-   is reached, a failure is recorded in the test log and the test won't be
-   executed further.
-
-   \note This macro can only be used in a test function that is invoked
-   by the test framework.
-
-   \sa QTRY_VERIFY(), QTRY_VERIFY2_WITH_TIMEOUT(), QVERIFY(), QCOMPARE(), QTRY_COMPARE()
-*/
-
-
-/*! \macro QTRY_VERIFY(condition)
-   \since 5.0
-
-   \relates QTest
-
-   Checks the \a condition by invoking QTRY_VERIFY_WITH_TIMEOUT() with a timeout of five seconds.
-
-   \note This macro can only be used in a test function that is invoked
-   by the test framework.
-
-   \sa QTRY_VERIFY_WITH_TIMEOUT(), QTRY_VERIFY2(), QVERIFY(), QCOMPARE(), QTRY_COMPARE()
-*/
-
-/*! \macro QTRY_VERIFY2_WITH_TIMEOUT(condition, message, timeout)
-   \since 5.6
-
-   \relates QTest
-
-   The QTRY_VERIFY2_WITH_TIMEOUT macro is similar to QTRY_VERIFY_WITH_TIMEOUT()
-   except that it outputs a verbose \a message when \a condition is still false
-   after the specified \a timeout. The \a message is a plain C string.
-
-   Example:
-   \code
-   QTRY_VERIFY2_WITH_TIMEOUT(list.size() > 2, QByteArray::number(list.size()).constData(), 10000);
-   \endcode
-
-   \note This macro can only be used in a test function that is invoked
-   by the test framework.
-
-   \sa QTRY_VERIFY(), QTRY_VERIFY_WITH_TIMEOUT(), QVERIFY(), QCOMPARE(), QTRY_COMPARE()
-*/
-
-/*! \macro QTRY_VERIFY2(condition, message)
-   \since 5.6
-
-   \relates QTest
-
-   Checks the \a condition by invoking QTRY_VERIFY2_WITH_TIMEOUT() with a timeout
-   of five seconds. If \a condition is then still false, \a message is output.
-   The \a message is a plain C string.
-
-   Example:
-   \code
-   QTRY_VERIFY2_WITH_TIMEOUT(list.size() > 2, QByteArray::number(list.size()).constData());
-   \endcode
-
-   \note This macro can only be used in a test function that is invoked
-   by the test framework.
-
-   \sa QTRY_VERIFY2_WITH_TIMEOUT(), QTRY_VERIFY2(), QVERIFY(), QCOMPARE(), QTRY_COMPARE()
-*/
-
-/*! \macro QTRY_COMPARE_WITH_TIMEOUT(actual, expected, timeout)
-   \since 5.0
-
-   \relates QTest
-
-   The QTRY_COMPARE_WITH_TIMEOUT() macro is similar to QCOMPARE(), but performs the comparison
-   of the \a actual and \a expected values repeatedly, until either the two values
-   are equal or the \a timeout is reached.  Between each comparison, events
-   will be processed.  If the timeout is reached, a failure is recorded in the
-   test log and the test won't be executed further.
-
-   \note This macro can only be used in a test function that is invoked
-   by the test framework.
-
-   \sa QTRY_COMPARE(), QCOMPARE(), QVERIFY(), QTRY_VERIFY()
-*/
-
-/*! \macro QTRY_COMPARE(actual, expected)
-   \since 5.0
-
-   \relates QTest
-
-   Performs a comparison of the \a actual and \a expected values by
-   invoking QTRY_COMPARE_WITH_TIMEOUT() with a timeout of five seconds.
-
-   \note This macro can only be used in a test function that is invoked
-   by the test framework.
-
-   \sa QTRY_COMPARE_WITH_TIMEOUT(), QCOMPARE(), QVERIFY(), QTRY_VERIFY()
-*/
-
-/*! \macro QFETCH(type, name)
-
-   \relates QTest
-
-   The fetch macro creates a local variable named \a name with the type \a type
-   on the stack. \a name has to match the element name from the test's data.
-   If no such element exists, the test will assert.
-
-   Assuming a test has the following data:
-
-   \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 code/src_qtestlib_qtestcase.cpp 4
-
-   \c aString and \c expected are variables on the stack that are initialized with
-   the current test data.
-
-   \b {Note:} This macro can only be used in a test function that is invoked
-   by the test framework. The test function must have a _data function.
-*/
-
-/*! \macro QWARN(message)
-
-   \relates QTest
-   \threadsafe
-
-   Appends \a message as a warning to the test log. This macro can be used anywhere
-   in your tests.
-*/
-
-/*! \macro QFAIL(message)
-
-   \relates QTest
-
-   This macro can be used to force a test failure. The test stops
-   executing and the failure \a message is appended to the test log.
-
-   \b {Note:} This macro can only be used in a test function that is invoked
-   by the test framework.
-
-   Example:
-
-   \snippet code/src_qtestlib_qtestcase.cpp 5
-*/
-
-/*! \macro QTEST(actual, testElement)
-
-   \relates QTest
-
-   QTEST() is a convenience macro for \l QCOMPARE() that compares
-   the value \a actual with the element \a testElement from the test's data.
-   If there is no such element, the test asserts.
-
-   Apart from that, QTEST() behaves exactly as \l QCOMPARE().
-
-   Instead of writing:
-
-   \snippet code/src_qtestlib_qtestcase.cpp 6
-
-   you can write:
-
-   \snippet code/src_qtestlib_qtestcase.cpp 7
-
-   \sa QCOMPARE()
-*/
-
-/*! \macro QSKIP(description)
-
-   \relates QTest
-
-   If called from a test function, the QSKIP() macro stops execution of the test
-   without adding a failure to the test log. You can use it to skip tests that
-   wouldn't make sense in the current configuration. The text \a description is
-   appended to the test log and should contain an explanation of why the test
-   couldn't be executed.
-
-   If the test is data-driven, each call to QSKIP() will skip only the current
-   row of test data, so an unconditional call to QSKIP will produce one skip
-   message in the test log for each row of test data.
-
-   If called from an _data function, the QSKIP() macro will stop execution of
-   the _data function and will prevent execution of the associated test
-   function.
-
-   If called from initTestCase() or initTestCase_data(), the QSKIP() macro will
-   skip all test and _data functions.
-
-   \b {Note:} This macro can only be used in a test function or _data
-   function that is invoked by the test framework.
-
-   Example:
-   \snippet code/src_qtestlib_qtestcase.cpp 8
-*/
-
-/*! \macro QEXPECT_FAIL(dataIndex, comment, mode)
-
-   \relates QTest
-
-   The QEXPECT_FAIL() macro marks the next \l QCOMPARE() or \l QVERIFY() as an
-   expected failure. Instead of adding a failure to the test log, an expected
-   failure will be reported.
-
-   If a \l QVERIFY() or \l QCOMPARE() is marked as an expected failure,
-   but passes instead, an unexpected pass (XPASS) is written to the test log.
-
-   The parameter \a dataIndex describes for which entry in the test data the
-   failure is expected. Pass an empty string (\c{""}) if the failure
-   is expected for all entries or if no test data exists.
-
-   \a comment will be appended to the test log for the expected failure.
-
-   \a mode is a \l QTest::TestFailMode and sets whether the test should
-   continue to execute or not.
-
-   \b {Note:} This macro can only be used in a test function that is invoked
-   by the test framework.
-
-   Example 1:
-   \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
-   is written instead. The QEXPECT_FAIL() has no influence on the second QCOMPARE()
-   statement in the example.
-
-   Example 2:
-   \snippet code/src_qtestlib_qtestcase.cpp 10
-
-   The above testfunction will not continue executing for the test data
-   entry \c{data27}.
-
-   \sa QTest::TestFailMode, QVERIFY(), QCOMPARE()
-*/
-
-/*! \macro QFINDTESTDATA(filename)
-   \since 5.0
-
-   \relates QTest
-
-   Returns a QString for the testdata file referred to by \a filename, or an
-   empty QString if the testdata file could not be found.
-
-   This macro allows the test to load data from an external file without
-   hardcoding an absolute filename into the test, or using relative paths
-   which may be error prone.
-
-   The returned path will be the first path from the following list which
-   resolves to an existing file or directory:
-
-   \list
-   \li \a filename relative to QCoreApplication::applicationDirPath()
-      (only if a QCoreApplication or QApplication object has been created).
-   \li \a filename relative to the test's standard install directory
-      (QLibraryInfo::TestsPath with the lowercased testcase name appended).
-   \li \a filename relative to the directory containing the source file from which
-      QFINDTESTDATA is invoked.
-   \endlist
-
-   If the named file/directory does not exist at any of these locations,
-   a warning is printed to the test log.
-
-   For example, in this code:
-   \snippet code/src_qtestlib_qtestcase.cpp 26
-
-   The testdata file will be resolved as the first existing file from:
-
-   \list
-   \li \c{/home/user/build/myxmlparser/tests/tst_myxmlparser/testxml/simple1.xml}
-   \li \c{/usr/local/Qt-5.0.0/tests/tst_myxmlparser/testxml/simple1.xml}
-   \li \c{/home/user/sources/myxmlparser/tests/tst_myxmlparser/testxml/simple1.xml}
-   \endlist
-
-   This allows the test to find its testdata regardless of whether the
-   test has been installed, and regardless of whether the test's build tree
-   is equal to the test's source tree.
-
-   \b {Note:} reliable detection of testdata from the source directory requires
-   either that qmake is used, or the \c{QT_TESTCASE_BUILDDIR} macro is defined to
-   point to the working directory from which the compiler is invoked, or only
-   absolute paths to the source files are passed to the compiler. Otherwise, the
-   absolute path of the source directory cannot be determined.
-
-   \b {Note:} For tests that use the \l QTEST_APPLESS_MAIN() macro to generate a
-   \c{main()} function, \c{QFINDTESTDATA} will not attempt to find test data
-   relative to QCoreApplication::applicationDirPath().  In practice, this means that
-   tests using \c{QTEST_APPLESS_MAIN()} will fail to find their test data
-   if run from a shadow build tree.
-*/
-
-/*! \macro QTEST_MAIN(TestClass)
-
-    \relates QTest
-
-    Implements a main() function that instantiates an application object and
-    the \a TestClass, and executes all tests in the order they were defined.
-    Use this macro to build stand-alone executables.
-
-    If \c QT_WIDGETS_LIB is defined, the application object will be a QApplication,
-    if \c QT_GUI_LIB is defined, the application object will be a QGuiApplication,
-    otherwise it will be a QCoreApplication.  If qmake is used and the configuration
-    includes \c{QT += widgets}, then \c QT_WIDGETS_LIB will be defined automatically.
-    Similarly, if qmake is used and the configuration includes \c{QT += gui}, then
-    \c QT_GUI_LIB will be defined automatically.
-
-    \b {Note:} On platforms that have keypad navigation enabled by default,
-    this macro will forcefully disable it if \c QT_WIDGETS_LIB is defined.  This is done
-    to simplify the usage of key events when writing autotests. If you wish to write a
-    test case that uses keypad navigation, you should enable it either in the
-    \c {initTestCase()} or \c {init()} functions of your test case by calling
-    \l {QApplication::setNavigationMode()}.
-
-    Example:
-    \snippet code/src_qtestlib_qtestcase.cpp 11
-
-    \sa QTEST_APPLESS_MAIN(), QTEST_GUILESS_MAIN(), QTest::qExec(),
-    QApplication::setNavigationMode()
-*/
-
-/*! \macro QTEST_APPLESS_MAIN(TestClass)
-
-    \relates QTest
-
-    Implements a main() function that executes all tests in \a TestClass.
-
-    Behaves like \l QTEST_MAIN(), but doesn't instantiate a QApplication
-    object. Use this macro for really simple stand-alone non-GUI tests.
-
-    \sa QTEST_MAIN()
-*/
-
-/*! \macro QTEST_GUILESS_MAIN(TestClass)
-    \since 5.0
-
-    \relates QTest
-
-    Implements a main() function that instantiates a QCoreApplication object
-    and the \a TestClass, and executes all tests in the order they were
-    defined.  Use this macro to build stand-alone executables.
-
-    Behaves like \l QTEST_MAIN(), but instantiates a QCoreApplication instead
-    of the QApplication object. Use this macro if your test case doesn't need
-    functionality offered by QApplication, but the event loop is still necessary.
-
-    \sa QTEST_MAIN()
-*/
-
-/*!
-    \macro QBENCHMARK
-
-    \relates QTest
-
-    This macro is used to measure the performance of code within a test.
-    The code to be benchmarked is contained within a code block following
-    this macro.
-
-    For example:
-
-    \snippet code/src_qtestlib_qtestcase.cpp 27
-
-    \sa {Qt Test Overview#Creating a Benchmark}{Creating a Benchmark},
-        {Chapter 5: Writing a Benchmark}{Writing a Benchmark}
-*/
-
-/*!
-    \macro QBENCHMARK_ONCE
-    \since 4.6
-
-    \relates QTest
-
-    \brief The QBENCHMARK_ONCE macro is for measuring performance of a
-    code block by running it once.
-
-    This macro is used to measure the performance of code within a test.
-    The code to be benchmarked is contained within a code block following
-    this macro.
-
-    Unlike QBENCHMARK, the contents of the contained code block is only run
-    once. The elapsed time will be reported as "0" if it's to short to
-    be measured by the selected backend. (Use)
-
-    \sa {Qt Test Overview#Creating a Benchmark}{Creating a Benchmark},
-    {Chapter 5: Writing a Benchmark}{Writing a Benchmark}
-*/
-
-/*! \enum QTest::TestFailMode
-
-    This enum describes the modes for handling an expected failure of the
-    \l QVERIFY() or \l QCOMPARE() macros.
-
-    \value Abort Aborts the execution of the test. Use this mode when it
-           doesn't make sense to execute the test any further after the
-           expected failure.
-
-    \value Continue Continues execution of the test after the expected failure.
-
-    \sa QEXPECT_FAIL()
-*/
-
-/*! \enum QTest::KeyAction
-
-    This enum describes possible actions for key handling.
-
-    \value Press    The key is pressed.
-    \value Release  The key is released.
-    \value Click    The key is clicked (pressed and released).
-*/
-
-/*! \enum QTest::MouseAction
-
-    This enum describes possible actions for mouse handling.
-
-    \value MousePress    A mouse button is pressed.
-    \value MouseRelease  A mouse button is released.
-    \value MouseClick    A mouse button is clicked (pressed and released).
-    \value MouseDClick   A mouse button is double clicked (pressed and released twice).
-    \value MouseMove     The mouse pointer has moved.
-*/
-
-/*! \fn void QTest::keyClick(QWidget *widget, Qt::Key key, Qt::KeyboardModifiers modifier = Qt::NoModifier, int delay=-1)
-
-    Simulates clicking of \a key with an optional \a modifier on a \a widget.
-    If \a delay is larger than 0, the test will wait for \a delay milliseconds
-    before clicking the key.
-
-    Examples:
-    \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
-    second example simulates clicking \c shift-escape on \c myWidget
-    following a 200 ms delay of the test.
-
-    \sa QTest::keyClicks()
-*/
-
-/*! \fn void QTest::keyClick(QWidget *widget, char key, Qt::KeyboardModifiers modifier = Qt::NoModifier, int delay=-1)
-    \overload
-
-    Simulates clicking of \a key with an optional \a modifier on a \a widget.
-    If \a delay is larger than 0, the test will wait for \a delay milliseconds
-    before clicking the key.
-
-    Example:
-    \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.
-
-    \sa QTest::keyClicks()
-*/
-
-/*! \fn void QTest::keyClick(QWindow *window, Qt::Key key, Qt::KeyboardModifiers modifier = Qt::NoModifier, int delay=-1)
-    \overload
-    \since 5.0
-
-    Simulates clicking of \a key with an optional \a modifier on a \a window.
-    If \a delay is larger than 0, the test will wait for \a delay milliseconds
-    before clicking the key.
-
-    Examples:
-    \snippet code/src_qtestlib_qtestcase.cpp 29
-
-    The first example above simulates clicking the \c escape key on \c
-    myWindow without any keyboard modifiers and without delay. The
-    second example simulates clicking \c shift-escape on \c myWindow
-    following a 200 ms delay of the test.
-
-    \sa QTest::keyClicks()
-*/
-
-/*! \fn void QTest::keyClick(QWindow *window, char key, Qt::KeyboardModifiers modifier = Qt::NoModifier, int delay=-1)
-    \overload
-    \since 5.0
-
-    Simulates clicking of \a key with an optional \a modifier on a \a window.
-    If \a delay is larger than 0, the test will wait for \a delay milliseconds
-    before clicking the key.
-
-    Example:
-    \snippet code/src_qtestlib_qtestcase.cpp 28
-
-    The example above simulates clicking \c a on \c myWindow without
-    any keyboard modifiers and without delay of the test.
-
-    \sa QTest::keyClicks()
-*/
-
-/*! \fn void QTest::keyEvent(KeyAction action, QWidget *widget, Qt::Key key, Qt::KeyboardModifiers modifier = Qt::NoModifier, int delay=-1)
-
-    Sends a Qt key event to \a widget with the given \a key and an associated \a action.
-    Optionally, a keyboard \a modifier can be specified, as well as a \a delay
-    (in milliseconds) of the test before sending the event.
-*/
-
-/*! \fn void QTest::keyEvent(KeyAction action, QWidget *widget, char ascii, Qt::KeyboardModifiers modifier = Qt::NoModifier, int delay=-1)
-    \overload
-
-    Sends a Qt key event to \a widget with the given key \a ascii and an associated \a action.
-    Optionally, a keyboard \a modifier can be specified, as well as a \a delay
-    (in milliseconds) of the test before sending the event.
-*/
-
-/*! \fn void QTest::keyEvent(KeyAction action, QWindow *window, Qt::Key key, Qt::KeyboardModifiers modifier = Qt::NoModifier, int delay=-1)
-    \overload
-    \since 5.0
-
-    Sends a Qt key event to \a window with the given \a key and an associated \a action.
-    Optionally, a keyboard \a modifier can be specified, as well as a \a delay
-    (in milliseconds) of the test before sending the event.
-*/
-
-/*! \fn void QTest::keyEvent(KeyAction action, QWindow *window, char ascii, Qt::KeyboardModifiers modifier = Qt::NoModifier, int delay=-1)
-    \overload
-    \since 5.0
-
-    Sends a Qt key event to \a window with the given key \a ascii and an associated \a action.
-    Optionally, a keyboard \a modifier can be specified, as well as a \a delay
-    (in milliseconds) of the test before sending the event.
-*/
-
-/*! \fn void QTest::keyPress(QWidget *widget, Qt::Key key, Qt::KeyboardModifiers modifier = Qt::NoModifier, int delay=-1)
-
-    Simulates pressing a \a key with an optional \a modifier on a \a widget. If \a delay
-    is larger than 0, the test will wait for \a delay milliseconds before pressing the key.
-
-    \b {Note:} At some point you should release the key using \l keyRelease().
-
-    \sa QTest::keyRelease(), QTest::keyClick()
-*/
-
-/*! \fn void QTest::keyPress(QWidget *widget, char key, Qt::KeyboardModifiers modifier = Qt::NoModifier, int delay=-1)
-    \overload
-
-    Simulates pressing a \a key with an optional \a modifier on a \a widget.
-    If \a delay is larger than 0, the test will wait for \a delay milliseconds
-    before pressing the key.
-
-    \b {Note:} At some point you should release the key using \l keyRelease().
-
-    \sa QTest::keyRelease(), QTest::keyClick()
-*/
-
-/*! \fn void QTest::keyPress(QWindow *window, Qt::Key key, Qt::KeyboardModifiers modifier = Qt::NoModifier, int delay=-1)
-    \overload
-    \since 5.0
-
-    Simulates pressing a \a key with an optional \a modifier on a \a window. If \a delay
-    is larger than 0, the test will wait for \a delay milliseconds before pressing the key.
-
-    \b {Note:} At some point you should release the key using \l keyRelease().
-
-    \sa QTest::keyRelease(), QTest::keyClick()
-*/
-
-/*! \fn void QTest::keyPress(QWindow *window, char key, Qt::KeyboardModifiers modifier = Qt::NoModifier, int delay=-1)
-    \overload
-    \since 5.0
-
-    Simulates pressing a \a key with an optional \a modifier on a \a window.
-    If \a delay is larger than 0, the test will wait for \a delay milliseconds
-    before pressing the key.
-
-    \b {Note:} At some point you should release the key using \l keyRelease().
-
-    \sa QTest::keyRelease(), QTest::keyClick()
-*/
-
-/*! \fn void QTest::keyRelease(QWidget *widget, Qt::Key key, Qt::KeyboardModifiers modifier = Qt::NoModifier, int delay=-1)
-
-    Simulates releasing a \a key with an optional \a modifier on a \a widget.
-    If \a delay is larger than 0, the test will wait for \a delay milliseconds
-    before releasing the key.
-
-    \sa QTest::keyPress(), QTest::keyClick()
-*/
-
-/*! \fn void QTest::keyRelease(QWidget *widget, char key, Qt::KeyboardModifiers modifier = Qt::NoModifier, int delay=-1)
-    \overload
-
-    Simulates releasing a \a key with an optional \a modifier on a \a widget.
-    If \a delay is larger than 0, the test will wait for \a delay milliseconds
-    before releasing the key.
-
-    \sa QTest::keyClick()
-*/
-
-/*! \fn void QTest::keyRelease(QWindow *window, Qt::Key key, Qt::KeyboardModifiers modifier = Qt::NoModifier, int delay=-1)
-    \overload
-    \since 5.0
-
-    Simulates releasing a \a key with an optional \a modifier on a \a window.
-    If \a delay is larger than 0, the test will wait for \a delay milliseconds
-    before releasing the key.
-
-    \sa QTest::keyPress(), QTest::keyClick()
-*/
-
-/*! \fn void QTest::keyRelease(QWindow *window, char key, Qt::KeyboardModifiers modifier = Qt::NoModifier, int delay=-1)
-    \overload
-    \since 5.0
-
-    Simulates releasing a \a key with an optional \a modifier on a \a window.
-    If \a delay is larger than 0, the test will wait for \a delay milliseconds
-    before releasing the key.
-
-    \sa QTest::keyClick()
-*/
-
-/*! \fn void QTest::keyClicks(QWidget *widget, const QString &sequence, Qt::KeyboardModifiers modifier = Qt::NoModifier, int delay=-1)
-
-    Simulates clicking a \a sequence of keys on a \a
-    widget. Optionally, a keyboard \a modifier can be specified as
-    well as a \a delay (in milliseconds) of the test before each key
-    click.
-
-    Example:
-    \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
-    modifiers and without delay of the test.
-
-    \sa QTest::keyClick()
-*/
-
-/*! \fn void QTest::waitForEvents()
-    \internal
-*/
-
-/*! \fn void QTest::mouseEvent(MouseAction action, QWidget *widget, Qt::MouseButton button, Qt::KeyboardModifiers stateKey, QPoint pos, int delay=-1)
-    \internal
-*/
-
-/*! \fn void QTest::mouseEvent(MouseAction action, QWindow *window, Qt::MouseButton button, Qt::KeyboardModifiers stateKey, QPoint pos, int delay=-1)
-    \internal
-*/
-
-/*! \fn void QTest::mousePress(QWidget *widget, Qt::MouseButton button, Qt::KeyboardModifiers modifier = 0, QPoint pos = QPoint(), int delay=-1)
-
-    Simulates pressing a mouse \a button with an optional \a modifier
-    on a \a widget.  The position is defined by \a pos; the default
-    position is the center of the widget. If \a delay is specified,
-    the test will wait for the specified amount of milliseconds before
-    the press.
-
-    \sa QTest::mouseRelease(), QTest::mouseClick()
-*/
-
-/*! \fn void QTest::mousePress(QWindow *window, Qt::MouseButton button, Qt::KeyboardModifiers stateKey = 0, QPoint pos = QPoint(), int delay=-1)
-    \overload
-    \since 5.0
-
-    Simulates pressing a mouse \a button with an optional \a stateKey modifier
-    on a \a window.  The position is defined by \a pos; the default
-    position is the center of the window. If \a delay is specified,
-    the test will wait for the specified amount of milliseconds before
-    the press.
-
-    \sa QTest::mouseRelease(), QTest::mouseClick()
-*/
-
-/*! \fn void QTest::mouseRelease(QWidget *widget, Qt::MouseButton button, Qt::KeyboardModifiers modifier = 0, QPoint pos = QPoint(), int delay=-1)
-
-    Simulates releasing a mouse \a button with an optional \a modifier
-    on a \a widget.  The position of the release is defined by \a pos;
-    the default position is the center of the widget. If \a delay is
-    specified, the test will wait for the specified amount of
-    milliseconds before releasing the button.
-
-    \sa QTest::mousePress(), QTest::mouseClick()
-*/
-
-/*! \fn void QTest::mouseRelease(QWindow *window, Qt::MouseButton button, Qt::KeyboardModifiers stateKey = 0, QPoint pos = QPoint(), int delay=-1)
-    \overload
-    \since 5.0
-
-    Simulates releasing a mouse \a button with an optional \a stateKey modifier
-    on a \a window.  The position of the release is defined by \a pos;
-    the default position is the center of the window. If \a delay is
-    specified, the test will wait for the specified amount of
-    milliseconds before releasing the button.
-
-    \sa QTest::mousePress(), QTest::mouseClick()
-*/
-
-/*! \fn void QTest::mouseClick(QWidget *widget, Qt::MouseButton button, Qt::KeyboardModifiers modifier = 0, QPoint pos = QPoint(), int delay=-1)
-
-    Simulates clicking a mouse \a button with an optional \a modifier
-    on a \a widget.  The position of the click is defined by \a pos;
-    the default position is the center of the widget. If \a delay is
-    specified, the test will wait for the specified amount of
-    milliseconds before pressing and before releasing the button.
-
-    \sa QTest::mousePress(), QTest::mouseRelease()
-*/
-
-/*! \fn void QTest::mouseClick(QWindow *window, Qt::MouseButton button, Qt::KeyboardModifiers stateKey = 0, QPoint pos = QPoint(), int delay=-1)
-    \overload
-    \since 5.0
-
-    Simulates clicking a mouse \a button with an optional \a stateKey modifier
-    on a \a window.  The position of the click is defined by \a pos;
-    the default position is the center of the window. If \a delay is
-    specified, the test will wait for the specified amount of
-    milliseconds before pressing and before releasing the button.
-
-    \sa QTest::mousePress(), QTest::mouseRelease()
-*/
-
-/*! \fn void QTest::mouseDClick(QWidget *widget, Qt::MouseButton button, Qt::KeyboardModifiers modifier = 0, QPoint pos = QPoint(), int delay=-1)
-
-    Simulates double clicking a mouse \a button with an optional \a
-    modifier on a \a widget.  The position of the click is defined by
-    \a pos; the default position is the center of the widget. If \a
-    delay is specified, the test will wait for the specified amount of
-    milliseconds before each press and release.
-
-    \sa QTest::mouseClick()
-*/
-
-/*! \fn void QTest::mouseDClick(QWindow *window, Qt::MouseButton button, Qt::KeyboardModifiers stateKey = 0, QPoint pos = QPoint(), int delay=-1)
-    \overload
-    \since 5.0
-
-    Simulates double clicking a mouse \a button with an optional \a stateKey
-    modifier on a \a window.  The position of the click is defined by
-    \a pos; the default position is the center of the window. If \a
-    delay is specified, the test will wait for the specified amount of
-    milliseconds before each press and release.
-
-    \sa QTest::mouseClick()
-*/
-
-/*! \fn void QTest::mouseMove(QWidget *widget, QPoint pos = QPoint(), int delay=-1)
-
-    Moves the mouse pointer to a \a widget. If \a pos is not
-    specified, the mouse pointer moves to the center of the widget. If
-    a \a delay (in milliseconds) is given, the test will wait before
-    moving the mouse pointer.
-*/
-
-/*! \fn void QTest::mouseMove(QWindow *window, QPoint pos = QPoint(), int delay=-1)
-    \overload
-    \since 5.0
-
-    Moves the mouse pointer to a \a window. If \a pos is not
-    specified, the mouse pointer moves to the center of the window. If
-    a \a delay (in milliseconds) is given, the test will wait before
-    moving the mouse pointer.
-*/
-
-/*!
-    \fn char *QTest::toString(const T &value)
-
-    Returns a textual representation of \a value. This function is used by
-    \l QCOMPARE() to output verbose information in case of a test failure.
-
-    You can add specializations or overloads of this function to your test to enable
-    verbose output.
-
-    \b {Note:} Starting with Qt 5.5, you should prefer to provide a toString() function
-    in the type's namespace instead of specializing this template.
-    If your code needs to continue to work with the QTestLib from Qt 5.4 or
-    earlier, you need to continue to use specialization.
-
-    \b {Note:} The caller of toString() must delete the returned data
-    using \c{delete[]}.  Your implementation should return a string
-    created with \c{new[]} or qstrdup(). The easiest way to do so is to
-    create a QByteArray or QString and calling QTest::toString() on it
-    (see second example below).
-
-    Example for specializing (Qt ≤ 5.4):
-
-    \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
-    MyPoint fails, \l QCOMPARE() will call this function to output the
-    contents of \c MyPoint to the test log.
-
-    Same example, but with overloading (Qt ≥ 5.5):
-
-    \snippet code/src_qtestlib_qtestcase.cpp toString-overload
-
-    \sa QCOMPARE()
-*/
-
-/*!
-    \fn char *QTest::toString(const QLatin1String &string)
-    \overload
-
-    Returns a textual representation of the given \a string.
-*/
-
-/*!
-    \fn char *QTest::toString(const QString &string)
-    \overload
-
-    Returns a textual representation of the given \a string.
-*/
-
-/*!
-    \fn char *QTest::toString(const QByteArray &ba)
-    \overload
-
-    Returns a textual representation of the byte array \a ba.
-
-    \sa QTest::toHexRepresentation()
-*/
-
-/*!
-    \fn char *QTest::toString(const QTime &time)
-    \overload
-
-    Returns a textual representation of the given \a time.
-*/
-
-/*!
-    \fn char *QTest::toString(const QDate &date)
-    \overload
-
-    Returns a textual representation of the given \a date.
-*/
-
-/*!
-    \fn char *QTest::toString(const QDateTime &dateTime)
-    \overload
-
-    Returns a textual representation of the date and time specified by
-    \a dateTime.
-*/
-
-/*!
-    \fn char *QTest::toString(const QChar &character)
-    \overload
-
-    Returns a textual representation of the given \a character.
-*/
-
-/*!
-    \fn char *QTest::toString(const QPoint &point)
-    \overload
-
-    Returns a textual representation of the given \a point.
-*/
-
-/*!
-    \fn char *QTest::toString(const QSize &size)
-    \overload
-
-    Returns a textual representation of the given \a size.
-*/
-
-/*!
-    \fn char *QTest::toString(const QRect &rectangle)
-    \overload
-
-    Returns a textual representation of the given \a rectangle.
-*/
-
-/*!
-    \fn char *QTest::toString(const QUrl &url)
-    \since 4.4
-    \overload
-
-    Returns a textual representation of the given \a url.
-*/
-
-/*!
-    \fn char *QTest::toString(const QPointF &point)
-    \overload
-
-    Returns a textual representation of the given \a point.
-*/
-
-/*!
-    \fn char *QTest::toString(const QSizeF &size)
-    \overload
-
-    Returns a textual representation of the given \a size.
-*/
-
-/*!
-    \fn char *QTest::toString(const QRectF &rectangle)
-    \overload
-
-    Returns a textual representation of the given \a rectangle.
-*/
-
-/*!
-    \fn char *QTest::toString(const QVariant &variant)
-    \overload
-
-    Returns a textual representation of the given \a variant.
-*/
-
-/*!
-    \fn char *QTest::toString(QSizePolicy::ControlType ct)
-    \overload
-    \since 5.5
-
-    Returns a textual representation of control type \a ct.
-*/
-
-/*!
-    \fn char *QTest::toString(QSizePolicy::ControlTypes cts)
-    \overload
-    \since 5.5
-
-    Returns a textual representation of control types \a cts.
-*/
-
-/*!
-    \fn char *QTest::toString(QSizePolicy::Policy p)
-    \overload
-    \since 5.5
-
-    Returns a textual representation of policy \a p.
-*/
-
-/*!
-    \fn char *QTest::toString(QSizePolicy sp)
-    \overload
-    \since 5.5
-
-    Returns a textual representation of size policy \a sp.
-*/
-
-/*! \fn void QTest::qWait(int ms)
-
-    Waits for \a ms milliseconds. While waiting, events will be processed and
-    your test will stay responsive to user interface events or network communication.
-
-    Example:
-    \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.
-
-    \sa QTest::qSleep(), QSignalSpy::wait()
-*/
-
-/*! \fn bool QTest::qWaitForWindowExposed(QWindow *window, int timeout)
-    \since 5.0
-
-    Waits for \a timeout milliseconds or until the \a window is exposed.
-    Returns \c true if \c window is exposed within \a timeout milliseconds, otherwise returns \c false.
-
-    This is mainly useful for asynchronous systems like X11, where a window will be mapped to screen some
-    time after being asked to show itself on the screen.
-
-    \sa QTest::qWaitForWindowActive(), QWindow::isExposed()
-*/
-
-/*! \fn bool QTest::qWaitForWindowActive(QWindow *window, int timeout)
-    \since 5.0
-
-    Waits for \a timeout milliseconds or until the \a window is active.
-
-    Returns \c true if \c window is active within \a timeout milliseconds, otherwise returns \c false.
-
-    \sa QTest::qWaitForWindowExposed(), QWindow::isActive()
-*/
-
-/*! \fn bool QTest::qWaitForWindowExposed(QWidget *widget, int timeout)
-    \since 5.0
-
-    Waits for \a timeout milliseconds or until the \a widget's window is exposed.
-    Returns \c true if \c widget's window is exposed within \a timeout milliseconds, otherwise returns \c false.
-
-    This is mainly useful for asynchronous systems like X11, where a window will be mapped to screen some
-    time after being asked to show itself on the screen.
-
-    \sa QTest::qWaitForWindowActive()
-*/
-
-/*! \fn bool QTest::qWaitForWindowActive(QWidget *widget, int timeout)
-    \since 5.0
-
-    Waits for \a timeout milliseconds or until the \a widget's window is active.
-
-    Returns \c true if \c widget's window is active within \a timeout milliseconds, otherwise returns \c false.
-
-    \sa QTest::qWaitForWindowExposed(), QWidget::isActiveWindow()
-*/
-
-/*! \fn bool QTest::qWaitForWindowShown(QWidget *widget, int timeout)
-    \since 5.0
-    \deprecated
-
-    Waits for \a timeout milliseconds or until the \a widget's window is exposed.
-    Returns \c true if \c widget's window is exposed within \a timeout milliseconds, otherwise returns \c false.
-
-    This function does the same as qWaitForWindowExposed().
-
-    Example:
-    \snippet code/src_qtestlib_qtestcase.cpp 24
-
-    \sa QTest::qWaitForWindowActive(), QTest::qWaitForWindowExposed()
-*/
-
-/*!
-    \class QTest::QTouchEventSequence
-    \inmodule QtTest
-    \since 4.6
-
-    \brief The QTouchEventSequence class is used to simulate a sequence of touch events.
-
-    To simulate a sequence of touch events on a specific device for a window or widget, call
-    QTest::touchEvent to create a QTouchEventSequence instance. Add touch events to
-    the sequence by calling press(), move(), release() and stationary(), and let the
-    instance run out of scope to commit the sequence to the event system.
-
-    Example:
-    \snippet code/src_qtestlib_qtestcase.cpp 25
-*/
-
-/*!
-    \fn QTest::QTouchEventSequence::~QTouchEventSequence()
-
-    Commits this sequence of touch events, unless autoCommit was disabled, and frees allocated resources.
-*/
-
-/*!
-  \fn void QTest::QTouchEventSequence::commit(bool processEvents)
-
-   Commits this sequence of touch events to the event system. Normally there is no need to call this
-   function because it is called from the destructor. However, if autoCommit is disabled, the events
-   only get committed upon explicitly calling this function.
-
-   In special cases tests may want to disable the processing of the events. This can be achieved by
-   setting \a processEvents to false. This results in merely queuing the events, the event loop will
-   not be forced to process them.
-*/
-
-/*!
-    \fn QTouchEventSequence &QTest::QTouchEventSequence::press(int touchId, const QPoint &pt, QWindow *window)
-    \since 5.0
-
-    Adds a press event for touchpoint \a touchId at position \a pt to this sequence and returns
-    a reference to this QTouchEventSequence.
-
-    The position \a pt is interpreted as relative to \a window. If \a window is the null pointer, then
-    \a pt is interpreted as relative to the window provided when instantiating this QTouchEventSequence.
-
-    Simulates that the user pressed the touch screen or pad with the finger identified by \a touchId.
-*/
-
-/*!
-    \fn QTouchEventSequence &QTest::QTouchEventSequence::press(int touchId, const QPoint &pt, QWidget *widget)
-
-    Adds a press event for touchpoint \a touchId at position \a pt to this sequence and returns
-    a reference to this QTouchEventSequence.
-
-    The position \a pt is interpreted as relative to \a widget. If \a widget is the null pointer, then
-    \a pt is interpreted as relative to the widget provided when instantiating this QTouchEventSequence.
-
-    Simulates that the user pressed the touch screen or pad with the finger identified by \a touchId.
-*/
-
-/*!
-    \fn QTouchEventSequence &QTest::QTouchEventSequence::move(int touchId, const QPoint &pt, QWindow *window)
-    \since 5.0
-
-    Adds a move event for touchpoint \a touchId at position \a pt to this sequence and returns
-    a reference to this QTouchEventSequence.
-
-    The position \a pt is interpreted as relative to \a window. If \a window is the null pointer, then
-    \a pt is interpreted as relative to the window provided when instantiating this QTouchEventSequence.
-
-    Simulates that the user moved the finger identified by \a touchId.
-*/
-
-/*!
-    \fn QTouchEventSequence &QTest::QTouchEventSequence::move(int touchId, const QPoint &pt, QWidget *widget)
-
-    Adds a move event for touchpoint \a touchId at position \a pt to this sequence and returns
-    a reference to this QTouchEventSequence.
-
-    The position \a pt is interpreted as relative to \a widget. If \a widget is the null pointer, then
-    \a pt is interpreted as relative to the widget provided when instantiating this QTouchEventSequence.
-
-    Simulates that the user moved the finger identified by \a touchId.
-*/
-
-/*!
-    \fn QTouchEventSequence &QTest::QTouchEventSequence::release(int touchId, const QPoint &pt, QWindow *window)
-    \since 5.0
-
-    Adds a release event for touchpoint \a touchId at position \a pt to this sequence and returns
-    a reference to this QTouchEventSequence.
-
-    The position \a pt is interpreted as relative to \a window. If \a window is the null pointer, then
-    \a pt is interpreted as relative to the window provided when instantiating this QTouchEventSequence.
-
-    Simulates that the user lifted the finger identified by \a touchId.
-*/
-
-/*!
-    \fn QTouchEventSequence &QTest::QTouchEventSequence::release(int touchId, const QPoint &pt, QWidget *widget)
-
-    Adds a release event for touchpoint \a touchId at position \a pt to this sequence and returns
-    a reference to this QTouchEventSequence.
-
-    The position \a pt is interpreted as relative to \a widget. If \a widget is the null pointer, then
-    \a pt is interpreted as relative to the widget provided when instantiating this QTouchEventSequence.
-
-    Simulates that the user lifted the finger identified by \a touchId.
-*/
-
-/*!
-    \fn QTouchEventSequence &QTest::QTouchEventSequence::stationary(int touchId)
-
-    Adds a stationary event for touchpoint \a touchId to this sequence and returns
-    a reference to this QTouchEventSequence.
-
-    Simulates that the user did not move the finger identified by \a touchId.
-*/
-
-/*!
-    \fn QTouchEventSequence QTest::touchEvent(QWindow *window, QTouchDevice *device, bool autoCommit)
-    \since 5.0
-
-    Creates and returns a QTouchEventSequence for the \a device to
-    simulate events for \a window.
-
-    When adding touch events to the sequence, \a window will also be used to translate
-    the position provided to screen coordinates, unless another window is provided in the
-    respective calls to press(), move() etc.
-
-    The touch events are committed to the event system when the destructor of the
-    QTouchEventSequence is called (ie when the object returned runs out of scope), unless
-    \a autoCommit is set to false. When \a autoCommit is false, commit() has to be called
-    manually.
-*/
-
-/*!
-    \fn QTouchEventSequence QTest::touchEvent(QWidget *widget, QTouchDevice *device, bool autoCommit)
-
-    Creates and returns a QTouchEventSequence for the \a device to
-    simulate events for \a widget.
-
-    When adding touch events to the sequence, \a widget will also be used to translate
-    the position provided to screen coordinates, unless another widget is provided in the
-    respective calls to press(), move() etc.
-
-    The touch events are committed to the event system when the destructor of the
-    QTouchEventSequence is called (ie when the object returned runs out of scope), unless
-    \a autoCommit is set to false. When \a autoCommit is false, commit() has to be called
-    manually.
-*/
-
 static bool installCoverageTool(const char * appname, const char * testname)
 {
 #ifdef __COVERAGESCANNER__
@@ -3578,6 +2323,11 @@ bool QTest::compare_string_helper(const char *t1, const char *t2, const char *ac
                           toString(t1), toString(t2), actual, expected, file, line);
 }
 
+/*!
+   \namespace QTest::Internal
+   \internal
+*/
+
 /*! \fn bool QTest::compare_ptr_helper(const void *t1, const void *t2, const char *actual, const char *expected, const char *file, int line);
     \internal
 */
diff --git a/src/testlib/qtestcase.qdoc b/src/testlib/qtestcase.qdoc
new file mode 100644
index 0000000000..7e14a236bc
--- /dev/null
+++ b/src/testlib/qtestcase.qdoc
@@ -0,0 +1,1278 @@
+/****************************************************************************
+**
+** Copyright (C) 2015 The Qt Company Ltd.
+** Contact: http://www.qt.io/licensing/
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** Commercial License Usage
+** Licensees holding valid commercial Qt licenses may use this file in
+** accordance with the commercial license agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and The Qt Company. For licensing terms
+** and conditions see http://www.qt.io/terms-conditions. For further
+** information use the contact form at http://www.qt.io/contact-us.
+**
+** GNU Free Documentation License Usage
+** 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. Please review the following information to ensure
+** the GNU Free Documentation License version 1.3 requirements
+** will be met: http://www.gnu.org/copyleft/fdl.html.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+   \namespace QTest
+   \inmodule QtTest
+
+   \brief The QTest namespace contains all the functions and
+   declarations that are related to Qt Test.
+
+   See the \l{Qt Test Overview} for information about how to write unit tests.
+*/
+
+/*! \macro QVERIFY(condition)
+
+   \relates QTest
+
+   The QVERIFY() macro checks whether the \a condition is true or not. If it is
+   true, execution continues. If not, a failure is recorded in the test log
+   and the test won't be executed further.
+
+   \b {Note:} This macro can only be used in a test function that is invoked
+   by the test framework.
+
+   Example:
+   \snippet code/src_qtestlib_qtestcase.cpp 0
+
+   \sa QCOMPARE(), QTRY_VERIFY()
+*/
+
+/*! \macro QVERIFY2(condition, message)
+
+    \relates QTest
+
+    The QVERIFY2() macro behaves exactly like QVERIFY(), except that it outputs
+    a verbose \a message when \a condition is false. The \a message is a plain
+    C string.
+
+    Example:
+    \snippet code/src_qtestlib_qtestcase.cpp 1
+
+    \sa QVERIFY(), QCOMPARE()
+*/
+
+/*! \macro QCOMPARE(actual, expected)
+
+   \relates QTest
+
+   The QCOMPARE macro compares an \a actual value to an \a expected value using
+   the equals operator. If \a actual and \a expected are identical, execution
+   continues. If not, a failure is recorded in the test log and the test
+   won't be executed further.
+
+   In the case of comparing floats and doubles, qFuzzyCompare() is used for
+   comparing. This means that comparing to 0 will likely fail. One solution
+   to this is to compare to 1, and add 1 to the produced output.
+
+   QCOMPARE tries to output the contents of the values if the comparison fails,
+   so it is visible from the test log why the comparison failed.
+
+   QCOMPARE is very strict on the data types. Both \a actual and \a expected
+   have to be of the same type, otherwise the test won't compile. This prohibits
+   unspecified behavior from being introduced; that is behavior that usually
+   occurs when the compiler implicitly casts the argument.
+
+   For your own classes, you can use \l QTest::toString() to format values for
+   outputting into the test log.
+
+   \note This macro can only be used in a test function that is invoked
+   by the test framework.
+
+   Example:
+   \snippet code/src_qtestlib_qtestcase.cpp 2
+
+   \sa QVERIFY(), QTRY_COMPARE(), QTest::toString()
+*/
+
+/*! \macro QVERIFY_EXCEPTION_THROWN(expression, exceptiontype)
+   \since 5.3
+
+   \relates QTest
+
+   The QVERIFY_EXCEPTION_THROWN macro executes an \a expression and tries
+   to catch an exception thrown from the \a expression. If the \a expression
+   throws an exception and its type is the same as \a exceptiontype
+   or \a exceptiontype is substitutable with the type of thrown exception
+   (i.e. usually the type of thrown exception is publically derived
+   from \a exceptiontype) then execution will be continued. If not-substitutable
+   type of exception is thrown or the \a expression doesn't throw an exception
+   at all, then a failure will be recorded in the test log and
+   the test won't be executed further.
+
+   \note This macro can only be used in a test function that is invoked
+   by the test framework.
+*/
+
+/*! \macro QTRY_VERIFY_WITH_TIMEOUT(condition, timeout)
+   \since 5.0
+
+   \relates QTest
+
+   The QTRY_VERIFY_WITH_TIMEOUT() macro is similar to QVERIFY(), but checks the \a condition
+   repeatedly, until either the condition becomes true or the \a timeout is
+   reached.  Between each evaluation, events will be processed.  If the timeout
+   is reached, a failure is recorded in the test log and the test won't be
+   executed further.
+
+   \note This macro can only be used in a test function that is invoked
+   by the test framework.
+
+   \sa QTRY_VERIFY(), QTRY_VERIFY2_WITH_TIMEOUT(), QVERIFY(), QCOMPARE(), QTRY_COMPARE()
+*/
+
+
+/*! \macro QTRY_VERIFY(condition)
+   \since 5.0
+
+   \relates QTest
+
+   Checks the \a condition by invoking QTRY_VERIFY_WITH_TIMEOUT() with a timeout of five seconds.
+
+   \note This macro can only be used in a test function that is invoked
+   by the test framework.
+
+   \sa QTRY_VERIFY_WITH_TIMEOUT(), QTRY_VERIFY2(), QVERIFY(), QCOMPARE(), QTRY_COMPARE()
+*/
+
+/*! \macro QTRY_VERIFY2_WITH_TIMEOUT(condition, message, timeout)
+   \since 5.6
+
+   \relates QTest
+
+   The QTRY_VERIFY2_WITH_TIMEOUT macro is similar to QTRY_VERIFY_WITH_TIMEOUT()
+   except that it outputs a verbose \a message when \a condition is still false
+   after the specified \a timeout. The \a message is a plain C string.
+
+   Example:
+   \code
+   QTRY_VERIFY2_WITH_TIMEOUT(list.size() > 2, QByteArray::number(list.size()).constData(), 10000);
+   \endcode
+
+   \note This macro can only be used in a test function that is invoked
+   by the test framework.
+
+   \sa QTRY_VERIFY(), QTRY_VERIFY_WITH_TIMEOUT(), QVERIFY(), QCOMPARE(), QTRY_COMPARE()
+*/
+
+/*! \macro QTRY_VERIFY2(condition, message)
+   \since 5.6
+
+   \relates QTest
+
+   Checks the \a condition by invoking QTRY_VERIFY2_WITH_TIMEOUT() with a timeout
+   of five seconds. If \a condition is then still false, \a message is output.
+   The \a message is a plain C string.
+
+   Example:
+   \code
+   QTRY_VERIFY2_WITH_TIMEOUT(list.size() > 2, QByteArray::number(list.size()).constData());
+   \endcode
+
+   \note This macro can only be used in a test function that is invoked
+   by the test framework.
+
+   \sa QTRY_VERIFY2_WITH_TIMEOUT(), QTRY_VERIFY2(), QVERIFY(), QCOMPARE(), QTRY_COMPARE()
+*/
+
+/*! \macro QTRY_COMPARE_WITH_TIMEOUT(actual, expected, timeout)
+   \since 5.0
+
+   \relates QTest
+
+   The QTRY_COMPARE_WITH_TIMEOUT() macro is similar to QCOMPARE(), but performs the comparison
+   of the \a actual and \a expected values repeatedly, until either the two values
+   are equal or the \a timeout is reached.  Between each comparison, events
+   will be processed.  If the timeout is reached, a failure is recorded in the
+   test log and the test won't be executed further.
+
+   \note This macro can only be used in a test function that is invoked
+   by the test framework.
+
+   \sa QTRY_COMPARE(), QCOMPARE(), QVERIFY(), QTRY_VERIFY()
+*/
+
+/*! \macro QTRY_COMPARE(actual, expected)
+   \since 5.0
+
+   \relates QTest
+
+   Performs a comparison of the \a actual and \a expected values by
+   invoking QTRY_COMPARE_WITH_TIMEOUT() with a timeout of five seconds.
+
+   \note This macro can only be used in a test function that is invoked
+   by the test framework.
+
+   \sa QTRY_COMPARE_WITH_TIMEOUT(), QCOMPARE(), QVERIFY(), QTRY_VERIFY()
+*/
+
+/*! \macro QFETCH(type, name)
+
+   \relates QTest
+
+   The fetch macro creates a local variable named \a name with the type \a type
+   on the stack. \a name has to match the element name from the test's data.
+   If no such element exists, the test will assert.
+
+   Assuming a test has the following data:
+
+   \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 code/src_qtestlib_qtestcase.cpp 4
+
+   \c aString and \c expected are variables on the stack that are initialized with
+   the current test data.
+
+   \b {Note:} This macro can only be used in a test function that is invoked
+   by the test framework. The test function must have a _data function.
+*/
+
+/*! \macro QWARN(message)
+
+   \relates QTest
+   \threadsafe
+
+   Appends \a message as a warning to the test log. This macro can be used anywhere
+   in your tests.
+*/
+
+/*! \macro QFAIL(message)
+
+   \relates QTest
+
+   This macro can be used to force a test failure. The test stops
+   executing and the failure \a message is appended to the test log.
+
+   \b {Note:} This macro can only be used in a test function that is invoked
+   by the test framework.
+
+   Example:
+
+   \snippet code/src_qtestlib_qtestcase.cpp 5
+*/
+
+/*! \macro QTEST(actual, testElement)
+
+   \relates QTest
+
+   QTEST() is a convenience macro for \l QCOMPARE() that compares
+   the value \a actual with the element \a testElement from the test's data.
+   If there is no such element, the test asserts.
+
+   Apart from that, QTEST() behaves exactly as \l QCOMPARE().
+
+   Instead of writing:
+
+   \snippet code/src_qtestlib_qtestcase.cpp 6
+
+   you can write:
+
+   \snippet code/src_qtestlib_qtestcase.cpp 7
+
+   \sa QCOMPARE()
+*/
+
+/*! \macro QSKIP(description)
+
+   \relates QTest
+
+   If called from a test function, the QSKIP() macro stops execution of the test
+   without adding a failure to the test log. You can use it to skip tests that
+   wouldn't make sense in the current configuration. The text \a description is
+   appended to the test log and should contain an explanation of why the test
+   couldn't be executed.
+
+   If the test is data-driven, each call to QSKIP() will skip only the current
+   row of test data, so an unconditional call to QSKIP will produce one skip
+   message in the test log for each row of test data.
+
+   If called from an _data function, the QSKIP() macro will stop execution of
+   the _data function and will prevent execution of the associated test
+   function.
+
+   If called from initTestCase() or initTestCase_data(), the QSKIP() macro will
+   skip all test and _data functions.
+
+   \b {Note:} This macro can only be used in a test function or _data
+   function that is invoked by the test framework.
+
+   Example:
+   \snippet code/src_qtestlib_qtestcase.cpp 8
+*/
+
+/*! \macro QEXPECT_FAIL(dataIndex, comment, mode)
+
+   \relates QTest
+
+   The QEXPECT_FAIL() macro marks the next \l QCOMPARE() or \l QVERIFY() as an
+   expected failure. Instead of adding a failure to the test log, an expected
+   failure will be reported.
+
+   If a \l QVERIFY() or \l QCOMPARE() is marked as an expected failure,
+   but passes instead, an unexpected pass (XPASS) is written to the test log.
+
+   The parameter \a dataIndex describes for which entry in the test data the
+   failure is expected. Pass an empty string (\c{""}) if the failure
+   is expected for all entries or if no test data exists.
+
+   \a comment will be appended to the test log for the expected failure.
+
+   \a mode is a \l QTest::TestFailMode and sets whether the test should
+   continue to execute or not.
+
+   \b {Note:} This macro can only be used in a test function that is invoked
+   by the test framework.
+
+   Example 1:
+   \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
+   is written instead. The QEXPECT_FAIL() has no influence on the second QCOMPARE()
+   statement in the example.
+
+   Example 2:
+   \snippet code/src_qtestlib_qtestcase.cpp 10
+
+   The above testfunction will not continue executing for the test data
+   entry \c{data27}.
+
+   \sa QTest::TestFailMode, QVERIFY(), QCOMPARE()
+*/
+
+/*! \macro QFINDTESTDATA(filename)
+   \since 5.0
+
+   \relates QTest
+
+   Returns a QString for the testdata file referred to by \a filename, or an
+   empty QString if the testdata file could not be found.
+
+   This macro allows the test to load data from an external file without
+   hardcoding an absolute filename into the test, or using relative paths
+   which may be error prone.
+
+   The returned path will be the first path from the following list which
+   resolves to an existing file or directory:
+
+   \list
+   \li \a filename relative to QCoreApplication::applicationDirPath()
+      (only if a QCoreApplication or QApplication object has been created).
+   \li \a filename relative to the test's standard install directory
+      (QLibraryInfo::TestsPath with the lowercased testcase name appended).
+   \li \a filename relative to the directory containing the source file from which
+      QFINDTESTDATA is invoked.
+   \endlist
+
+   If the named file/directory does not exist at any of these locations,
+   a warning is printed to the test log.
+
+   For example, in this code:
+   \snippet code/src_qtestlib_qtestcase.cpp 26
+
+   The testdata file will be resolved as the first existing file from:
+
+   \list
+   \li \c{/home/user/build/myxmlparser/tests/tst_myxmlparser/testxml/simple1.xml}
+   \li \c{/usr/local/Qt-5.0.0/tests/tst_myxmlparser/testxml/simple1.xml}
+   \li \c{/home/user/sources/myxmlparser/tests/tst_myxmlparser/testxml/simple1.xml}
+   \endlist
+
+   This allows the test to find its testdata regardless of whether the
+   test has been installed, and regardless of whether the test's build tree
+   is equal to the test's source tree.
+
+   \b {Note:} reliable detection of testdata from the source directory requires
+   either that qmake is used, or the \c{QT_TESTCASE_BUILDDIR} macro is defined to
+   point to the working directory from which the compiler is invoked, or only
+   absolute paths to the source files are passed to the compiler. Otherwise, the
+   absolute path of the source directory cannot be determined.
+
+   \b {Note:} For tests that use the \l QTEST_APPLESS_MAIN() macro to generate a
+   \c{main()} function, \c{QFINDTESTDATA} will not attempt to find test data
+   relative to QCoreApplication::applicationDirPath().  In practice, this means that
+   tests using \c{QTEST_APPLESS_MAIN()} will fail to find their test data
+   if run from a shadow build tree.
+*/
+
+/*! \macro QTEST_MAIN(TestClass)
+
+    \relates QTest
+
+    Implements a main() function that instantiates an application object and
+    the \a TestClass, and executes all tests in the order they were defined.
+    Use this macro to build stand-alone executables.
+
+    If \c QT_WIDGETS_LIB is defined, the application object will be a QApplication,
+    if \c QT_GUI_LIB is defined, the application object will be a QGuiApplication,
+    otherwise it will be a QCoreApplication.  If qmake is used and the configuration
+    includes \c{QT += widgets}, then \c QT_WIDGETS_LIB will be defined automatically.
+    Similarly, if qmake is used and the configuration includes \c{QT += gui}, then
+    \c QT_GUI_LIB will be defined automatically.
+
+    \b {Note:} On platforms that have keypad navigation enabled by default,
+    this macro will forcefully disable it if \c QT_WIDGETS_LIB is defined.  This is done
+    to simplify the usage of key events when writing autotests. If you wish to write a
+    test case that uses keypad navigation, you should enable it either in the
+    \c {initTestCase()} or \c {init()} functions of your test case by calling
+    \l {QApplication::setNavigationMode()}.
+
+    Example:
+    \snippet code/src_qtestlib_qtestcase.cpp 11
+
+    \sa QTEST_APPLESS_MAIN(), QTEST_GUILESS_MAIN(), QTest::qExec(),
+    QApplication::setNavigationMode()
+*/
+
+/*! \macro QTEST_APPLESS_MAIN(TestClass)
+
+    \relates QTest
+
+    Implements a main() function that executes all tests in \a TestClass.
+
+    Behaves like \l QTEST_MAIN(), but doesn't instantiate a QApplication
+    object. Use this macro for really simple stand-alone non-GUI tests.
+
+    \sa QTEST_MAIN()
+*/
+
+/*! \macro QTEST_GUILESS_MAIN(TestClass)
+    \since 5.0
+
+    \relates QTest
+
+    Implements a main() function that instantiates a QCoreApplication object
+    and the \a TestClass, and executes all tests in the order they were
+    defined.  Use this macro to build stand-alone executables.
+
+    Behaves like \l QTEST_MAIN(), but instantiates a QCoreApplication instead
+    of the QApplication object. Use this macro if your test case doesn't need
+    functionality offered by QApplication, but the event loop is still necessary.
+
+    \sa QTEST_MAIN()
+*/
+
+/*!
+    \macro QBENCHMARK
+
+    \relates QTest
+
+    This macro is used to measure the performance of code within a test.
+    The code to be benchmarked is contained within a code block following
+    this macro.
+
+    For example:
+
+    \snippet code/src_qtestlib_qtestcase.cpp 27
+
+    \sa {Qt Test Overview#Creating a Benchmark}{Creating a Benchmark},
+        {Chapter 5: Writing a Benchmark}{Writing a Benchmark}
+*/
+
+/*!
+    \macro QBENCHMARK_ONCE
+    \since 4.6
+
+    \relates QTest
+
+    \brief The QBENCHMARK_ONCE macro is for measuring performance of a
+    code block by running it once.
+
+    This macro is used to measure the performance of code within a test.
+    The code to be benchmarked is contained within a code block following
+    this macro.
+
+    Unlike QBENCHMARK, the contents of the contained code block is only run
+    once. The elapsed time will be reported as "0" if it's to short to
+    be measured by the selected backend. (Use)
+
+    \sa {Qt Test Overview#Creating a Benchmark}{Creating a Benchmark},
+    {Chapter 5: Writing a Benchmark}{Writing a Benchmark}
+*/
+
+/*! \enum QTest::TestFailMode
+
+    This enum describes the modes for handling an expected failure of the
+    \l QVERIFY() or \l QCOMPARE() macros.
+
+    \value Abort Aborts the execution of the test. Use this mode when it
+           doesn't make sense to execute the test any further after the
+           expected failure.
+
+    \value Continue Continues execution of the test after the expected failure.
+
+    \sa QEXPECT_FAIL()
+*/
+
+/*! \enum QTest::KeyAction
+
+    This enum describes possible actions for key handling.
+
+    \value Press    The key is pressed.
+    \value Release  The key is released.
+    \value Click    The key is clicked (pressed and released).
+*/
+
+/*! \enum QTest::MouseAction
+
+    This enum describes possible actions for mouse handling.
+
+    \value MousePress    A mouse button is pressed.
+    \value MouseRelease  A mouse button is released.
+    \value MouseClick    A mouse button is clicked (pressed and released).
+    \value MouseDClick   A mouse button is double clicked (pressed and released twice).
+    \value MouseMove     The mouse pointer has moved.
+*/
+
+/*! \fn void QTest::keyClick(QWidget *widget, Qt::Key key, Qt::KeyboardModifiers modifier = Qt::NoModifier, int delay=-1)
+
+    Simulates clicking of \a key with an optional \a modifier on a \a widget.
+    If \a delay is larger than 0, the test will wait for \a delay milliseconds
+    before clicking the key.
+
+    Examples:
+    \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
+    second example simulates clicking \c shift-escape on \c myWidget
+    following a 200 ms delay of the test.
+
+    \sa QTest::keyClicks()
+*/
+
+/*! \fn void QTest::keyClick(QWidget *widget, char key, Qt::KeyboardModifiers modifier = Qt::NoModifier, int delay=-1)
+    \overload
+
+    Simulates clicking of \a key with an optional \a modifier on a \a widget.
+    If \a delay is larger than 0, the test will wait for \a delay milliseconds
+    before clicking the key.
+
+    Example:
+    \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.
+
+    \sa QTest::keyClicks()
+*/
+
+/*! \fn void QTest::keyClick(QWindow *window, Qt::Key key, Qt::KeyboardModifiers modifier = Qt::NoModifier, int delay=-1)
+    \overload
+    \since 5.0
+
+    Simulates clicking of \a key with an optional \a modifier on a \a window.
+    If \a delay is larger than 0, the test will wait for \a delay milliseconds
+    before clicking the key.
+
+    Examples:
+    \snippet code/src_qtestlib_qtestcase.cpp 29
+
+    The first example above simulates clicking the \c escape key on \c
+    myWindow without any keyboard modifiers and without delay. The
+    second example simulates clicking \c shift-escape on \c myWindow
+    following a 200 ms delay of the test.
+
+    \sa QTest::keyClicks()
+*/
+
+/*! \fn void QTest::keyClick(QWindow *window, char key, Qt::KeyboardModifiers modifier = Qt::NoModifier, int delay=-1)
+    \overload
+    \since 5.0
+
+    Simulates clicking of \a key with an optional \a modifier on a \a window.
+    If \a delay is larger than 0, the test will wait for \a delay milliseconds
+    before clicking the key.
+
+    Example:
+    \snippet code/src_qtestlib_qtestcase.cpp 28
+
+    The example above simulates clicking \c a on \c myWindow without
+    any keyboard modifiers and without delay of the test.
+
+    \sa QTest::keyClicks()
+*/
+
+/*! \fn void QTest::keyEvent(KeyAction action, QWidget *widget, Qt::Key key, Qt::KeyboardModifiers modifier = Qt::NoModifier, int delay=-1)
+
+    Sends a Qt key event to \a widget with the given \a key and an associated \a action.
+    Optionally, a keyboard \a modifier can be specified, as well as a \a delay
+    (in milliseconds) of the test before sending the event.
+*/
+
+/*! \fn void QTest::keyEvent(KeyAction action, QWidget *widget, char ascii, Qt::KeyboardModifiers modifier = Qt::NoModifier, int delay=-1)
+    \overload
+
+    Sends a Qt key event to \a widget with the given key \a ascii and an associated \a action.
+    Optionally, a keyboard \a modifier can be specified, as well as a \a delay
+    (in milliseconds) of the test before sending the event.
+*/
+
+/*! \fn void QTest::keyEvent(KeyAction action, QWindow *window, Qt::Key key, Qt::KeyboardModifiers modifier = Qt::NoModifier, int delay=-1)
+    \overload
+    \since 5.0
+
+    Sends a Qt key event to \a window with the given \a key and an associated \a action.
+    Optionally, a keyboard \a modifier can be specified, as well as a \a delay
+    (in milliseconds) of the test before sending the event.
+*/
+
+/*! \fn void QTest::keyEvent(KeyAction action, QWindow *window, char ascii, Qt::KeyboardModifiers modifier = Qt::NoModifier, int delay=-1)
+    \overload
+    \since 5.0
+
+    Sends a Qt key event to \a window with the given key \a ascii and an associated \a action.
+    Optionally, a keyboard \a modifier can be specified, as well as a \a delay
+    (in milliseconds) of the test before sending the event.
+*/
+
+/*! \fn void QTest::keyPress(QWidget *widget, Qt::Key key, Qt::KeyboardModifiers modifier = Qt::NoModifier, int delay=-1)
+
+    Simulates pressing a \a key with an optional \a modifier on a \a widget. If \a delay
+    is larger than 0, the test will wait for \a delay milliseconds before pressing the key.
+
+    \b {Note:} At some point you should release the key using \l keyRelease().
+
+    \sa QTest::keyRelease(), QTest::keyClick()
+*/
+
+/*! \fn void QTest::keyPress(QWidget *widget, char key, Qt::KeyboardModifiers modifier = Qt::NoModifier, int delay=-1)
+    \overload
+
+    Simulates pressing a \a key with an optional \a modifier on a \a widget.
+    If \a delay is larger than 0, the test will wait for \a delay milliseconds
+    before pressing the key.
+
+    \b {Note:} At some point you should release the key using \l keyRelease().
+
+    \sa QTest::keyRelease(), QTest::keyClick()
+*/
+
+/*! \fn void QTest::keyPress(QWindow *window, Qt::Key key, Qt::KeyboardModifiers modifier = Qt::NoModifier, int delay=-1)
+    \overload
+    \since 5.0
+
+    Simulates pressing a \a key with an optional \a modifier on a \a window. If \a delay
+    is larger than 0, the test will wait for \a delay milliseconds before pressing the key.
+
+    \b {Note:} At some point you should release the key using \l keyRelease().
+
+    \sa QTest::keyRelease(), QTest::keyClick()
+*/
+
+/*! \fn void QTest::keyPress(QWindow *window, char key, Qt::KeyboardModifiers modifier = Qt::NoModifier, int delay=-1)
+    \overload
+    \since 5.0
+
+    Simulates pressing a \a key with an optional \a modifier on a \a window.
+    If \a delay is larger than 0, the test will wait for \a delay milliseconds
+    before pressing the key.
+
+    \b {Note:} At some point you should release the key using \l keyRelease().
+
+    \sa QTest::keyRelease(), QTest::keyClick()
+*/
+
+/*! \fn void QTest::keyRelease(QWidget *widget, Qt::Key key, Qt::KeyboardModifiers modifier = Qt::NoModifier, int delay=-1)
+
+    Simulates releasing a \a key with an optional \a modifier on a \a widget.
+    If \a delay is larger than 0, the test will wait for \a delay milliseconds
+    before releasing the key.
+
+    \sa QTest::keyPress(), QTest::keyClick()
+*/
+
+/*! \fn void QTest::keyRelease(QWidget *widget, char key, Qt::KeyboardModifiers modifier = Qt::NoModifier, int delay=-1)
+    \overload
+
+    Simulates releasing a \a key with an optional \a modifier on a \a widget.
+    If \a delay is larger than 0, the test will wait for \a delay milliseconds
+    before releasing the key.
+
+    \sa QTest::keyClick()
+*/
+
+/*! \fn void QTest::keyRelease(QWindow *window, Qt::Key key, Qt::KeyboardModifiers modifier = Qt::NoModifier, int delay=-1)
+    \overload
+    \since 5.0
+
+    Simulates releasing a \a key with an optional \a modifier on a \a window.
+    If \a delay is larger than 0, the test will wait for \a delay milliseconds
+    before releasing the key.
+
+    \sa QTest::keyPress(), QTest::keyClick()
+*/
+
+/*! \fn void QTest::keyRelease(QWindow *window, char key, Qt::KeyboardModifiers modifier = Qt::NoModifier, int delay=-1)
+    \overload
+    \since 5.0
+
+    Simulates releasing a \a key with an optional \a modifier on a \a window.
+    If \a delay is larger than 0, the test will wait for \a delay milliseconds
+    before releasing the key.
+
+    \sa QTest::keyClick()
+*/
+
+/*! \fn void QTest::keyClicks(QWidget *widget, const QString &sequence, Qt::KeyboardModifiers modifier = Qt::NoModifier, int delay=-1)
+
+    Simulates clicking a \a sequence of keys on a \a
+    widget. Optionally, a keyboard \a modifier can be specified as
+    well as a \a delay (in milliseconds) of the test before each key
+    click.
+
+    Example:
+    \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
+    modifiers and without delay of the test.
+
+    \sa QTest::keyClick()
+*/
+
+/*! \fn void QTest::mousePress(QWidget *widget, Qt::MouseButton button, Qt::KeyboardModifiers modifier = 0, QPoint pos = QPoint(), int delay=-1)
+
+    Simulates pressing a mouse \a button with an optional \a modifier
+    on a \a widget.  The position is defined by \a pos; the default
+    position is the center of the widget. If \a delay is specified,
+    the test will wait for the specified amount of milliseconds before
+    the press.
+
+    \sa QTest::mouseRelease(), QTest::mouseClick()
+*/
+
+/*! \fn void QTest::mousePress(QWindow *window, Qt::MouseButton button, Qt::KeyboardModifiers stateKey = 0, QPoint pos = QPoint(), int delay=-1)
+    \overload
+    \since 5.0
+
+    Simulates pressing a mouse \a button with an optional \a stateKey modifier
+    on a \a window.  The position is defined by \a pos; the default
+    position is the center of the window. If \a delay is specified,
+    the test will wait for the specified amount of milliseconds before
+    the press.
+
+    \sa QTest::mouseRelease(), QTest::mouseClick()
+*/
+
+/*! \fn void QTest::mouseRelease(QWidget *widget, Qt::MouseButton button, Qt::KeyboardModifiers modifier = 0, QPoint pos = QPoint(), int delay=-1)
+
+    Simulates releasing a mouse \a button with an optional \a modifier
+    on a \a widget.  The position of the release is defined by \a pos;
+    the default position is the center of the widget. If \a delay is
+    specified, the test will wait for the specified amount of
+    milliseconds before releasing the button.
+
+    \sa QTest::mousePress(), QTest::mouseClick()
+*/
+
+/*! \fn void QTest::mouseRelease(QWindow *window, Qt::MouseButton button, Qt::KeyboardModifiers stateKey = 0, QPoint pos = QPoint(), int delay=-1)
+    \overload
+    \since 5.0
+
+    Simulates releasing a mouse \a button with an optional \a stateKey modifier
+    on a \a window.  The position of the release is defined by \a pos;
+    the default position is the center of the window. If \a delay is
+    specified, the test will wait for the specified amount of
+    milliseconds before releasing the button.
+
+    \sa QTest::mousePress(), QTest::mouseClick()
+*/
+
+/*! \fn void QTest::mouseClick(QWidget *widget, Qt::MouseButton button, Qt::KeyboardModifiers modifier = 0, QPoint pos = QPoint(), int delay=-1)
+
+    Simulates clicking a mouse \a button with an optional \a modifier
+    on a \a widget.  The position of the click is defined by \a pos;
+    the default position is the center of the widget. If \a delay is
+    specified, the test will wait for the specified amount of
+    milliseconds before pressing and before releasing the button.
+
+    \sa QTest::mousePress(), QTest::mouseRelease()
+*/
+
+/*! \fn void QTest::mouseClick(QWindow *window, Qt::MouseButton button, Qt::KeyboardModifiers stateKey = 0, QPoint pos = QPoint(), int delay=-1)
+    \overload
+    \since 5.0
+
+    Simulates clicking a mouse \a button with an optional \a stateKey modifier
+    on a \a window.  The position of the click is defined by \a pos;
+    the default position is the center of the window. If \a delay is
+    specified, the test will wait for the specified amount of
+    milliseconds before pressing and before releasing the button.
+
+    \sa QTest::mousePress(), QTest::mouseRelease()
+*/
+
+/*! \fn void QTest::mouseDClick(QWidget *widget, Qt::MouseButton button, Qt::KeyboardModifiers modifier = 0, QPoint pos = QPoint(), int delay=-1)
+
+    Simulates double clicking a mouse \a button with an optional \a
+    modifier on a \a widget.  The position of the click is defined by
+    \a pos; the default position is the center of the widget. If \a
+    delay is specified, the test will wait for the specified amount of
+    milliseconds before each press and release.
+
+    \sa QTest::mouseClick()
+*/
+
+/*! \fn void QTest::mouseDClick(QWindow *window, Qt::MouseButton button, Qt::KeyboardModifiers stateKey = 0, QPoint pos = QPoint(), int delay=-1)
+    \overload
+    \since 5.0
+
+    Simulates double clicking a mouse \a button with an optional \a stateKey
+    modifier on a \a window.  The position of the click is defined by
+    \a pos; the default position is the center of the window. If \a
+    delay is specified, the test will wait for the specified amount of
+    milliseconds before each press and release.
+
+    \sa QTest::mouseClick()
+*/
+
+/*! \fn void QTest::mouseMove(QWidget *widget, QPoint pos = QPoint(), int delay=-1)
+
+    Moves the mouse pointer to a \a widget. If \a pos is not
+    specified, the mouse pointer moves to the center of the widget. If
+    a \a delay (in milliseconds) is given, the test will wait before
+    moving the mouse pointer.
+*/
+
+/*! \fn void QTest::mouseMove(QWindow *window, QPoint pos = QPoint(), int delay=-1)
+    \overload
+    \since 5.0
+
+    Moves the mouse pointer to a \a window. If \a pos is not
+    specified, the mouse pointer moves to the center of the window. If
+    a \a delay (in milliseconds) is given, the test will wait before
+    moving the mouse pointer.
+*/
+
+/*!
+    \fn char *QTest::toString(const T &value)
+
+    Returns a textual representation of \a value. This function is used by
+    \l QCOMPARE() to output verbose information in case of a test failure.
+
+    You can add specializations or overloads of this function to your test to enable
+    verbose output.
+
+    \b {Note:} Starting with Qt 5.5, you should prefer to provide a toString() function
+    in the type's namespace instead of specializing this template.
+    If your code needs to continue to work with the QTestLib from Qt 5.4 or
+    earlier, you need to continue to use specialization.
+
+    \b {Note:} The caller of toString() must delete the returned data
+    using \c{delete[]}.  Your implementation should return a string
+    created with \c{new[]} or qstrdup(). The easiest way to do so is to
+    create a QByteArray or QString and calling QTest::toString() on it
+    (see second example below).
+
+    Example for specializing (Qt ≤ 5.4):
+
+    \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
+    MyPoint fails, \l QCOMPARE() will call this function to output the
+    contents of \c MyPoint to the test log.
+
+    Same example, but with overloading (Qt ≥ 5.5):
+
+    \snippet code/src_qtestlib_qtestcase.cpp toString-overload
+
+    \sa QCOMPARE()
+*/
+
+/*!
+    \fn char *QTest::toString(const QLatin1String &string)
+    \overload
+
+    Returns a textual representation of the given \a string.
+*/
+
+/*!
+    \fn char *QTest::toString(const QString &string)
+    \overload
+
+    Returns a textual representation of the given \a string.
+*/
+
+/*!
+    \fn char *QTest::toString(const QByteArray &ba)
+    \overload
+
+    Returns a textual representation of the byte array \a ba.
+
+    \sa QTest::toHexRepresentation()
+*/
+
+/*!
+    \fn char *QTest::toString(const QTime &time)
+    \overload
+
+    Returns a textual representation of the given \a time.
+*/
+
+/*!
+    \fn char *QTest::toString(const QDate &date)
+    \overload
+
+    Returns a textual representation of the given \a date.
+*/
+
+/*!
+    \fn char *QTest::toString(const QDateTime &dateTime)
+    \overload
+
+    Returns a textual representation of the date and time specified by
+    \a dateTime.
+*/
+
+/*!
+    \fn char *QTest::toString(const QChar &character)
+    \overload
+
+    Returns a textual representation of the given \a character.
+*/
+
+/*!
+    \fn char *QTest::toString(const QPoint &point)
+    \overload
+
+    Returns a textual representation of the given \a point.
+*/
+
+/*!
+    \fn char *QTest::toString(const QSize &size)
+    \overload
+
+    Returns a textual representation of the given \a size.
+*/
+
+/*!
+    \fn char *QTest::toString(const QRect &rectangle)
+    \overload
+
+    Returns a textual representation of the given \a rectangle.
+*/
+
+/*!
+    \fn char *QTest::toString(const QUrl &url)
+    \since 4.4
+    \overload
+
+    Returns a textual representation of the given \a url.
+*/
+
+/*!
+    \fn char *QTest::toString(const QPointF &point)
+    \overload
+
+    Returns a textual representation of the given \a point.
+*/
+
+/*!
+    \fn char *QTest::toString(const QSizeF &size)
+    \overload
+
+    Returns a textual representation of the given \a size.
+*/
+
+/*!
+    \fn char *QTest::toString(const QRectF &rectangle)
+    \overload
+
+    Returns a textual representation of the given \a rectangle.
+*/
+
+/*!
+    \fn char *QTest::toString(const QVariant &variant)
+    \overload
+
+    Returns a textual representation of the given \a variant.
+*/
+
+/*!
+    \fn char *QTest::toString(QSizePolicy::ControlType ct)
+    \overload
+    \since 5.5
+
+    Returns a textual representation of control type \a ct.
+*/
+
+/*!
+    \fn char *QTest::toString(QSizePolicy::ControlTypes cts)
+    \overload
+    \since 5.5
+
+    Returns a textual representation of control types \a cts.
+*/
+
+/*!
+    \fn char *QTest::toString(QSizePolicy::Policy p)
+    \overload
+    \since 5.5
+
+    Returns a textual representation of policy \a p.
+*/
+
+/*!
+    \fn char *QTest::toString(QSizePolicy sp)
+    \overload
+    \since 5.5
+
+    Returns a textual representation of size policy \a sp.
+*/
+
+/*! \fn void QTest::qWait(int ms)
+
+    Waits for \a ms milliseconds. While waiting, events will be processed and
+    your test will stay responsive to user interface events or network communication.
+
+    Example:
+    \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.
+
+    \sa QTest::qSleep(), QSignalSpy::wait()
+*/
+
+/*! \fn bool QTest::qWaitForWindowExposed(QWindow *window, int timeout)
+    \since 5.0
+
+    Waits for \a timeout milliseconds or until the \a window is exposed.
+    Returns \c true if \c window is exposed within \a timeout milliseconds, otherwise returns \c false.
+
+    This is mainly useful for asynchronous systems like X11, where a window will be mapped to screen some
+    time after being asked to show itself on the screen.
+
+    \sa QTest::qWaitForWindowActive(), QWindow::isExposed()
+*/
+
+/*! \fn bool QTest::qWaitForWindowActive(QWindow *window, int timeout)
+    \since 5.0
+
+    Waits for \a timeout milliseconds or until the \a window is active.
+
+    Returns \c true if \c window is active within \a timeout milliseconds, otherwise returns \c false.
+
+    \sa QTest::qWaitForWindowExposed(), QWindow::isActive()
+*/
+
+/*! \fn bool QTest::qWaitForWindowExposed(QWidget *widget, int timeout)
+    \since 5.0
+
+    Waits for \a timeout milliseconds or until the \a widget's window is exposed.
+    Returns \c true if \c widget's window is exposed within \a timeout milliseconds, otherwise returns \c false.
+
+    This is mainly useful for asynchronous systems like X11, where a window will be mapped to screen some
+    time after being asked to show itself on the screen.
+
+    \sa QTest::qWaitForWindowActive()
+*/
+
+/*! \fn bool QTest::qWaitForWindowActive(QWidget *widget, int timeout)
+    \since 5.0
+
+    Waits for \a timeout milliseconds or until the \a widget's window is active.
+
+    Returns \c true if \c widget's window is active within \a timeout milliseconds, otherwise returns \c false.
+
+    \sa QTest::qWaitForWindowExposed(), QWidget::isActiveWindow()
+*/
+
+/*! \fn bool QTest::qWaitForWindowShown(QWidget *widget, int timeout)
+    \since 5.0
+    \deprecated
+
+    Waits for \a timeout milliseconds or until the \a widget's window is exposed.
+    Returns \c true if \c widget's window is exposed within \a timeout milliseconds, otherwise returns \c false.
+
+    This function does the same as qWaitForWindowExposed().
+
+    Example:
+    \snippet code/src_qtestlib_qtestcase.cpp 24
+
+    \sa QTest::qWaitForWindowActive(), QTest::qWaitForWindowExposed()
+*/
+
+/*!
+    \class QTest::QTouchEventSequence
+    \inmodule QtTest
+    \since 4.6
+
+    \brief The QTouchEventSequence class is used to simulate a sequence of touch events.
+
+    To simulate a sequence of touch events on a specific device for a window or widget, call
+    QTest::touchEvent to create a QTouchEventSequence instance. Add touch events to
+    the sequence by calling press(), move(), release() and stationary(), and let the
+    instance run out of scope to commit the sequence to the event system.
+
+    Example:
+    \snippet code/src_qtestlib_qtestcase.cpp 25
+*/
+
+/*!
+    \fn QTest::QTouchEventSequence::~QTouchEventSequence()
+
+    Commits this sequence of touch events, unless autoCommit was disabled, and frees allocated resources.
+*/
+
+/*!
+  \fn void QTest::QTouchEventSequence::commit(bool processEvents)
+
+   Commits this sequence of touch events to the event system. Normally there is no need to call this
+   function because it is called from the destructor. However, if autoCommit is disabled, the events
+   only get committed upon explicitly calling this function.
+
+   In special cases tests may want to disable the processing of the events. This can be achieved by
+   setting \a processEvents to false. This results in merely queuing the events, the event loop will
+   not be forced to process them.
+*/
+
+/*!
+    \fn QTouchEventSequence &QTest::QTouchEventSequence::press(int touchId, const QPoint &pt, QWindow *window)
+    \since 5.0
+
+    Adds a press event for touchpoint \a touchId at position \a pt to this sequence and returns
+    a reference to this QTouchEventSequence.
+
+    The position \a pt is interpreted as relative to \a window. If \a window is the null pointer, then
+    \a pt is interpreted as relative to the window provided when instantiating this QTouchEventSequence.
+
+    Simulates that the user pressed the touch screen or pad with the finger identified by \a touchId.
+*/
+
+/*!
+    \fn QTouchEventSequence &QTest::QTouchEventSequence::press(int touchId, const QPoint &pt, QWidget *widget)
+
+    Adds a press event for touchpoint \a touchId at position \a pt to this sequence and returns
+    a reference to this QTouchEventSequence.
+
+    The position \a pt is interpreted as relative to \a widget. If \a widget is the null pointer, then
+    \a pt is interpreted as relative to the widget provided when instantiating this QTouchEventSequence.
+
+    Simulates that the user pressed the touch screen or pad with the finger identified by \a touchId.
+*/
+
+/*!
+    \fn QTouchEventSequence &QTest::QTouchEventSequence::move(int touchId, const QPoint &pt, QWindow *window)
+    \since 5.0
+
+    Adds a move event for touchpoint \a touchId at position \a pt to this sequence and returns
+    a reference to this QTouchEventSequence.
+
+    The position \a pt is interpreted as relative to \a window. If \a window is the null pointer, then
+    \a pt is interpreted as relative to the window provided when instantiating this QTouchEventSequence.
+
+    Simulates that the user moved the finger identified by \a touchId.
+*/
+
+/*!
+    \fn QTouchEventSequence &QTest::QTouchEventSequence::move(int touchId, const QPoint &pt, QWidget *widget)
+
+    Adds a move event for touchpoint \a touchId at position \a pt to this sequence and returns
+    a reference to this QTouchEventSequence.
+
+    The position \a pt is interpreted as relative to \a widget. If \a widget is the null pointer, then
+    \a pt is interpreted as relative to the widget provided when instantiating this QTouchEventSequence.
+
+    Simulates that the user moved the finger identified by \a touchId.
+*/
+
+/*!
+    \fn QTouchEventSequence &QTest::QTouchEventSequence::release(int touchId, const QPoint &pt, QWindow *window)
+    \since 5.0
+
+    Adds a release event for touchpoint \a touchId at position \a pt to this sequence and returns
+    a reference to this QTouchEventSequence.
+
+    The position \a pt is interpreted as relative to \a window. If \a window is the null pointer, then
+    \a pt is interpreted as relative to the window provided when instantiating this QTouchEventSequence.
+
+    Simulates that the user lifted the finger identified by \a touchId.
+*/
+
+/*!
+    \fn QTouchEventSequence &QTest::QTouchEventSequence::release(int touchId, const QPoint &pt, QWidget *widget)
+
+    Adds a release event for touchpoint \a touchId at position \a pt to this sequence and returns
+    a reference to this QTouchEventSequence.
+
+    The position \a pt is interpreted as relative to \a widget. If \a widget is the null pointer, then
+    \a pt is interpreted as relative to the widget provided when instantiating this QTouchEventSequence.
+
+    Simulates that the user lifted the finger identified by \a touchId.
+*/
+
+/*!
+    \fn QTouchEventSequence &QTest::QTouchEventSequence::stationary(int touchId)
+
+    Adds a stationary event for touchpoint \a touchId to this sequence and returns
+    a reference to this QTouchEventSequence.
+
+    Simulates that the user did not move the finger identified by \a touchId.
+*/
+
+/*!
+    \fn QTouchEventSequence QTest::touchEvent(QWindow *window, QTouchDevice *device, bool autoCommit)
+    \since 5.0
+
+    Creates and returns a QTouchEventSequence for the \a device to
+    simulate events for \a window.
+
+    When adding touch events to the sequence, \a window will also be used to translate
+    the position provided to screen coordinates, unless another window is provided in the
+    respective calls to press(), move() etc.
+
+    The touch events are committed to the event system when the destructor of the
+    QTouchEventSequence is called (ie when the object returned runs out of scope), unless
+    \a autoCommit is set to false. When \a autoCommit is false, commit() has to be called
+    manually.
+*/
+
+/*!
+    \fn QTouchEventSequence QTest::touchEvent(QWidget *widget, QTouchDevice *device, bool autoCommit)
+
+    Creates and returns a QTouchEventSequence for the \a device to
+    simulate events for \a widget.
+
+    When adding touch events to the sequence, \a widget will also be used to translate
+    the position provided to screen coordinates, unless another widget is provided in the
+    respective calls to press(), move() etc.
+
+    The touch events are committed to the event system when the destructor of the
+    QTouchEventSequence is called (ie when the object returned runs out of scope), unless
+    \a autoCommit is set to false. When \a autoCommit is false, commit() has to be called
+    manually.
+*/
+
+// Internals of qtestmouse.h:
+
+/*! \fn void QTest::waitForEvents()
+    \internal
+*/
+
+/*! \fn void QTest::mouseEvent(MouseAction action, QWidget *widget, Qt::MouseButton button, Qt::KeyboardModifiers stateKey, QPoint pos, int delay=-1)
+    \internal
+*/
+
+/*! \fn void QTest::mouseEvent(MouseAction action, QWindow *window, Qt::MouseButton button, Qt::KeyboardModifiers stateKey, QPoint pos, int delay=-1)
+    \internal
+*/