summaryrefslogtreecommitdiffstats
path: root/src/testlib/qtestcase.qdoc
diff options
context:
space:
mode:
authorQt Forward Merge Bot <qt_forward_merge_bot@qt-project.org>2019-10-24 01:00:14 +0200
committerEdward Welbourne <edward.welbourne@qt.io>2019-10-24 10:23:44 +0200
commitb327807c5ed6f151bfb22c2fe204ed289a3b6254 (patch)
tree880a0e7664e1270f4f51ccf79a3cf2ddbcd7d810 /src/testlib/qtestcase.qdoc
parentaa4b0f5cb7e84046530fbc26581f777506fea658 (diff)
parentb61c6164c100defc519b178d73858df59cffc48d (diff)
Merge remote-tracking branch 'origin/5.13' into 5.14
Conflicts: src/corelib/io/qstandardpaths_unix.cpp src/corelib/tools/qsharedpointer_impl.h tests/auto/corelib/tools/qsharedpointer/tst_qsharedpointer.cpp Change-Id: Iae95c5778dc091058f16f6db76f04a0178a9e809
Diffstat (limited to 'src/testlib/qtestcase.qdoc')
-rw-r--r--src/testlib/qtestcase.qdoc57
1 files changed, 42 insertions, 15 deletions
diff --git a/src/testlib/qtestcase.qdoc b/src/testlib/qtestcase.qdoc
index 2af016304d..9006d7b401 100644
--- a/src/testlib/qtestcase.qdoc
+++ b/src/testlib/qtestcase.qdoc
@@ -1,6 +1,6 @@
/****************************************************************************
**
-** Copyright (C) 2016 The Qt Company Ltd.
+** Copyright (C) 2019 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of the documentation of the Qt Toolkit.
@@ -220,8 +220,8 @@
\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.
+ on the stack. The \a name and \a type must match a column from the test's
+ data table. This is asserted and the test will abort if the assertion fails.
Assuming a test has the following data:
@@ -235,10 +235,37 @@
\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
+ \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 QFETCH_GLOBAL(type, name)
+
+ \relates QTest
+
+ This macro fetches a variable named \a name with the type \a type from
+ a row in the global data table. The \a name and \a type must match a
+ column in the global data table. This is asserted and the test will abort
+ if the assertion fails.
+
+ Assuming a test has the following data:
+
+ \snippet code/src_qtestlib_qtestcase.cpp 30
+
+ The test's own data is a single number per row. In this case,
+ \c initTestCase_data() also supplies a locale per row. Therefore,
+ this test will be run with every combination of locale from the
+ latter and number from the former.
+
+ \snippet code/src_qtestlib_qtestcase.cpp 31
+
+ The locale is read from the global data table using QFETCH_GLOBAL(),
+ and the number is read from the local data table using QFETCH().
+
+ \note This macro can only be used in test methods of a class with an
+ \c initTestCase_data() method.
+*/
+
/*! \macro QWARN(message)
\relates QTest
@@ -255,7 +282,7 @@
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
+ \note This macro can only be used in a test function that is invoked
by the test framework.
Example:
@@ -332,7 +359,7 @@
\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
+ \note This macro can only be used in a test function that is invoked
by the test framework.
Example 1:
@@ -394,13 +421,13 @@
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
+ \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
+ \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
@@ -422,7 +449,7 @@
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,
+ \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
@@ -662,7 +689,7 @@
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().
+ \note At some point you should release the key using \l keyRelease().
\sa QTest::keyRelease(), QTest::keyClick()
*/
@@ -674,7 +701,7 @@
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().
+ \note At some point you should release the key using \l keyRelease().
\sa QTest::keyRelease(), QTest::keyClick()
*/
@@ -686,7 +713,7 @@
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().
+ \note At some point you should release the key using \l keyRelease().
\sa QTest::keyRelease(), QTest::keyClick()
*/
@@ -699,7 +726,7 @@
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().
+ \note At some point you should release the key using \l keyRelease().
\sa QTest::keyRelease(), QTest::keyClick()
*/
@@ -920,12 +947,12 @@
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
+ \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
+ \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