Doc: Revise Qt Test tutorial

- Make it explicit that each chapter can be run as a stand-alone test
application
- Add a CMake section on how to build the executable

Task-number: QTBUG-103730
Change-Id: Id4c87c454521f698dcf16cfdc176318dd3e16786
Reviewed-by: Kai Koehne <kai.koehne@qt.io>
(cherry picked from commit ac171469a0021b5ddabd0197c31b814fbbaad16a)
Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>

src/testlib/doc/includes/building-examples.qdocinc

@@ -0,0 +1,41 @@
+// Copyright (C) 2022 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR
+// GFDL-1.3-no-invariants-only
+
+//! [building the executable]
+    You can build the test case executable using CMake or qmake.
+
+    \section2 Building with CMake
+
+    Configure your build settings in your CMakeLists.txt file:
+
+    \quotefile \1/CMakeLists.txt
+
+    Next, from the command line, run either \c cmake or use the \c qt-cmake
+    convenience script located in
+    \c Qt-prefix/<version>/<platform>/bin/qt-cmake:
+
+    \badcode
+        <Qt-prefix>/<version>/<platform>/bin/qt-cmake <source-dir> <build-dir> -G Ninja
+    \endcode
+
+    Then, run your preferred generator tool to build the executable. Here, we're
+    using Ninja:
+
+    \badcode
+        ninja
+    \endcode
+
+    \section2 Building with qmake
+
+    Configure your build settings in your \c .pro file:
+
+    \quotefile \1/\1.pro
+
+    Next, run \c qmake, and, finally, run \c make to build your executable:
+
+    \badcode
+        qmake
+        make
+    \endcode
+//! [building the executable]

src/testlib/doc/qttestlib.qdocconf

@@ -41,7 +41,8 @@ sources     += ../../corelib/kernel/qtestsupport_core.cpp \
 exampledirs += ../../../examples/qtestlib \
                .. \
                . \
-               snippets
+               snippets \
+               includes
 
 excludedirs += ../../../examples/widgets/doc
 

src/testlib/doc/snippets/code/doc_src_qtestlib.qdoc

@@ -49,3 +49,54 @@ PASS   : TestQString::cleanupTestCase()
 Totals: 3 passed, 0 failed, 0 skipped
 ********* Finished testing of TestQString *********
 //! [10]
+
+//! [11]
+********* Start testing of TestQString *********
+Config: Using QtTest library %VERSION%, Qt %VERSION%
+PASS   : TestQString::initTestCase()
+PASS   : TestQString::toUpper(all lower)
+PASS   : TestQString::toUpper(mixed)
+PASS   : TestQString::toUpper(all upper)
+PASS   : TestQString::cleanupTestCase()
+Totals: 5 passed, 0 failed, 0 skipped, 0 blacklisted, 0ms
+********* Finished testing of TestQString *********
+//! [11]
+
+//! [12]
+********* Start testing of TestGui *********
+Config: Using QtTest library %VERSION%, Qt %VERSION%
+PASS   : TestGui::initTestCase()
+PASS   : TestGui::testGui()
+PASS   : TestGui::cleanupTestCase()
+Totals: 3 passed, 0 failed, 0 skipped, 0 blacklisted, 20ms
+********* Finished testing of TestGui **
+//! [12]
+
+//! [13]
+********* Start testing of TestGui *********
+Config: Using QtTest library %VERSION%, Qt %VERSION%
+PASS   : TestGui::initTestCase()
+PASS   : TestGui::testGui(char)
+PASS   : TestGui::testGui(there and back again)
+PASS   : TestGui::cleanupTestCase()
+Totals: 4 passed, 0 failed, 0 skipped, 0 blacklisted, 18ms
+********* Finished testing of TestGui *********
+//! [13]
+
+//! [14]
+********* Start testing of TestBenchmark *********
+Config: Using QtTest library %VERSION%, Qt %VERSION%
+PASS   : TestBenchmark::initTestCase()
+PASS   : TestBenchmark::simple()
+RESULT : TestBenchmark::simple():
+     0.00030 msecs per iteration (total: 79, iterations: 262144)
+PASS   : TestBenchmark::multiple(locale aware compare)
+RESULT : TestBenchmark::multiple():"locale aware compare":
+     0.00029 msecs per iteration (total: 78, iterations: 262144)
+.....
+PASS   : TestBenchmark::series(locale aware compare--8001)
+RESULT : TestBenchmark::series():"locale aware compare--8001":
+     0.039 msecs per iteration (total: 81, iterations: 2048)
+Totals: 15 passed, 0 failed, 0 skipped, 0 blacklisted, 3971ms
+********* Finished testing of TestBenchmark *********
+//! [14]

src/testlib/doc/src/qttestlib-manual.qdoc

@@ -1,4 +1,4 @@
-// Copyright (C) 2019 The Qt Company Ltd.
+// Copyright (C) 2022 The Qt Company Ltd.
 // Copyright (C) 2016 Intel Corporation.
 // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
 
@@ -520,9 +520,8 @@
 
     \title Qt Test Tutorial
 
-    This tutorial gives a short introduction to how to use some of the
+    This tutorial introduces some of the features of the Qt Test framework. It
-    features of the Qt Test framework. It is divided into five
+    is divided into six chapters:
-    chapters:
 
     \list 1
     \li \l {Chapter 1: Writing a Unit Test}{Writing a Unit Test}
@@ -533,19 +532,23 @@
     \li \l {Chapter 6: Skipping Tests with QSKIP}{Skipping Tests}
     \endlist
 
+    \note You can build and execute the tests from each chapter using the
+    available source code, which is linked to at the end of each chapter.
+
 */
 
 
 /*!
     \example tutorial1
 
+    \previouspage {Qt Test Tutorial}{Qt Test Tutorial Overview}
     \nextpage {Chapter 2: Data Driven Testing}{Chapter 2}
 
     \title Chapter 1: Writing a Unit Test
     \brief How to write a unit test.
 
-    In this first chapter we will see how to write a simple unit test
+    This first chapter demonstrates how to write a simple unit test and how to
-    for a class, and how to execute it.
+    run the test case as a stand-alone executable.
 
     \section1 Writing a Test
 
@@ -578,6 +581,8 @@
     appended to the test log, making it immediately visible why the
     comparison failed.
 
+    \section1 Preparing the Stand-Alone Executable
+
     Finally, to make our test case a stand-alone executable, the
     following two lines are needed:
 
@@ -589,18 +594,15 @@
     .cpp file, we also need to include the generated moc file to make
     Qt's introspection work.
 
-    \section1 Executing a Test
+    \section1 Building the Executable
 
-    Now that we finished writing our test, we want to execute
+    \include {building-examples.qdocinc} {building the executable} {tutorial1}
-    it. Assuming that our test was saved as \c testqstring.cpp in an
-    empty directory, we build the test using \c qmake to create a
-    project and generate a makefile.
-
-    \snippet code/doc_src_qtestlib.qdoc 9
 
     \note If you're using windows, replace \c make with \c
     nmake or whatever build tool you use.
 
+    \section1 Running the Executable
+
     Running the resulting executable should give you the following
     output:
 
@@ -619,8 +621,8 @@
     \title Chapter 2: Data Driven Testing
     \brief How to create data driven tests.
 
-    In this chapter we will demonstrate how to execute a test
+    This chapter demonstrates how to execute a test multiple times with
-    multiple times with different test data.
+    different test data.
 
     So far, we have hard coded the data we wanted to test into our
     test function. If we add more test data, the function might look like
@@ -628,37 +630,37 @@
 
     \snippet code/doc_src_qtestlib.cpp 11
 
-    To prevent that the function ends up being cluttered by repetitive
+    To prevent the function from being cluttered with repetitive code, Qt Test
-    code, Qt Test supports adding test data to a test function. All
+    supports adding test data to a test function. All we need is to add another
-    we need is to add another private slot to our test class:
+    private slot to our test class:
 
     \snippet tutorial2/testqstring.cpp 0
 
     \section1 Writing the Data Function
 
-    A test function's associated data function carries the same name,
+    A test function's associated data function has \c _data appended to its
-    appended by \c{_data}. Our data function looks like this:
+    name. Our data function looks like this:
 
     \snippet tutorial2/testqstring.cpp 1
 
     First, we define the two elements of our test table using the \l
-    QTest::addColumn() function: a test string, and the
+    QTest::addColumn() function: a test string and the
     expected result of applying the QString::toUpper() function to
     that string.
 
-    Then we add some data to the table using the \l
+    Then, we add some data to the table using the \l
     QTest::newRow() function. Each set of data will become a
     separate row in the test table.
 
     \l QTest::newRow() takes one argument: a name that will be associated
     with the data set 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
+    Then, we stream the data set into the new table row. First an arbitrary
     string, and then the expected result of applying the
     QString::toUpper() function to that string.
 
     You can think of the test data as a two-dimensional table. In
     our case, it has two columns called \c string and \c result and
-    three rows. In addition a name as well as an index is associated
+    three rows. In addition, a name and an index are associated
     with each row:
 
     \table
@@ -700,12 +702,14 @@
 
     First, we fetch the two elements of the data set using the \l
     QFETCH() macro. \l QFETCH() takes two arguments: The data type of
-    the element and the element name. Then we perform the test using
+    the element and the element name. Then, we perform the test using
     the \l QCOMPARE() macro.
 
     This approach makes it very easy to add new data to the test
     without modifying the test itself.
 
+    \section1 Preparing the Stand-Alone Executable
+
     And again, to make our test case a stand-alone executable,
     the following two lines are needed:
 
@@ -716,6 +720,17 @@
     declaration and the implementation of our test class are in a .cpp
     file, we also need to include the generated moc file to make Qt's
     introspection work.
+
+    \section1 Building the Executable
+
+    \include {building-examples.qdocinc} {building the executable} {tutorial2}
+
+    \section1 Running the Executable
+
+    Running the resulting executable should give you the following
+    output:
+
+    \snippet code/doc_src_qtestlib.qdoc 11
 */
 
 /*!
@@ -732,7 +747,7 @@
     Qt Test sends internal Qt events. That means there are no
     side-effects on the machine the tests are running on.
 
-    In this chapter we will see how to write a simple GUI test.
+    This chapter demonstrates how to write a simple GUI test.
 
     \section1 Writing a GUI Test
 
@@ -747,8 +762,8 @@
 
     \snippet tutorial3/testgui.cpp 1
 
-    In the implementation of the test function we first create a
+    In the implementation of the test function, we first create a
-    QLineEdit. Then we simulate writing "hello world" in the line edit
+    QLineEdit. Then, we simulate writing "hello world" in the line edit
     using the \l QTest::keyClicks() function.
 
     \note The widget must also be shown in order to correctly test keyboard
@@ -766,6 +781,8 @@
     Finally, we use the \l QCOMPARE() macro to check if the line edit's
     text is as expected.
 
+    \section1 Preparing the Stand-Alone Executable
+
     As before, to make our test case a stand-alone executable, the
     following two lines are needed:
 
@@ -776,6 +793,17 @@
     the implementation of our test class are in a .cpp file, we also
     need to include the generated moc file to make Qt's introspection
     work.
+
+    \section1 Building the Executable
+
+    \include {building-examples.qdocinc} {building the executable} {tutorial3}
+
+    \section1 Running the Executable
+
+    Running the resulting executable should give you the following
+    output:
+
+    \snippet code/doc_src_qtestlib.qdoc 12
 */
 
 /*!
@@ -846,6 +874,8 @@
     Finally, we use the QCOMPARE() macro to check if the line edit's
     text is as expected.
 
+    \section1 Preparing the Stand-Alone Executable
+
     As before, to make our test case a stand-alone executable,
     the following two lines are needed:
 
@@ -856,6 +886,17 @@
     the implementation of our test class are in a .cpp file, we also
     need to include the generated moc file to make Qt's introspection
     work.
+
+    \section1 Building the Executable
+
+    \include {building-examples.qdocinc} {building the executable} {tutorial4}
+
+    \section1 Running the Executable
+
+    Running the resulting executable should give you the following
+    output:
+
+    \snippet code/doc_src_qtestlib.qdoc 13
 */
 
 /*!
@@ -867,8 +908,7 @@
     \title Chapter 5: Writing a Benchmark
     \brief How to write a benchmark.
 
-    In this final chapter we will demonstrate how to write benchmarks
+    This final demonstrates how to write benchmarks using Qt Test.
-    using Qt Test.
 
     \section1 Writing a Benchmark
     To create a benchmark we extend a test function with a QBENCHMARK macro.
@@ -878,8 +918,8 @@
 
     \snippet tutorial5/benchmarking.cpp 0
 
-    Setup can be done at the beginning of the function, the clock is not
+    Setup can be done at the beginning of the function. At this point, the clock
-    running at this point. The code inside the QBENCHMARK macro will be
+    is not running. The code inside the QBENCHMARK macro will be
     measured, and possibly repeated several times in order to get an
     accurate measurement.
 
@@ -912,6 +952,16 @@
     See the \l{qtestlib-tools Announcement}{qtestlib-tools announcement}
     for more information on these tools and a simple graphing example.
 
+    \section1 Building the Executable
+
+    \include {building-examples.qdocinc} {building the executable} {tutorial5}
+
+    \section1 Running the Executable
+
+    Running the resulting executable should give you the following
+    output:
+
+    \snippet code/doc_src_qtestlib.qdoc 14
 */
 /*!
     \page qttestlib-tutorial6.html