From 2e12825b0b4457d709d6d467c84f30ce35336ff3 Mon Sep 17 00:00:00 2001 From: Leena Miettinen Date: Wed, 2 Oct 2019 13:22:39 +0200 Subject: Doc: Describe initTestCase_data() function and QFETCH_GLOBAL macro Fixes: QTBUG-24342 Change-Id: I8f8f3726c5d31e34af9bfe054572c08fc07e01e0 Reviewed-by: Edward Welbourne --- .../doc/snippets/code/src_qtestlib_qtestcase.cpp | 30 ++++++++++++- src/testlib/doc/src/qttestlib-manual.qdoc | 49 ++++++++++++++++++---- src/testlib/qtestcase.qdoc | 33 +++++++++++++-- 3 files changed, 100 insertions(+), 12 deletions(-) (limited to 'src/testlib') diff --git a/src/testlib/doc/snippets/code/src_qtestlib_qtestcase.cpp b/src/testlib/doc/snippets/code/src_qtestlib_qtestcase.cpp index 202f87af52..5f71828595 100644 --- a/src/testlib/doc/snippets/code/src_qtestlib_qtestcase.cpp +++ b/src/testlib/doc/snippets/code/src_qtestlib_qtestcase.cpp @@ -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. @@ -296,3 +296,31 @@ QTest::keyClick(myWindow, Qt::Key_Escape, Qt::ShiftModifier, 200); } +//! [30] +void TestQLocale::initTestCase_data() +{ + QTest::addColumn("locale"); + QTest::newRow("C") << QLocale::c(); + QTest::newRow("UKish") << QLocale("en_GB"); + QTest::newRow("USAish") << QLocale(QLocale::English); +} + +void TestQLocale::roundTripInt_data() +{ + QTest::addColumn("number"); + QTest::newRow("one") << 1; + QTest::newRow("two") << 2; + QTest::newRow("ten") << 10; +} +//! [30] + +//! [31] +void TestQLocale::roundTripInt() +{ + QFETCH_GLOBAL(QLocale, locale); + QFETCH(int, number); + bool ok; + QCOMPARE(locale.toInt(locale.toString(number), &ok), number); + QVERIFY(ok); +} +//! [31] diff --git a/src/testlib/doc/src/qttestlib-manual.qdoc b/src/testlib/doc/src/qttestlib-manual.qdoc index 71b4541313..a3644c1623 100644 --- a/src/testlib/doc/src/qttestlib-manual.qdoc +++ b/src/testlib/doc/src/qttestlib-manual.qdoc @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2016 The Qt Company Ltd. +** Copyright (C) 2019 The Qt Company Ltd. ** Copyright (C) 2016 Intel Corporation. ** Contact: https://www.qt.io/licensing/ ** @@ -89,12 +89,14 @@ private slot is a test function in your test. QTest::qExec() can be used to execute all test functions in the test object. - In addition, there are four private slots that are \e not treated as test functions. - They will be executed by the testing framework and can be used to initialize and - clean up either the entire test or the current test function. + In addition, you can define the following private slots that are \e not + treated as test functions. When present, they will be executed by the + testing framework and can be used to initialize and clean up either the + entire test or the current test function. \list \li \c{initTestCase()} will be called before the first test function is executed. + \li \c{initTestCase_data()} will be called to create a global test data table. \li \c{cleanupTestCase()} will be called after the last test function was executed. \li \c{init()} will be called before each test function is executed. \li \c{cleanup()} will be called after every test function. @@ -365,6 +367,34 @@ See \l {Chapter 5: Writing a Benchmark}{Writing a Benchmark} in the Qt Test Tutorial for more benchmarking examples. + + \section1 Using Global Test Data + + You can define \c{initTestCase_data()} to set up a global test data table. + Each test is run once for each row in the global test data table. When the + test function itself \l{Chapter 2: Data-driven Testing}{is data-driven}, + it is run for each local data row, for each global data row. So, if there + are \c g rows in the global data table and \c d rows in the test's own + data-table, the number of runs of this test is \c g times \c d. + + Global data is fetched from the table using the \l QFETCH_GLOBAL() macro. + + The following are typical use cases for global test data: + + \list + \li Selecting among the available database backends in QSql tests to run + every test against every database. + \li Doing all networking tests with and without SSL (HTTP versus HTTPS) + and proxying. + \li Testing a timer with a high precision clock and with a coarse one. + \li Selecting whether a parser shall read from a QByteArray or from a + QIODevice. + \endlist + + For example, to test each number provided by \c {roundTripInt_data()} with + each locale provided by \c {initTestCase_data()}: + + \snippet code/src_qtestlib_qtestcase.cpp 31 */ /*! @@ -508,10 +538,9 @@ QTest::newRow() function. Each set of data will become a separate row in the test table. - \l QTest::newRow() takes one argument: a name that will be - associated with the data set. If the test fails, the name will be - used in the test log, referencing the failed data. Then we - stream the data set into the new table row. First an arbitrary + \l QTest::newRow() takes one argument: a name that will be associated + with the data set and used in the test log to identify the data set. + Then we stream the data set into the new table row. First an arbitrary string, and then the expected result of applying the QString::toUpper() function to that string. @@ -543,6 +572,10 @@ \li HELLO \endtable + When data is streamed into the row, each datum is asserted to match + the type of the column whose value it supplies. If any assertion fails, + the test is aborted. + \section1 Rewriting the Test Function Our test function can now be rewritten: diff --git a/src/testlib/qtestcase.qdoc b/src/testlib/qtestcase.qdoc index 2af016304d..f3761cdfa8 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: @@ -239,6 +239,33 @@ 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 -- cgit v1.2.3 From 3478f6c4474e86f2431c22533dbffefb48af93a9 Mon Sep 17 00:00:00 2001 From: Leena Miettinen Date: Fri, 11 Oct 2019 16:30:33 +0200 Subject: Doc: Describe using QVERIFY to verify validity of QSignalSpy From https://wiki.qt.io/Writing_Unit_Tests Change-Id: I3186efe30cde465766800aee1f0a530fb80907fb Reviewed-by: Edward Welbourne --- src/testlib/qsignalspy.qdoc | 16 ++++++++++++++-- 1 file changed, 14 insertions(+), 2 deletions(-) (limited to 'src/testlib') diff --git a/src/testlib/qsignalspy.qdoc b/src/testlib/qsignalspy.qdoc index 3352307d69..39639d0a09 100644 --- a/src/testlib/qsignalspy.qdoc +++ b/src/testlib/qsignalspy.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. @@ -48,7 +48,7 @@ \snippet code/doc_src_qsignalspy.cpp 1 - \b {Note:} Non-standard data types need to be registered, using + \note Non-standard data types need to be registered, using the qRegisterMetaType() function, before you can create a QSignalSpy. For example: @@ -57,6 +57,18 @@ To retrieve the instance, you can use qvariant_cast: \snippet code/doc_src_qsignalspy.cpp 3 + + \section1 Verifying Signal Emissions + + The QSignalSpy class provides an elegant mechanism for capturing the list + of signals emitted by an object. However, you should verify its validity + after construction. The constructor does a number of sanity checks, such as + verifying that the signal to be spied upon actually exists. To make the + diagnosis of test failures easier, the results of these checks should be + checked by calling \c QVERIFY(spy.isValid()) before proceeding further with + a test. + + \sa QVERIFY() */ /*! \fn QSignalSpy::QSignalSpy(const QObject *object, const char *signal) -- cgit v1.2.3 From a9dcd772c032b5cb52f86e6cd898db3d3bc81023 Mon Sep 17 00:00:00 2001 From: Leena Miettinen Date: Fri, 18 Oct 2019 16:11:55 +0200 Subject: Doc: Replace \b {Note:} with \note Change-Id: I1f6947acec4494c151317e1faf79720dad0da6bb Reviewed-by: Martin Smith --- src/testlib/doc/src/qttestlib-manual.qdoc | 4 +--- src/testlib/qtestcase.qdoc | 24 ++++++++++++------------ 2 files changed, 13 insertions(+), 15 deletions(-) (limited to 'src/testlib') diff --git a/src/testlib/doc/src/qttestlib-manual.qdoc b/src/testlib/doc/src/qttestlib-manual.qdoc index a3644c1623..ee7767b5a5 100644 --- a/src/testlib/doc/src/qttestlib-manual.qdoc +++ b/src/testlib/doc/src/qttestlib-manual.qdoc @@ -355,15 +355,13 @@ counters can be obtained by running any benchmark executable with the option \c -perfcounterlist. - \list - \li \b Notes: + \note \list \li Using the performance counter may require enabling access to non-privileged applications. \li Devices that do not support high-resolution timers default to one-millisecond granularity. \endlist - \endlist See \l {Chapter 5: Writing a Benchmark}{Writing a Benchmark} in the Qt Test Tutorial for more benchmarking examples. diff --git a/src/testlib/qtestcase.qdoc b/src/testlib/qtestcase.qdoc index f3761cdfa8..9006d7b401 100644 --- a/src/testlib/qtestcase.qdoc +++ b/src/testlib/qtestcase.qdoc @@ -235,7 +235,7 @@ \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. */ @@ -282,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: @@ -359,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: @@ -421,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 @@ -449,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 @@ -689,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() */ @@ -701,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() */ @@ -713,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() */ @@ -726,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() */ @@ -947,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 -- cgit v1.2.3