1// Copyright (C) 2023 The Qt Company Ltd.
2// Copyright (C) 2016 Intel Corporation.
3// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
6 \page qttestlib-tutorial2-example.html
7 \previouspage {Chapter 1: Writing a Unit Test}{Chapter 1}
8 \nextpage {Chapter 3: Simulating Gui Events}{Chapter 3}
10 \title Chapter 2: Data Driven Testing
11 \brief How to create data driven tests.
13 This chapter demonstrates how to execute a test multiple times with
16 So far, we have hard coded the data we wanted to test into our
17 test function. If we add more test data, the function might look like
20 \snippet code/doc_src_qtestlib.cpp 11
22 To prevent the function from being cluttered with repetitive code, Qt Test
23 supports adding test data to a test function. All we need is to add another
24 private slot to our test class:
26 \snippet tutorial2/testqstring.cpp 0
28 \section1 Writing the Data Function
30 A test function's associated data function has \c _data appended to its
31 name. Our data function looks like this:
33 \snippet tutorial2/testqstring.cpp 1
35 First, we define the two elements of our test table using the \l
36 QTest::addColumn() function: a test string and the
37 expected result of applying the QString::toUpper() function to
40 Then, we add some data to the table using the \l QTest::newRow()
41 function. We can also use \l QTest::addRow() if we need to format some data
42 in the row name, for example when generating many data rows iteratively.
43 Each row of data will become a separate row in the test table.
45 \l QTest::newRow() takes one argument: a name that will be associated with
46 the data set and used in the test log to identify the data row. \l
47 QTest::addRow() takes a (\c{printf}-style) format string followed by the
48 parameters to be represented in place of the formatting tokens in the format
49 string. Then, we stream the data set into the new table row. First an
50 arbitrary string, and then the expected result of applying the
51 QString::toUpper() function to that string.
53 You can think of the test data as a two-dimensional table. In
54 our case, it has two columns called \c string and \c result and
55 three rows. In addition, a name and an index are associated
81 When data is streamed into the row, each datum is asserted to match
82 the type of the column whose value it supplies. If any assertion fails,
85 The names of rows and columns, in a given test function's data table, should
86 be unique: if two rows share a name, or two columns share a name, a warning
87 will (since Qt 6.5) be produced. See \l qWarning() for how you can cause
88 warnings to be treated as errors and \l {Test for Warnings} for how to get
89 your tests clear of other warnings.
91 \section1 Rewriting the Test Function
93 Our test function can now be rewritten:
95 \snippet tutorial2/testqstring.cpp 2
97 The TestQString::toUpper() function will be executed three times,
98 once for each entry in the test table that we created in the
99 associated TestQString::toUpper_data() function.
101 First, we fetch the two elements of the data set using the \l
102 QFETCH() macro. \l QFETCH() takes two arguments: The data type of
103 the element and the element name. Then, we perform the test using
104 the \l QCOMPARE() macro.
106 This approach makes it very easy to add new data to the test
107 without modifying the test itself.
109 \section1 Preparing the Stand-Alone Executable
111 And again, to make our test case a stand-alone executable,
112 the following two lines are needed:
114 \snippet tutorial2/testqstring.cpp 3
116 As before, the QTEST_MAIN() macro expands to a simple main()
117 method that runs all the test functions, and since both the
118 declaration and the implementation of our test class are in a .cpp
119 file, we also need to include the generated moc file to make Qt's
122 \section1 Building the Executable
124 \include {building-examples.qdocinc} {building the executable} {tutorial2}
126 \section1 Running the Executable
128 Running the resulting executable should give you the following
131 \snippet code/doc_src_qtestlib.qdoc 11