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