diff options
Diffstat (limited to 'src/testlib/doc')
| -rw-r--r-- | src/testlib/doc/includes/building-examples.qdocinc | 41 | ||||
| -rw-r--r-- | src/testlib/doc/qttestlib.qdocconf | 3 | ||||
| -rw-r--r-- | src/testlib/doc/snippets/code/doc_src_qtestlib.qdoc | 51 | ||||
| -rw-r--r-- | src/testlib/doc/src/qttestlib-manual.qdoc | 116 |
4 files changed, 177 insertions, 34 deletions
diff --git a/src/testlib/doc/includes/building-examples.qdocinc b/src/testlib/doc/includes/building-examples.qdocinc new file mode 100644 index 0000000000..ab845dd482 --- /dev/null +++ b/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] diff --git a/src/testlib/doc/qttestlib.qdocconf b/src/testlib/doc/qttestlib.qdocconf index d359eff143..fe80362cca 100644 --- a/src/testlib/doc/qttestlib.qdocconf +++ b/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 diff --git a/src/testlib/doc/snippets/code/doc_src_qtestlib.qdoc b/src/testlib/doc/snippets/code/doc_src_qtestlib.qdoc index bd58d0493b..93bf5111a0 100644 --- a/src/testlib/doc/snippets/code/doc_src_qtestlib.qdoc +++ b/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] diff --git a/src/testlib/doc/src/qttestlib-manual.qdoc b/src/testlib/doc/src/qttestlib-manual.qdoc index 4c67c34d23..c99c947253 100644 --- a/src/testlib/doc/src/qttestlib-manual.qdoc +++ b/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 - features of the Qt Test framework. It is divided into five - chapters: + This tutorial introduces some of the features of the Qt Test framework. It + is divided into six 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 - for a class, and how to execute it. + This first chapter demonstrates how to write a simple unit test and how to + 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 - - Now that we finished writing our test, we want to execute - it. Assuming that our test was saved as \c testqstring.cpp in an - empty directory, we build the test using \c qmake to create a - project and generate a makefile. + \section1 Building the Executable - \snippet code/doc_src_qtestlib.qdoc 9 + \include {building-examples.qdocinc} {building the executable} {tutorial1} \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 - multiple times with different test data. + This chapter demonstrates how to execute a test multiple times with + different test data. So far, we have hard coded the data we wanted to test into our test function. If we add more test data, the function might look like @@ -628,37 +630,37 @@ \snippet code/doc_src_qtestlib.cpp 11 - To prevent that the function ends up being cluttered by repetitive - code, Qt Test supports adding test data to a test function. All - we need is to add another private slot to our test class: + To prevent the function from being cluttered with repetitive code, Qt Test + supports adding test data to a test function. All we need is to add another + 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, - appended by \c{_data}. Our data function looks like this: + A test function's associated data function has \c _data appended to its + 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 - QLineEdit. Then we simulate writing "hello world" in the line edit + In the implementation of the test function, we first create a + QLineEdit. Then, we simulate writing "hello world" in the line edit using the \l QTest::keyClicks() function. \note The widget must also be shown in order to correctly test keyboard @@ -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 - using Qt Test. + This final demonstrates how to write benchmarks using Qt Test. \section1 Writing a Benchmark To create a benchmark we extend a test function with a QBENCHMARK macro. @@ -878,9 +918,9 @@ \snippet tutorial5/benchmarking.cpp 0 - Setup can be done at the beginning of the function, the clock is not - running at this point. The code inside the QBENCHMARK macro will be - measured, and possibly repeated several times in order to get an + Setup can be done at the beginning of the function. At this point, the clock + is not running. The code inside the QBENCHMARK macro will be + measured, and possibly repeated several times in order to get an accurate measurement. Several \l {testlib-benchmarking-measurement}{back-ends} are available @@ -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 |