← Back to branch summary

~ubuntu-branches/ubuntu/wily/qtbase-opensource-src/wily

« back to all changes in this revision

Viewing changes to src/testlib/doc/src/qttestlib-manual.qdoc

  • Committer: Package Import Robot
  • Author(s): Timo Jyrinki
  • Date: 2013-02-05 12:46:17 UTC
  • Revision ID: package-import@ubuntu.com-20130205124617-c8jouts182j002fx
Tags: upstream-5.0.1+dfsg
Import upstream version 5.0.1+dfsg

Show diffs side-by-side

added added

removed removed

Lines of Context:
src/testlib/doc/src/qttestlib-manual.qdoc
 
1
/****************************************************************************
 
2
**
 
3
** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies).
 
4
** Contact: http://www.qt-project.org/legal
 
5
**
 
6
** This file is part of the documentation of the Qt Toolkit.
 
7
**
 
8
** $QT_BEGIN_LICENSE:FDL$
 
9
** Commercial License Usage
 
10
** Licensees holding valid commercial Qt licenses may use this file in
 
11
** accordance with the commercial license agreement provided with the
 
12
** Software or, alternatively, in accordance with the terms contained in
 
13
** a written agreement between you and Digia.  For licensing terms and
 
14
** conditions see http://qt.digia.com/licensing.  For further information
 
15
** use the contact form at http://qt.digia.com/contact-us.
 
16
**
 
17
** GNU Free Documentation License Usage
 
18
** Alternatively, this file may be used under the terms of the GNU Free
 
19
** Documentation License version 1.3 as published by the Free Software
 
20
** Foundation and appearing in the file included in the packaging of
 
21
** this file.  Please review the following information to ensure
 
22
** the GNU Free Documentation License version 1.3 requirements
 
23
** will be met: http://www.gnu.org/copyleft/fdl.html.
 
24
** $QT_END_LICENSE$
 
25
**
 
26
****************************************************************************/
 
27
 
 
28
/*!
 
29
    \page qtest-overview.html
 
30
    \title Qt Test Overview
 
31
    \brief Overview of the Qt unit testing framework.
 
32
 
 
33
    \ingroup frameworks-technologies
 
34
    \ingroup qt-basic-concepts
 
35
 
 
36
    \keyword qtestlib
 
37
 
 
38
    Qt Test is a framework for unit testing Qt based applications and libraries.
 
39
    Qt Test provides
 
40
    all the functionality commonly found in unit testing frameworks as
 
41
    well as extensions for testing graphical user interfaces.
 
42
 
 
43
    Qt Test is designed to ease the writing of unit tests for Qt
 
44
    based applications and libraries:
 
45
 
 
46
    \table
 
47
    \header \li Feature \li Details
 
48
    \row
 
49
        \li \b Lightweight
 
50
        \li Qt Test consists of about 6000 lines of code and 60
 
51
           exported symbols.
 
52
    \row
 
53
        \li \b Self-contained
 
54
        \li Qt Test requires only a few symbols from the Qt Core library
 
55
           for non-gui testing.
 
56
    \row
 
57
        \li \b {Rapid testing}
 
58
        \li Qt Test needs no special test-runners; no special
 
59
           registration for tests.
 
60
    \row
 
61
        \li \b {Data-driven testing}
 
62
        \li A test can be executed multiple times with different test data.
 
63
    \row
 
64
        \li \b {Basic GUI testing}
 
65
        \li Qt Test offers functionality for mouse and keyboard simulation.
 
66
    \row
 
67
        \li \b {Benchmarking}
 
68
        \li Qt Test supports benchmarking and provides several measurement back-ends.
 
69
    \row
 
70
         \li \b {IDE friendly}
 
71
         \li Qt Test outputs messages that can be interpreted by Visual
 
72
            Studio and KDevelop.
 
73
    \row
 
74
         \li \b Thread-safety
 
75
         \li The error reporting is thread safe and atomic.
 
76
    \row
 
77
         \li \b Type-safety
 
78
         \li Extensive use of templates prevent errors introduced by
 
79
            implicit type casting.
 
80
    \row
 
81
         \li \b {Easily extendable}
 
82
         \li Custom types can easily be added to the test data and test output.
 
83
    \endtable
 
84
 
 
85
    \section1 Creating a Test
 
86
 
 
87
    To create a test, subclass QObject and add one or more private slots to it. Each
 
88
    private slot is a test function in your test. QTest::qExec() can be used to execute
 
89
    all test functions in the test object.
 
90
 
 
91
    In addition, there are four private slots that are \e not treated as test functions.
 
92
    They will be executed by the testing framework and can be used to initialize and
 
93
    clean up either the entire test or the current test function.
 
94
 
 
95
    \list
 
96
    \li \c{initTestCase()} will be called before the first test function is executed.
 
97
    \li \c{cleanupTestCase()} will be called after the last test function was executed.
 
98
    \li \c{init()} will be called before each test function is executed.
 
99
    \li \c{cleanup()} will be called after every test function.
 
100
    \endlist
 
101
 
 
102
    If \c{initTestCase()} fails, no test function will be executed. If \c{init()} fails,
 
103
    the following test function will not be executed, the test will proceed to the next
 
104
    test function.
 
105
 
 
106
    Example:
 
107
    \snippet code/doc_src_qtestlib.cpp 0
 
108
 
 
109
    For more examples, refer to the \l{Qt Test Tutorial}.
 
110
 
 
111
    \section1 Building a Test
 
112
 
 
113
    If you are using \c qmake as your build tool, just add the
 
114
    following to your project file:
 
115
 
 
116
    \snippet code/doc_src_qtestlib.pro 1
 
117
 
 
118
    If you would like to run the test via \c{make check}, add the
 
119
    additional line:
 
120
 
 
121
    \snippet code/doc_src_qtestlib.pro 2
 
122
 
 
123
    See \l{qmake Common Projects#building-a-testcase}{the qmake manual} for
 
124
    more information about \c{make check}.
 
125
 
 
126
    If you are using other build tools, make sure that you add the location
 
127
    of the Qt Test header files to your include path (usually \c{include/QtTest}
 
128
    under your Qt installation directory). If you are using a release build
 
129
    of Qt, link your test to the \c QtTest library. For debug builds, use
 
130
    \c{QtTest_debug}.
 
131
 
 
132
    See \l {Chapter 1: Writing a Unit Test}{Writing a Unit Test} for a step by
 
133
    step explanation.
 
134
 
 
135
    \section1 Qt Test Command Line Arguments
 
136
 
 
137
    \section2 Syntax
 
138
 
 
139
    The syntax to execute an autotest takes the following simple form:
 
140
 
 
141
    \snippet code/doc_src_qtestlib.qdoc 2
 
142
 
 
143
    Substitute \c testname with the name of your executable. \c
 
144
    testfunctions can contain names of test functions to be
 
145
    executed. If no \c testfunctions are passed, all tests are run. If you
 
146
    append the name of an entry in \c testdata, the test function will be
 
147
    run only with that test data.
 
148
 
 
149
    For example:
 
150
 
 
151
    \snippet code/doc_src_qtestlib.qdoc 3
 
152
 
 
153
    Runs the test function called \c toUpper with all available test data.
 
154
 
 
155
    \snippet code/doc_src_qtestlib.qdoc 4
 
156
 
 
157
    Runs the \c toUpper test function with all available test data,
 
158
    and the \c toInt test function with the test data called \c
 
159
    zero (if the specified test data doesn't exist, the associated test
 
160
    will fail).
 
161
 
 
162
    \snippet code/doc_src_qtestlib.qdoc 5
 
163
 
 
164
    Runs the \c testMyWidget function test, outputs every signal
 
165
    emission and waits 500 milliseconds after each simulated
 
166
    mouse/keyboard event.
 
167
 
 
168
    \section2 Options
 
169
 
 
170
    \section3 Logging Options
 
171
 
 
172
    The following command line options determine how test results are reported:
 
173
 
 
174
    \list
 
175
    \li \c -o \e{filename,format} \br
 
176
    Writes output to the specified file, in the specified format (one of
 
177
    \c txt, \c xml, \c lightxml or \c xunitxml).  The special filename \c -
 
178
    may be used to log to standard output.
 
179
    \li \c -o \e filename \br
 
180
    Writes output to the specified file.
 
181
    \li \c -txt \br
 
182
    Outputs results in plain text.
 
183
    \li \c -xml \br
 
184
    Outputs results as an XML document.
 
185
    \li \c -lightxml \br
 
186
    Outputs results as a stream of XML tags.
 
187
    \li \c -xunitxml \br
 
188
    Outputs results as an Xunit XML document.
 
189
    \endlist
 
190
 
 
191
    The first version of the \c -o option may be repeated in order to log
 
192
    test results in multiple formats, but no more than one instance of this
 
193
    option can log test results to standard output.
 
194
 
 
195
    If the first version of the \c -o option is used, neither the second version
 
196
    of the \c -o option nor the \c -txt, \c -xml, \c -lightxml or \c -xunitxml
 
197
    options should be used.
 
198
 
 
199
    If neither version of the \c -o option is used, test results will be logged to
 
200
    standard output.  If no format option is used, test results will be logged in
 
201
    plain text.
 
202
 
 
203
    \section3 Test Log Detail Options
 
204
 
 
205
    The following command line options control how much detail is reported
 
206
    in test logs:
 
207
 
 
208
    \list
 
209
    \li \c -silent \br
 
210
    Silent output; only shows fatal errors, test failures and minimal status
 
211
    messages.
 
212
    \li \c -v1 \br
 
213
    Verbose output; shows when each test function is entered.
 
214
    (This option only affects plain text output.)
 
215
    \li \c -v2 \br
 
216
    Extended verbose output; shows each \l QCOMPARE() and \l QVERIFY().
 
217
    (This option affects all output formats and implies \c -v1 for plain text output.)
 
218
    \li \c -vs \br
 
219
    Shows all signals that get emitted and the slot invocations resulting from
 
220
    those signals.
 
221
    (This option affects all output formats.)
 
222
    \endlist
 
223
 
 
224
    \section3 Testing Options
 
225
 
 
226
    The following command-line options influence how tests are run:
 
227
 
 
228
    \list
 
229
    \li \c -functions \br
 
230
    Outputs all test functions available in the test, then quits.
 
231
    \li \c -datatags \br
 
232
    Outputs all data tags available in the test.
 
233
    A global data tag is preceded by ' __global__ '.
 
234
    \li \c -eventdelay \e ms \br
 
235
    If no delay is specified for keyboard or mouse simulation
 
236
    (\l QTest::keyClick(),
 
237
    \l QTest::mouseClick() etc.), the value from this parameter
 
238
    (in milliseconds) is substituted.
 
239
    \li \c -keydelay \e ms \br
 
240
    Like -eventdelay, but only influences keyboard simulation and not mouse
 
241
    simulation.
 
242
    \li \c -mousedelay \e ms \br
 
243
    Like -eventdelay, but only influences mouse simulation and not keyboard
 
244
    simulation.
 
245
    \li \c -maxwarnings \e number \br
 
246
    Sets the maximum number of warnings to output. 0 for unlimited, defaults to
 
247
    2000.
 
248
    \li \c -nocrashhandler \br
 
249
    Disables the crash handler on Unix platforms.
 
250
    \endlist
 
251
 
 
252
    \section3 Benchmarking Options
 
253
 
 
254
    The following command line options control benchmark testing:
 
255
 
 
256
    \list
 
257
    \li \c -callgrind \br
 
258
    Uses Callgrind to time benchmarks (Linux only).
 
259
    \li \c -tickcounter \br
 
260
    Uses CPU tick counters to time benchmarks.
 
261
    \li \c -eventcounter \br
 
262
    Counts events received during benchmarks.
 
263
    \li \c -minimumvalue \e n \br
 
264
    Sets the minimum acceptable measurement value.
 
265
    \li \c -iterations \e n \br
 
266
    Sets the number of accumulation iterations.
 
267
    \li \c -median \e n \br
 
268
    Sets the number of median iterations.
 
269
    \li \c -vb \br
 
270
    Outputs verbose benchmarking information.
 
271
    \endlist
 
272
 
 
273
    \section3 Miscellaneous Options
 
274
 
 
275
    \list
 
276
    \li \c -help \br
 
277
    Outputs the possible command line arguments and gives some useful help.
 
278
    \endlist
 
279
 
 
280
    \section1 Creating a Benchmark
 
281
 
 
282
    To create a benchmark, follow the instructions for creating a test and then add a
 
283
    QBENCHMARK macro to the test function that you want to benchmark.
 
284
 
 
285
    \snippet code/doc_src_qtestlib.cpp 12
 
286
 
 
287
    The code inside the QBENCHMARK macro will be measured, and possibly also repeated
 
288
    several times in order to get an accurate measurement. This depends on the selected
 
289
    measurement back-end. Several back-ends are available. They can be selected on the
 
290
    command line:
 
291
 
 
292
    \target testlib-benchmarking-measurement
 
293
 
 
294
    \table
 
295
    \header \li Name
 
296
         \li Command-line Argument
 
297
         \li Availability
 
298
    \row \li Walltime
 
299
         \li (default)
 
300
         \li All platforms
 
301
    \row \li CPU tick counter
 
302
         \li -tickcounter
 
303
         \li Windows, Mac OS X, Linux, many UNIX-like systems.
 
304
    \row \li Valgrind Callgrind
 
305
         \li -callgrind
 
306
         \li Linux (if installed)
 
307
    \row \li Event Counter
 
308
         \li -eventcounter
 
309
         \li All platforms
 
310
    \endtable
 
311
 
 
312
    In short, walltime is always available but requires many repetitions to
 
313
    get a useful result.
 
314
    Tick counters are usually available and can provide
 
315
    results with fewer repetitions, but can be susceptible to CPU frequency
 
316
    scaling issues.
 
317
    Valgrind provides exact results, but does not take
 
318
    I/O waits into account, and is only available on a limited number of
 
319
    platforms.
 
320
    Event counting is available on all platforms and it provides the number of events
 
321
    that were received by the event loop before they are sent to their corresponding
 
322
    targets (this might include non-Qt events).
 
323
 
 
324
    \note Depending on the device configuration, tick counters on the
 
325
     Windows CE platform may not be as fine-grained, compared to other platforms.
 
326
     Devices that do not support high-resolution timers default to
 
327
     one-millisecond granularity.
 
328
 
 
329
    See \l {Chapter 5: Writing a Benchmark}{Writing a Benchmark} in the Qt Test
 
330
    Tutorial for more benchmarking examples.
 
331
 
 
332
    \section1 Using Qt Test Remotely on Windows CE
 
333
 
 
334
    The \c cetest convenience application enables you to launch an
 
335
    application remotely on a Windows CE device or emulator.
 
336
 
 
337
    It needs to be executed after the unit test has been successfully compiled.
 
338
 
 
339
    Prior to launching, the following files are copied to the device:
 
340
 
 
341
    \list
 
342
    \li all Qt libraries the project links to
 
343
    \li \l {QtRemote}{QtRemote.dll}
 
344
    \li the c runtime library specified during installation
 
345
    \li all files specified in the \c .pro file following the \l DEPLOYMENT rules.
 
346
    \endlist
 
347
 
 
348
    \section2 Syntax
 
349
    The syntax to execute an autotest takes the following simple form:
 
350
 
 
351
    \snippet code/doc_src_qtestlib.qdoc 6
 
352
 
 
353
    \section2 Options
 
354
    \c cetest provides the same options as those for unit-testing on non cross-compiled
 
355
    platforms. See \l {Qt Test Command Line Arguments} {Command Line Arguments} for
 
356
    more information.
 
357
 
 
358
    The following commands are also included:
 
359
 
 
360
    \list
 
361
    \li \c -debug \br
 
362
    Compiles the test version in debug mode.
 
363
    \li \c -release \br
 
364
    Compiles the test version in release mode.
 
365
    \li \c -libpath \e path \br
 
366
    Copies Qt libraries to the specified path.
 
367
    \li \c -qt-delete \br
 
368
    Deletes Qt libraries after execution.
 
369
    \li \c -project-delete \br
 
370
    Deletes project files after execution.
 
371
    \li \c -delete \br
 
372
    Deletes project and Qt libraries after execution.
 
373
    \li \c -conf \br
 
374
    Specifies a qt.conf file to be deployed to remote directory.
 
375
    \endlist
 
376
 
 
377
    \note \c{debug} is the default build option.
 
378
 
 
379
    \section2 QtRemote
 
380
    \c QtRemote is a small library which is built after Qt Test. It allows the host
 
381
    system to create a process on a remote device and waits until its execution has
 
382
    been finished.
 
383
 
 
384
    \section2 Requirements
 
385
    \c cetest uses Microsoft ActiveSync to establish a remote connection between the
 
386
    host computer and the device. Thus header files and libraries are needed to compile
 
387
    cetest and QtRemote successfully.
 
388
 
 
389
    Prior to \l{Installing Qt for Windows CE}{installation} of Qt, you need to set your
 
390
    \c INCLUDE and \c LIB environment variables properly.
 
391
 
 
392
    A default installation of Windows Mobile 5 for Pocket PC can be obtained by:
 
393
 
 
394
    \snippet code/doc_src_qtestlib.qdoc 7
 
395
 
 
396
    Note that Qt will remember the path, so you do not need to set it again
 
397
    after switching the environments for cross-compilation.
 
398
 
 
399
    \section1 3rd Party Code
 
400
 
 
401
    The CPU tick counters used for benchmarking are licensed under the following
 
402
    license: (from src/testlib/3rdparty/cycle.h)
 
403
 
 
404
    \legalese
 
405
    Copyright (c) 2003, 2006 Matteo Frigo\br
 
406
    Copyright (c) 2003, 2006 Massachusetts Institute of Technology
 
407
 
 
408
    Permission is hereby granted, free of charge, to any person obtaining
 
409
    a copy of this software and associated documentation files (the
 
410
    "Software"), to deal in the Software without restriction, including
 
411
    without limitation the rights to use, copy, modify, merge, publish,
 
412
    distribute, sublicense, and/or sell copies of the Software, and to
 
413
    permit persons to whom the Software is furnished to do so, subject to
 
414
    the following conditions:
 
415
 
 
416
    The above copyright notice and this permission notice shall be
 
417
    included in all copies or substantial portions of the Software.
 
418
 
 
419
    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
 
420
    EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
 
421
    MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
 
422
    NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
 
423
    LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
 
424
    OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
 
425
    WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 
426
    \endlegalese
 
427
*/
 
428
 
 
429
/*!
 
430
    \page qtest-tutorial.html
 
431
    \brief A short introduction to testing with Qt Test.
 
432
    \contentspage Qt Test Overview
 
433
    \nextpage {Chapter 1: Writing a Unit Test}{Chapter 1}
 
434
    \ingroup best-practices
 
435
 
 
436
    \title Qt Test Tutorial
 
437
 
 
438
    This tutorial gives a short introduction to how to use some of the
 
439
    features of the Qt Test framework. It is divided into five
 
440
    chapters:
 
441
 
 
442
    \list 1
 
443
    \li \l {Chapter 1: Writing a Unit Test}{Writing a Unit Test}
 
444
    \li \l {Chapter 2: Data Driven Testing}{Data Driven Testing}
 
445
    \li \l {Chapter 3: Simulating GUI Events}{Simulating GUI Events}
 
446
    \li \l {Chapter 4: Replaying GUI Events}{Replaying GUI Events}
 
447
    \li \l {Chapter 5: Writing a Benchmark}{Writing a Benchmark}
 
448
    \endlist
 
449
 
 
450
*/
 
451
 
 
452
 
 
453
/*!
 
454
    \example tutorial1
 
455
 
 
456
    \contentspage {Qt Test Tutorial}{Contents}
 
457
    \nextpage {Chapter 2: Data Driven Testing}{Chapter 2}
 
458
 
 
459
    \title Chapter 1: Writing a Unit Test
 
460
 
 
461
    In this first chapter we will see how to write a simple unit test
 
462
    for a class, and how to execute it.
 
463
 
 
464
    \section1 Writing a Test
 
465
 
 
466
    Let's assume you want to test the behavior of our QString class.
 
467
    First, you need a class that contains your test functions. This class
 
468
    has to inherit from QObject:
 
469
 
 
470
    \snippet tutorial1/testqstring.cpp 0
 
471
 
 
472
    \note You need to include the QTest header and declare the test functions as
 
473
    private slots so the test framework finds and executes it.
 
474
 
 
475
    Then you need to implement the test function itself. The
 
476
    implementation could look like this:
 
477
 
 
478
    \snippet code/doc_src_qtestlib.cpp 8
 
479
 
 
480
    The \l QVERIFY() macro evaluates the expression passed as its
 
481
    argument. If the expression evaluates to true, the execution of
 
482
    the test function continues. Otherwise, a message describing the
 
483
    failure is appended to the test log, and the test function stops
 
484
    executing.
 
485
 
 
486
    But if you want a more verbose output to the test log, you should
 
487
    use the \l QCOMPARE() macro instead:
 
488
 
 
489
    \snippet tutorial1/testqstring.cpp 1
 
490
 
 
491
    If the strings are not equal, the contents of both strings are
 
492
    appended to the test log, making it immediately visible why the
 
493
    comparison failed.
 
494
 
 
495
    Finally, to make our test case a stand-alone executable, the
 
496
    following two lines are needed:
 
497
 
 
498
    \snippet tutorial1/testqstring.cpp 2
 
499
 
 
500
    The \l QTEST_MAIN() macro expands to a simple \c main()
 
501
    method that runs all the test functions. Note that if both the
 
502
    declaration and the implementation of our test class are in a \c
 
503
    .cpp file, we also need to include the generated moc file to make
 
504
    Qt's introspection work.
 
505
 
 
506
    \section1 Executing a Test
 
507
 
 
508
    Now that we finished writing our test, we want to execute
 
509
    it. Assuming that our test was saved as \c testqstring.cpp in an
 
510
    empty directory, we build the test using qmake to create a project
 
511
    and generate a makefile.
 
512
 
 
513
    \snippet code/doc_src_qtestlib.qdoc 9
 
514
 
 
515
    \note If you're using windows, replace \c make with \c
 
516
    nmake or whatever build tool you use.
 
517
 
 
518
    Running the resulting executable should give you the following
 
519
    output:
 
520
 
 
521
    \snippet code/doc_src_qtestlib.qdoc 10
 
522
 
 
523
    Congratulations! You just wrote and executed your first unit test
 
524
    using the Qt Test framework.
 
525
*/
 
526
 
 
527
/*!
 
528
    \example tutorial2
 
529
 
 
530
    \previouspage {Chapter 1: Writing a Unit Test}{Chapter 1}
 
531
    \contentspage {Qt Test Tutorial}{Contents}
 
532
    \nextpage {Chapter 3: Simulating Gui Events}{Chapter 3}
 
533
 
 
534
    \title Chapter 2: Data Driven Testing
 
535
 
 
536
    In this chapter we will demonstrate how to execute a test
 
537
    multiple times with different test data.
 
538
 
 
539
    So far, we have hard coded the data we wanted to test into our
 
540
    test function. If we add more test data, the function might look like
 
541
    this:
 
542
 
 
543
    \snippet code/doc_src_qtestlib.cpp 11
 
544
 
 
545
    To prevent that the function ends up being cluttered by repetitive
 
546
    code, Qt Test supports adding test data to a test function. All
 
547
    we need is to add another private slot to our test class:
 
548
 
 
549
    \snippet tutorial2/testqstring.cpp 0
 
550
 
 
551
    \section1 Writing the Data Function
 
552
 
 
553
    A test function's associated data function carries the same name,
 
554
    appended by \c{_data}. Our data function looks like this:
 
555
 
 
556
    \snippet tutorial2/testqstring.cpp 1
 
557
 
 
558
    First, we define the two elements of our test table using the \l
 
559
    QTest::addColumn() function: a test string, and the
 
560
    expected result of applying the QString::toUpper() function to
 
561
    that string.
 
562
 
 
563
    Then we add some data to the table using the \l
 
564
    QTest::newRow() function. Each set of data will become a
 
565
    separate row in the test table.
 
566
 
 
567
    \l QTest::newRow() takes one argument: a name that will be
 
568
    associated with the data set. If the test fails, the name will be
 
569
    used in the test log, referencing the failed data. Then we
 
570
    stream the data set into the new table row. First an arbitrary
 
571
    string, and then the expected result of applying the
 
572
    QString::toUpper() function to that string.
 
573
 
 
574
    You can think of the test data as a two-dimensional table. In
 
575
    our case, it has two columns called \c string and \c result and
 
576
    three rows. In addition a name as well as an index is associated
 
577
    with each row:
 
578
 
 
579
    \table
 
580
    \header
 
581
        \li index
 
582
        \li name
 
583
        \li string
 
584
        \li result
 
585
    \row
 
586
        \li 0
 
587
        \li all lower
 
588
        \li "hello"
 
589
        \li HELLO
 
590
    \row
 
591
        \li 1
 
592
        \li mixed
 
593
        \li "Hello"
 
594
        \li HELLO
 
595
    \row
 
596
        \li 2
 
597
        \li all upper
 
598
        \li "HELLO"
 
599
        \li HELLO
 
600
    \endtable
 
601
 
 
602
    \section1 Rewriting the Test Function
 
603
 
 
604
    Our test function can now be rewritten:
 
605
 
 
606
    \snippet tutorial2/testqstring.cpp 2
 
607
 
 
608
    The TestQString::toUpper() function will be executed three times,
 
609
    once for each entry in the test table that we created in the
 
610
    associated TestQString::toUpper_data() function.
 
611
 
 
612
    First, we fetch the two elements of the data set using the \l
 
613
    QFETCH() macro. \l QFETCH() takes two arguments: The data type of
 
614
    the element and the element name. Then we perform the test using
 
615
    the \l QCOMPARE() macro.
 
616
 
 
617
    This approach makes it very easy to add new data to the test
 
618
    without modifying the test itself.
 
619
 
 
620
    And again, to make our test case a stand-alone executable,
 
621
    the following two lines are needed:
 
622
 
 
623
    \snippet tutorial2/testqstring.cpp 3
 
624
 
 
625
    As before, the QTEST_MAIN() macro expands to a simple main()
 
626
    method that runs all the test functions, and since both the
 
627
    declaration and the implementation of our test class are in a .cpp
 
628
    file, we also need to include the generated moc file to make Qt's
 
629
    introspection work.
 
630
*/
 
631
 
 
632
/*!
 
633
    \example tutorial3
 
634
 
 
635
    \previouspage {Chapter 2: Data Driven Testing}{Chapter 2}
 
636
    \contentspage {Qt Test Tutorial}{Contents}
 
637
    \nextpage {Chapter 4: Replaying GUI Events}{Chapter 4}
 
638
 
 
639
    \title Chapter 3: Simulating GUI Events
 
640
 
 
641
    Qt Test features some mechanisms to test graphical user
 
642
    interfaces. Instead of simulating native window system events,
 
643
    Qt Test sends internal Qt events. That means there are no
 
644
    side-effects on the machine the tests are running on.
 
645
 
 
646
    In this chapter we will see how to write a simple GUI test.
 
647
 
 
648
    \section1 Writing a GUI test
 
649
 
 
650
    This time, let's assume you want to test the behavior of our
 
651
    QLineEdit class. As before, you will need a class that contains
 
652
    your test function:
 
653
 
 
654
    \snippet tutorial3/testgui.cpp 0
 
655
 
 
656
    The only difference is that you need to include the QtGui class
 
657
    definitions in addition to the QTest namespace.
 
658
 
 
659
    \snippet tutorial3/testgui.cpp 1
 
660
 
 
661
    In the implementation of the test function we first create a
 
662
    QLineEdit. Then we simulate writing "hello world" in the line edit
 
663
    using the \l QTest::keyClicks() function.
 
664
 
 
665
    \note The widget must also be shown in order to correctly test keyboard
 
666
    shortcuts.
 
667
 
 
668
    QTest::keyClicks() simulates clicking a sequence of keys on a
 
669
    widget. Optionally, a keyboard modifier can be specified as well
 
670
    as a delay (in milliseconds) of the test after each key click. In
 
671
    a similar way, you can use the QTest::keyClick(),
 
672
    QTest::keyPress(), QTest::keyRelease(), QTest::mouseClick(),
 
673
    QTest::mouseDClick(), QTest::mouseMove(), QTest::mousePress()
 
674
    and QTest::mouseRelease() functions to simulate the associated
 
675
    GUI events.
 
676
 
 
677
    Finally, we use the \l QCOMPARE() macro to check if the line edit's
 
678
    text is as expected.
 
679
 
 
680
    As before, to make our test case a stand-alone executable, the
 
681
    following two lines are needed:
 
682
 
 
683
    \snippet tutorial3/testgui.cpp 2
 
684
 
 
685
    The QTEST_MAIN() macro expands to a simple main() method that
 
686
    runs all the test functions, and since both the declaration and
 
687
    the implementation of our test class are in a .cpp file, we also
 
688
    need to include the generated moc file to make Qt's introspection
 
689
    work.
 
690
*/
 
691
 
 
692
/*!
 
693
    \example tutorial4
 
694
 
 
695
    \previouspage {Chapter 3: Simulating GUI Events}{Chapter 3}
 
696
    \contentspage {Qt Test Tutorial}{Contents}
 
697
    \nextpage {Chapter 5: Writing a Benchmark}{Chapter 5}
 
698
 
 
699
    \title Chapter 4: Replaying GUI Events
 
700
 
 
701
    In this chapter, we will show how to simulate a GUI event,
 
702
    and how to store a series of GUI events as well as replay them on
 
703
    a widget.
 
704
 
 
705
    The approach to storing a series of events and replaying them is
 
706
    quite similar to the approach explained in \l {Chapter 2:
 
707
    Data Driven Testing}{chapter 2}. All you need to do is to add a data
 
708
    function to your test class:
 
709
 
 
710
    \snippet tutorial4/testgui.cpp 0
 
711
 
 
712
    \section1 Writing the Data Function
 
713
 
 
714
    As before, a test function's associated data function carries the
 
715
    same name, appended by \c{_data}.
 
716
 
 
717
    \snippet tutorial4/testgui.cpp 1
 
718
 
 
719
    First, we define the elements of the table using the
 
720
    QTest::addColumn() function: A list of GUI events, and the
 
721
    expected result of applying the list of events on a QWidget. Note
 
722
    that the type of the first element is \l QTestEventList.
 
723
 
 
724
    A QTestEventList can be populated with GUI events that can be
 
725
    stored as test data for later usage, or be replayed on any
 
726
    QWidget.
 
727
 
 
728
    In our current data function, we create two \l
 
729
    {QTestEventList} elements. The first list consists of a single click to
 
730
    the 'a' key. We add the event to the list using the
 
731
    QTestEventList::addKeyClick() function. Then we use the
 
732
    QTest::newRow() function to give the data set a name, and
 
733
    stream the event list and the expected result into the table.
 
734
 
 
735
    The second list consists of two key clicks: an 'a' with a
 
736
    following 'backspace'. Again we use the
 
737
    QTestEventList::addKeyClick() to add the events to the list, and
 
738
    QTest::newRow() to put the event list and the expected
 
739
    result into the table with an associated name.
 
740
 
 
741
    \section1 Rewriting the Test Function
 
742
 
 
743
    Our test can now be rewritten:
 
744
 
 
745
    \snippet tutorial4/testgui.cpp 2
 
746
 
 
747
    The TestGui::testGui() function will be executed two times,
 
748
    once for each entry in the test data that we created in the
 
749
    associated TestGui::testGui_data() function.
 
750
 
 
751
    First, we fetch the two elements of the data set using the \l
 
752
    QFETCH() macro. \l QFETCH() takes two arguments: the data type of
 
753
    the element and the element name. Then we create a QLineEdit, and
 
754
    apply the list of events on that widget using the
 
755
    QTestEventList::simulate() function.
 
756
 
 
757
    Finally, we use the QCOMPARE() macro to check if the line edit's
 
758
    text is as expected.
 
759
 
 
760
    As before, to make our test case a stand-alone executable,
 
761
    the following two lines are needed:
 
762
 
 
763
    \snippet tutorial4/testgui.cpp 3
 
764
 
 
765
    The QTEST_MAIN() macro expands to a simple main() method that
 
766
    runs all the test functions, and since both the declaration and
 
767
    the implementation of our test class are in a .cpp file, we also
 
768
    need to include the generated moc file to make Qt's introspection
 
769
    work.
 
770
*/
 
771
 
 
772
/*!
 
773
    \example tutorial5
 
774
 
 
775
    \previouspage {Chapter 4: Replaying GUI Events}{Chapter 4}
 
776
    \contentspage {Qt Test Tutorial}{Contents}
 
777
 
 
778
    \title Chapter 5: Writing a Benchmark
 
779
 
 
780
    In this final chapter we will demonstrate how to write benchmarks
 
781
    using Qt Test.
 
782
 
 
783
    \section1 Writing a Benchmark
 
784
    To create a benchmark we extend a test function with a QBENCHMARK macro.
 
785
    A benchmark test function will then typically consist of setup code and
 
786
    a QBENCHMARK macro that contains the code to be measured. This test
 
787
    function benchmarks QString::localeAwareCompare().
 
788
 
 
789
    \snippet tutorial5/benchmarking.cpp 0
 
790
 
 
791
    Setup can be done at the beginning of the function, the clock is not
 
792
    running at this point. The code inside the QBENCHMARK macro will be
 
793
    measured, and possibly repeated several times in order to  get an
 
794
    accurate measurement.
 
795
 
 
796
    Several \l {testlib-benchmarking-measurement}{back-ends} are available
 
797
    and can be selected on the command line.
 
798
 
 
799
    \section1 Data Functions
 
800
 
 
801
    Data functions are useful for creating benchmarks that compare
 
802
    multiple data inputs, for example locale aware compare against standard
 
803
    compare.
 
804
 
 
805
    \snippet tutorial5/benchmarking.cpp 1
 
806
 
 
807
    The test function then uses the data to determine what to benchmark.
 
808
 
 
809
    \snippet tutorial5/benchmarking.cpp 2
 
810
 
 
811
    The "if (useLocaleCompare)" switch is placed outside the QBENCHMARK
 
812
    macro to avoid measuring its overhead. Each benchmark test function
 
813
    can have one active QBENCHMARK macro.
 
814
 
 
815
    \section1 External Tools
 
816
 
 
817
    Tools for handling and visualizing test data are available as part of
 
818
    the \l {qtestlib-tools} project.
 
819
    These include a tool for comparing performance data obtained from test
 
820
    runs and a utility to generate Web-based graphs of performance data.
 
821
 
 
822
    See the \l{qtestlib-tools Announcement}{qtestlib-tools announcement}
 
823
    for more information on these tools and a simple graphing example.
 
824
 
 
825
*/