1berry/qtbase
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Doc: Revise Qt Test tutorial

Browse Source 
- 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>
This commit is contained in:
Andreas Eliasson 2022-06-03 14:55:04 +02:00 committed by Qt Cherry-pick Bot
parent 5f25bbb632
commit 7666b58b6b
4 changed files with 177 additions and 34 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

41
src/testlib/doc/includes/building-examples.qdocinc Normal file
View File

@ -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]

3
src/testlib/doc/qttestlib.qdocconf
View File

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

51
src/testlib/doc/snippets/code/doc_src_qtestlib.qdoc
View File

@ -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]

114
src/testlib/doc/src/qttestlib-manual.qdoc
View File

@ -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
\section1 Building the Executable
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.
\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,8 +918,8 @@
\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
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.
@ -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