3
<title>CxxTest User's Guide</title>
4
<meta http-equiv="Content-Type" content="text/html">
5
<meta name="description" content="CxxTest User's Guide">
6
<meta name="generator" content="makeinfo 4.3">
7
<link href="http://www.gnu.org/software/texinfo/" rel="generator-home">
10
<h1 class="settitle">CxxTest User's Guide</h1>
11
<a href="#contents">Table of contents</a>
13
<h2 class="chapter"><a name="TOC0"></a>1 Introduction</h2>
15
<p>CxxTest is a <a href="http://junit.org/">JUnit</a>/<a href="http://cppunit.sourceforge.net">CppUnit</a>/<a href="http://xprogramming.com/software.html">xUnit</a>-like framework for C++.
17
<p>Its advantages over existing alternatives are that it:
19
<li>Doesn't require RTTI
20
<li>Doesn't require member template functions
21
<li>Doesn't require exception handling
22
<li>Doesn't require any external libraries (including memory management, file/console I/O, graphics libraries)
24
In other words, CxxTest is designed to be as portable as possible. Its
25
only requirements are a reasonably modern C++ compiler and either Perl
26
or Python. However, when advanced features are supported in your
27
environment, CxxTest can use them, e.g. catch unhandled exceptions and
30
<p>In addition, CxxTest is slightly easier to use than the C++
31
alternatives, since you don't need to "register" your tests. It also
32
features some extras like a richer set of assertions and even support
33
for a "to do" list (see <a href="#warn"><code>TS_WARN(</code><em></em><code>)</code></a>).
35
<p>CxxTest is available under the
36
<a href="http://www.gnu.org/copyleft/lesser.html">GNU Lesser General Public License</a>.
38
<h3 class="section"><a name="TOC1"></a>1.1 About this guide</h3>
40
<p>This guide is not intended as an introduction to Extreme Progamming
41
and/or unit testing. It describes the design and usage of CxxTest.
43
<h2 class="chapter"><a name="TOC2"></a>2 Getting started</h2>
45
<h3 class="section"><a name="TOC3"></a>2.1 Getting CxxTest</h3>
47
<p>The homepage for CxxTest is <a href="http://cxxtest.sourceforge.net">http://cxxtest.sourceforge.net</a>. You
48
can always get the latest release from the SourceForge download page,
49
<a href="http://sourceforge.net/project/showfiles.php?group_id=52834">here</a>
50
or <a href="http://dl.sourceforge.net/cxxtest">here</a>. The latest version
51
of this guide is available online at
52
<a href="http://cxxtest.sourceforge.net/guide.html">http://cxxtest.sourceforge.net/guide.html</a>. A PDF version is also
53
available at <a href="http://cxxtest.sourceforge.net/guide.pdf">http://cxxtest.sourceforge.net/guide.pdf</a>.
55
<h3 class="section"><a name="TOC4"></a>2.2 Your first test!</h3>
57
<p>Here's a simple step-by-step guide:
61
<li>Tests are organized into "Test Suites".
62
Test suites are written in header files.
64
<p>A test suite is a class that inherits from <code>CxxTest::TestSuite</code>.
65
A test is a public <code>void (void)</code> member function of that class whose name starts with <code>test</code>,
66
e.g. <code>testDirectoryScanner()</code>, <code>test_cool_feature()</code> and even <code>TestImportantBugFix()</code>.
68
<pre class="smallexample">
69
<pre class="verbatim">
71
#include <cxxtest/TestSuite.h>
73
class MyTestSuite : public CxxTest::TestSuite
76
void testAddition( void )
78
TS_ASSERT( 1 + 1 > 1 );
79
TS_ASSERT_EQUALS( 1 + 1, 2 );
85
</p><li>After you have your test suites, you use CxxTest to generate a "test runner" source file:
87
<pre class="verbatim">
88
# cxxtestgen.pl --error-printer -o runner.cpp MyTestSuite.h
91
<p>or, for those less fortunate:
93
<pre class="verbatim">
94
C:\tmp> perl -w cxxtestgen.pl --error-printer -o runner.cpp MyTestSuite.h
97
</p><li>You would then simply compile the resulting file:
99
<pre class="verbatim">
100
# g++ -o runner runner.cpp
105
<pre class="verbatim">
106
C:\tmp> cl -GX -o runner.exe runner.cpp
111
<pre class="verbatim">
112
C:\tmp> bcc32 -erunner.exe runner.cpp
115
</p><li>Finally, you run the tests and enjoy a well tested piece of software:
117
<pre class="verbatim">
124
<h3 class="section"><a name="TOC5"></a>2.3 Your second test</h3>
126
<p>Now let's see what failed tests look like.
127
We will add a failing test to the previous example:
129
<pre class="smallexample">
130
<pre class="verbatim">
132
#include <cxxtest/TestSuite.h>
134
class MyTestSuite : public CxxTest::TestSuite
137
void testAddition( void )
139
TS_ASSERT( 1 + 1 > 1 );
140
TS_ASSERT_EQUALS( 1 + 1, 2 );
143
void testMultiplication( void )
145
TS_ASSERT_EQUALS( 2 * 2, 5 );
151
<p>Generate, compile and run the test runner, and you will get this:
153
<pre class="smallexample">
154
<pre class="verbatim">
157
MyTestSuite.h:15: Expected (2 * 2 == 5), found (4 != 5)
163
<p>Fixing the bug is left as an excercise to the reader.
165
<h3 class="section"><a name="TOC6"></a>2.4 Graphical user interface</h3>
167
<font size=-2>(v3.0.1)</font>
168
CxxTest can also display a simple GUI. The way to do this is depends on
169
your compiler, OS and environment, but try the following pointers:
172
<li>Under Windows with Visual C++, run <code>perl cxxtestgen.pl -o runner.cpp
173
</code><em>--gui=Win32Gui</em><code> MyTestSuite.h</code>.
175
<li>Under X-Windows, try <code>./cxxtestgen.pl -o runner.cpp
176
</code><em>--gui=X11Gui</em><code> MyTestSuite</code>. You may need to tell the compiler
177
where to find X, usually something like <code>g++ -o runner
178
-L/usr/X11R6/lib runner.cpp -lX11</code>.
180
<li>If you have <a href="http://www.trolltech.com">Qt</a> installed, try running
181
<code>cxxtestgen.pl</code> with the option <code>--gui=QtGui</code>. As
182
always, compile and link the the Qt headers and libraries.
186
<p>See <a href="#GUI">Graphical user interface</a> and <a href="#samples">Running the samples</a> for
189
<h2 class="chapter"><a name="TOC7"></a>3 <em>Really</em> using CxxTest</h2>
191
<p>There is much more to CxxTest than seeing if two times two is four.
192
You should probably take a look at the samples in the CxxTest distribution.
193
Other than that, here are some more in-depth explanations.
195
<h3 class="section"><a name="TOC8"></a>3.1 What can you test</h3>
197
<p>Here are the different "assertions" you can use in your tests:
199
<p><table><tr align="left"><td valign="top"><strong>Macro</strong> </td><td valign="top"><strong>Description</strong> </td><td valign="top"><strong>Example</strong>
201
<br></td></tr><tr align="left"><td valign="top"><a href="#fail"><code>TS_FAIL(</code><em>message</em><code>)</code></a>
202
</td><td valign="top">Fail unconditionally
203
</td><td valign="top"><code>TS_FAIL("Test not implemented");</code>
205
<br></td></tr><tr align="left"><td valign="top"><a href="#assert"><code>TS_ASSERT(</code><em>expr</em><code>)</code></a>
206
</td><td valign="top">Verify <code></code><em>(expr)</em><code></code> is true
207
</td><td valign="top"><code>TS_ASSERT(messageReceived());</code>
209
<br></td></tr><tr align="left"><td valign="top"><a href="#equals"><code>TS_ASSERT_EQUALS(</code><em>x, y</em><code>)</code></a>
210
</td><td valign="top">Verify <code></code><em>(x==y)</em><code></code>
211
</td><td valign="top"><code>TS_ASSERT_EQUALS(nodeCount(), 14);</code>
213
<br></td></tr><tr align="left"><td valign="top"><a href="#sameData"><code>TS_ASSERT_SAME_DATA(</code><em>x, y, size</em><code>)</code></a>
214
</td><td valign="top">Verify two buffers are equal
215
</td><td valign="top"><code>TS_ASSERT_SAME_DATA(input, output,, size);</code>
217
<br></td></tr><tr align="left"><td valign="top"><a href="#delta"><code>TS_ASSERT_DELTA(</code><em>x, y, d</em><code>)</code></a>
218
</td><td valign="top">Verify <code></code><em>(x==y)</em><code></code> up to <code></code><em>d</em><code></code>
219
</td><td valign="top"><code>TS_ASSERT_DELTA(sqrt(4.0), 2.0, 0.0001);</code>
221
<br></td></tr><tr align="left"><td valign="top"><a href="#differs"><code>TS_ASSERT_DIFFERS(</code><em>x, y</em><code>)</code></a>
222
</td><td valign="top">Verify <code></code><em>!(x==y)</em><code></code>
223
</td><td valign="top"><code>TS_ASSERT_DIFFERS(exam.numTook(), exam.numPassed());</code>
225
<br></td></tr><tr align="left"><td valign="top"><a href="#lessthan"><code>TS_ASSERT_LESS_THAN(</code><em>x, y</em><code>)</code></a>
226
</td><td valign="top">Verify <code></code><em>(x<y)</em><code></code>
227
</td><td valign="top"><code>TS_ASSERT_LESS_THAN(ship.speed(), SPEED_OF_LIGHT);</code>
229
<br></td></tr><tr align="left"><td valign="top"><a href="#lte"><code>TS_ASSERT_LESS_THAN_EQUALS(</code><em>x, y</em><code>)</code></a>
230
</td><td valign="top">Verify <code></code><em>(x<=y)</em><code></code>
231
</td><td valign="top"><code>TS_ASSERT_LESS_THAN_EQUALS(requests, items);</code>
233
<br></td></tr><tr align="left"><td valign="top"><a href="#predicate"><code>TS_ASSERT_PREDICATE(</code><em>R, x</em><code>)</code></a>
234
</td><td valign="top">Verify <code></code><em>P(x)</em><code></code>
235
</td><td valign="top"><code>TS_ASSERT_PREDICATE(SeemsReasonable, salary);</code>
237
<br></td></tr><tr align="left"><td valign="top"><a href="#relation"><code>TS_ASSERT_RELATION(</code><em>R, x, y</em><code>)</code></a>
238
</td><td valign="top">Verify <code></code><em>x R y</em><code></code>
239
</td><td valign="top"><code>TS_ASSERT_RELATION(std::greater, salary, average);</code>
241
<br></td></tr><tr align="left"><td valign="top"><a href="#throwsx"><code>TS_ASSERT_THROWS(</code><em>expr, type</em><code>)</code></a>
242
</td><td valign="top">Verify that <code></code><em>(expr)</em><code></code> throws a specific type of exception
243
</td><td valign="top"><code>TS_ASSERT_THROWS(parse(file), Parser::ReadError);</code>
245
<br></td></tr><tr align="left"><td valign="top"><a href="#throwsx"><code>TS_ASSERT_THROWS_EQUALS(</code><em>expr, arg, x, y</em><code>)</code></a>
246
</td><td valign="top">Verify type and value of what <code></code><em>(expr)</em><code></code> throws
247
</td><td valign="top">(See text)
249
<br></td></tr><tr align="left"><td valign="top"><a href="#throwsx"><code>TS_ASSERT_THROWS_ASSERT(</code><em>expr, arg, assertion</em><code>)</code></a>
250
</td><td valign="top">Verify type and value of what <code></code><em>(expr)</em><code></code> throws
251
</td><td valign="top">(See text)
253
<br></td></tr><tr align="left"><td valign="top"><a href="#throwsx"><code>TS_ASSERT_THROWS_ANYTHING(</code><em>expr</em><code>)</code></a>
254
</td><td valign="top">Verify that <code></code><em>(expr)</em><code></code> throws an exception
255
</td><td valign="top"><code>TS_ASSERT_THROWS_ANYTHING(buggy());</code>
257
<br></td></tr><tr align="left"><td valign="top"><a href="#throwsx"><code>TS_ASSERT_THROWS_NOTHING(</code><em>expr</em><code>)</code></a>
258
</td><td valign="top">Verify that <code></code><em>(expr)</em><code></code> doesn't throw anything
259
</td><td valign="top"><code>TS_ASSERT_THROWS_NOTHING(robust());</code>
261
<br></td></tr><tr align="left"><td valign="top"><a href="#warn"><code>TS_WARN(</code><em>message</em><code>)</code></a>
262
</td><td valign="top">Print <code></code><em>message</em><code></code> as a warning
263
</td><td valign="top"><code>TS_WARN("TODO: Check invalid parameters");</code>
265
<br></td></tr><tr align="left"><td valign="top"><a href="#trace"><code>TS_TRACE(</code><em>message</em><code>)</code></a>
266
</td><td valign="top">Print <code></code><em>message</em><code></code> as an informational message
267
</td><td valign="top"><code>TS_TRACE(errno);</code>
269
<br></td></tr></table>
271
<h4 class="subsection"><a name="TOC9"></a>3.1.1 <code>TS_FAIL</code></h4>
273
<p><a name="fail"></a>
275
<p><code>TS_FAIL</code> just fails the test.
276
It is like an <code>assert(false)</code> with an error message.
279
<pre class="smallexample">
280
<pre class="verbatim">
281
void testSomething( void )
283
TS_FAIL( "I don't know how to test this!" );
288
<h4 class="subsection"><a name="TOC10"></a>3.1.2 <code>TS_ASSERT</code></h4>
290
<p><a name="assert"></a>
292
<p><code>TS_ASSERT</code> is the basic all-around tester. It works just like the
293
well-respected <code>assert()</code> macro (which I sincerely hope you know and
296
<pre class="smallexample">
297
<pre class="verbatim">
298
void testSquare( void )
300
MyFileLibrary::createEmptyFile( "test.bin" );
301
TS_ASSERT( access( "test.bin", 0 ) == 0 );
306
<h4 class="subsection"><a name="TOC11"></a>3.1.3 <code>TS_ASSERT_EQUALS</code></h4>
308
<p><a name="equals"></a>
310
<p>This is the second most useful tester.
311
As the name hints, it is used to test if two values are equal.
313
<pre class="smallexample">
314
<pre class="verbatim">
315
void testSquare( void )
317
TS_ASSERT_EQUALS( square(-5), 25 );
322
<h4 class="subsection"><a name="TOC12"></a>3.1.4 <code>TS_ASSERT_SAME_DATA</code></h4>
324
<p><a name="sameData"></a>
326
<font size=-2>(v3.5.1)</font>
327
This assertion is similar to <a href="#equals"><code>TS_ASSERT_EQUALS(</code><em></em><code>)</code></a>, except that it
328
compares the contents of two buffers in memory. If the comparison
329
fails, the standard runner dumps the contents of both buffers as hex
332
<pre class="smallexample">
333
<pre class="verbatim">
334
void testCopyMemory( void )
336
char input[77], output[77];
337
myCopyMemory( output, input, 77 );
338
TS_ASSERT_SAME_DATA( input, output, 77 );
343
<h4 class="subsection"><a name="TOC13"></a>3.1.5 <code>TS_ASSERT_DELTA</code></h4>
345
<p><a name="delta"></a>
347
<p>Similar to <a href="#equals"><code>TS_ASSERT_EQUALS(</code><em></em><code>)</code></a>, this macro
348
verifies two values are equal up to a delta.
349
This is basically used for floating-point values.
351
<pre class="smallexample">
352
<pre class="verbatim">
353
void testSquareRoot( void )
355
TS_ASSERT_DELTA( squareRoot(4.0), 2.0, 0.00001 );
360
<h4 class="subsection"><a name="TOC14"></a>3.1.6 <code>TS_ASSERT_DIFFERS</code></h4>
362
<p><a name="differs"></a>
364
<p>The opposite of <a href="#equals"><code>TS_ASSERT_EQUALS(</code><em></em><code>)</code></a>, this macro is used to assert
365
that two values are not equal.
367
<pre class="smallexample">
368
<pre class="verbatim">
369
void testNumberGenerator( void )
371
int first = generateNumber();
372
int second = generateNumber();
373
TS_ASSERT_DIFFERS( first, second );
378
<h4 class="subsection"><a name="TOC15"></a>3.1.7 <code>TS_ASSERT_LESS_THAN</code></h4>
380
<p><a name="lessthan"></a>
382
<p>This macro asserts that the first operand is less than the second.
384
<pre class="smallexample">
385
<pre class="verbatim">
386
void testFindLargerNumber( void )
388
TS_ASSERT_LESS_THAN( 23, findLargerNumber(23) );
393
<h4 class="subsection"><a name="TOC16"></a>3.1.8 <code>TS_ASSERT_LESS_THAN_EQUALS</code></h4>
395
<p><a name="lte"></a>
397
<font size=-2>(v3.7.0)</font>
398
Not surprisingly, this macro asserts that the first operand is less than or equals the second.
400
<pre class="smallexample">
401
<pre class="verbatim">
402
void testBufferSize( void )
404
TS_ASSERT_LESS_THAN_EQUALS( bufferSize(), MAX_BUFFER_SIZE );
409
<h4 class="subsection"><a name="TOC17"></a>3.1.9 <code>TS_ASSERT_PREDICATE</code></h4>
411
<p><a name="predicate"></a>
413
<font size=-2>(v3.8.2)</font>
414
This macro can be seen as a generalization of
415
<a href="#assert"><code>TS_ASSERT(</code><em></em><code>)</code></a>. It takes as an argument the name of a class,
416
similar to an STL <code>unary_function</code>, and evaluates
417
<code>operator()</code>. The advantage this has over
418
<a href="#assert"><code>TS_ASSERT(</code><em></em><code>)</code></a> is that you can see the failed value.
420
<pre class="smallexample">
421
<pre class="verbatim">
425
bool operator()( unsigned ) const;
430
void testPrimeGenerator( void )
432
TS_ASSERT_PREDICATE( IsPrime, generatePrime() );
437
<h4 class="subsection"><a name="TOC18"></a>3.1.10 <code>TS_ASSERT_RELATION</code></h4>
439
<p><a name="relation"></a>
441
<font size=-2>(v3.8.0)</font>
443
<a href="#predicate"><code>TS_ASSERT_PREDICATE(</code><em></em><code>)</code></a>, this macro can be seen as a
444
generalization of <a href="#equals"><code>TS_ASSERT_EQUALS(</code><em></em><code>)</code></a>,
445
<a href="#differs"><code>TS_ASSERT_DIFFERS(</code><em></em><code>)</code></a>,
446
<a href="#lessthan"><code>TS_ASSERT_LESS_THAN(</code><em></em><code>)</code></a> and
447
<a href="#lte"><code>TS_ASSERT_LESS_THAN_EQUALS(</code><em></em><code>)</code></a>. It takes as an argument the
448
name of a class, similar to an STL <code>binary_function</code>, and evaluates
449
<code>operator()</code>. This can be used to very simply assert comparisons
450
which are not covered by the builtin macros.
452
<pre class="smallexample">
453
<pre class="verbatim">
454
void testGreater( void )
456
TS_ASSERT_RELATION( std::greater<int>, ticketsSold(), 1000 );
461
<h4 class="subsection"><a name="TOC19"></a>3.1.11 <code>TS_ASSERT_THROWS</code> and friends</h4>
463
<p><a name="throwsx"></a>
465
<p>These assertions are used to test whether an expression throws an exception.
466
<code>TS_ASSERT_THROWS</code> is used when you want to verify the type of exception
467
thrown, and <code>TS_ASSERT_THROWS_ANYTHING</code> is used to just make sure something
468
is thrown. As you might have guessed, <code>TS_ASSERT_THROWS_NOTHING</code> asserts
469
that nothing is thrown.
471
<font size=-2>(v3.10.0)</font>
472
<code>TS_ASSERT_THROWS_EQUALS</code> checks the type of the
473
exception as in <code>TS_ASSERT_THROWS</code> then allows you to compare two
474
value (one of which will presumably be the caught object).
475
<code>TS_ASSERT_THROWS_ASSERT</code> is the general case, and allows you to
476
make any assertion about the thrown value. These macros may seem a
477
little complicated, but they can be very useful; see below for an
480
<pre class="smallexample">
481
<pre class="verbatim">
482
void testFunctionsWhichThrowExceptions( void )
484
TS_ASSERT_THROWS_NOTHING( checkInput(1) );
485
TS_ASSERT_THROWS( checkInput(-11), std::runtime_error );
486
TS_ASSERT_THROWS_ANYTHING( thirdPartyFunction() );
488
TS_ASSERT_THROWS_EQUALS( validate(), const std::exception &e,
489
e.what(), "Invalid value" );
490
TS_ASSERT_THROWS_ASSERT( validate(), const Error &e,
491
TS_ASSERT_DIFFERS( e.code(), SUCCESS ) );
496
<h4 class="subsection"><a name="TOC20"></a>3.1.12 <code>TS_TRACE</code> and <code>TS_WARN</code></h4>
498
<p><a name="warn"></a>
501
<font size=-2>(v3.0.1)</font>
502
<code>TS_WARN</code> just prints out a message, like the
503
<code>#warning</code> preprocessor directive. I find it very useful for "to
504
do" items. For example:
506
<pre class="smallexample">
507
<pre class="verbatim">
508
void testToDoList( void )
510
TS_WARN( "TODO: Write some tests!" );
511
TS_WARN( "TODO: Make $$$ fast!" );
516
<p>In the GUI, <code>TS_WARN</code> sets the bar color to yellow (unless it was
519
<font size=-2>(v3.9.0)</font>
520
<code>TS_TRACE</code> is the same, except that it
521
doesn't change the color of the progress bar.
523
<h4 class="subsection"><a name="TOC21"></a>3.1.13 The <code>ETS_</code> macros</h4>
525
<p>The <code>TS_</code> macros mentioned above will catch exceptions thrown from tested code
526
and fail the test, as if you called <a href="#fail"><code>TS_FAIL(</code><em></em><code>)</code></a>.
527
Sometimes, however, you may want to catch the exception yourself; when you do, you can
528
use the <code>ETS_</code> versions of the macros.
530
<pre class="smallexample">
531
<pre class="verbatim">
532
void testInterestingThrower()
534
// Normal way: if an exception is caught we can't examine it
535
TS_ASSERT_EQUALS( foo(2), 4 );
537
// More elaborate way:
538
try { ETS_ASSERT_EQUALS( foo(2), 4 ); }
539
catch( const BadFoo &e ) { TS_FAIL( e.bar() ); }
544
<h4 class="subsection"><a name="TOC22"></a>3.1.14 The <code>TSM_</code> macros</h4>
546
<p>Sometimes the default output generated by the <code>ErrorPrinter</code> doesn't give you enough
547
information. This often happens when you move common test functionality to helper functions
548
inside the test suite; when an assertion fails, you do not know its origin.
550
<p>In the example below (which is the file <code>sample/MessageTest.h</code> from the CxxTest distribution),
551
we need the message feature to know which invocation of <code>checkValue()</code> failed:
553
<pre class="smallexample">
554
<pre class="verbatim">
555
class MessageTest : public CxxTest::TestSuite
560
checkValue( 0, "My hovercraft" );
561
checkValue( 1, "is full" );
562
checkValue( 2, "of eels" );
565
void checkValue( unsigned value, const char *message )
567
TSM_ASSERT( message, value );
568
TSM_ASSERT_EQUALS( message, value, value * value );
574
<h5 class="subsubsection"><a name="TOC23"></a>3.1.14.1 The <code>ETSM_</code> macros</h5>
576
<p><strong>Note:</strong> As with normal asserts, all <code>TSM_</code> macros have their
577
non-exception-safe counterparts, the <code>ETSM_</code> macros.
579
<h3 class="section"><a name="TOC24"></a>3.2 Running the samples</h3>
581
<p><a name="samples"></a>
583
<p>CxxTest comes with some samples in the <code>sample/</code> subdirectory of
584
the distribution. If you look in that directory, you will see three
585
Makefiles: <code>Makefile.unix</code>, <code>Makefile.msvc</code> and
586
<code>Makefile.bcc32</code> which are for Linux/Unix, MS Visual C++ and
587
Borland C++, repectively. These files are provided as a starting point,
588
and some options may need to be tweaked in them for your system.
590
<p>If you are running under Windows, a good guess would be to run
591
<code>nmake -fMakefile.msvc run_win32</code> (you may need to run
592
<code>VCVARS32.BAT</code> first). Under Linux, <code>make
593
-fMakefile.unix run_x11</code> should probably work.
595
<h3 class="section"><a name="TOC25"></a>3.3 Test fixtures</h3>
597
<p>When you have several test cases for the same module,
598
you often find that all of them start with more or less
599
the same code--creating objects, files, inputs, etc.
600
They may all have a common ending, too--cleaning up
603
<p>You can (and should) put all this code in a common place by overriding
604
the virtual functions <code>TestSuite::setUp()</code> and
605
<code>TestSuite::tearDown()</code>. <code>setUp()</code> will
606
then be called before each test, and <code>tearDown()</code>
609
<pre class="smallexample">
610
<pre class="verbatim">
611
class TestFileOps : public CxxTest::TestSuite
614
void setUp() { mkdir( "playground" ); }
615
void tearDown() { system( "rm -Rf playground"); }
617
void testCreateFile()
619
FileCreator fc( "playground" );
620
fc.createFile( "test.bin" );
621
TS_ASSERT_EQUALS( access( "playground/test.bin", 0 ), 0 );
627
<p><strong>Note new users:</strong> This is probably the single most important
628
feature to use when your tests become non-trivial.
630
<h4 class="subsection"><a name="TOC26"></a>3.3.1 Test suite level fixtures</h4>
632
<p><code>setUp()</code>/<code>tearDown()</code> are executed around each test case. If
633
you need a fixture on the test suite level, i.e. something that gets
634
constructed once before all the tests in the test suite are run, see
635
<a href="#dynamic">Dynamically creating test suites</a> below.
637
<h3 class="section"><a name="TOC27"></a>3.4 Integrating with your build environment</h3>
639
<p>It's very hard to maintain your tests if you have to generate, compile and run the test runner
640
manually all the time.
641
Fortunately, that's why we have build tools!
643
<h4 class="subsection"><a name="TOC28"></a>3.4.1 Overview</h4>
645
<p>Let's assume you're developing an application.
646
What I usually do is the following:
648
<li>Split the application into a library and a main module that just calls
650
This way, the test runner will be able to access all your classes through
652
<li>Create another application (or target, or project, or whatever) for the test runner.
653
Make the build tool generate it automatically.
654
<li>For extra points, make the build tool run the tests automatically.
657
<h4 class="subsection"><a name="TOC29"></a>3.4.2 Actually doing it</h4>
659
<p>Unfortunately, there are way too many different build tools and IDE's for me
660
to give ways to use CxxTest with all of them.
662
<p>I will try to outline the usage for some cases.
664
<h5 class="subsubsection"><a name="TOC30"></a>3.4.2.1 Using Makefiles</h5>
666
<p>Generating the tests with a makefile is pretty straightforward.
667
Simply add rules to generate, compile and run the test runner.
669
<pre class="smallexample">
670
<pre class="verbatim">
671
all: lib run_tests app
673
# Rules to build your targets
678
# A rule that runs the unit tests
682
# How to build the test runner
683
runner: runner.cpp lib
686
# How to generate the test runner
687
runner.cpp: SimpleTest.h ComplicatedTest.h
688
cxxtestgen.pl -o $@ --error-printer $^
692
<h5 class="subsubsection"><a name="TOC31"></a>3.4.2.2 Using Cons</h5>
694
<a href="http://dsmit.com/cons/">Cons</a> is a powerful and
695
versatile make replacement which uses Perl scripts instead of Makefiles.
697
<p>See <code>sample/Construct</code> in the CxxTest distribution for an example of building CxxTest test runners
700
<h5 class="subsubsection"><a name="TOC32"></a>3.4.2.3 Using Microsoft Visual Studio</h5>
702
<p>I have tried several ways to integrate CxxTest with visual studio, none of
703
which is perfect. Take a look at <code>sample/msvc</code> in the distribution
704
to see the best solution I'm aware of. Basically, the workspace has three
708
<li>The project <code>CxxTest_3_Generate</code> runs <code>cxxtestgen</code>.
710
<li>The project <code>CxxTest_2_Build</code> compiles the generated file.
712
<li>The project <code>CxxTest_1_Run</code> runs the tests.
715
<p>This method certainly works, and the test results are conveniently
716
displayed as compilation errors and warnings (for
717
<a href="#warn"><code>TS_WARN(</code><em></em><code>)</code></a>). However, there are still a few things missing;
718
to integrate this approach with your own project, you usually need to
719
work a little bit and tweak some makefiles and project options. I have
720
provided a small script in <code>sample/msvc/FixFiles.bat</code> to automate
723
<h5 class="subsubsection"><a name="TOC33"></a>3.4.2.4 Using Microsoft Windows DDK</h5>
725
<p>Unit testing for device drivers?! Why not?
726
And besides, the <code>build</code> utility can also be used to build
727
user-mode application.
729
<p>To use CxxTest with the <code>build</code> utility,
730
you add the generated tests file as an extra dependency
731
using the <code>NTBUILDTARGET0</code> macro and the <code>Makefile.inc</code>
734
<p>You can see an example of how to do this in the CxxTest distribution
735
under <code>sample/winddk</code>.
737
<h3 class="section"><a name="TOC34"></a>3.5 Graphical user interface</h3>
739
<p><a name="GUI"></a>
741
<p>There are currently three GUIs implemented: native Win32, native X11 and
742
Qt. To use this feature, just specify <code>--gui=X11Gui</code>,
743
<code>--gui=Win32Gui</code> or <code>--gui=QtGui</code> as a parameter for
744
<code>cxxtestgen</code> (instead of e.g. <code>--error-printer</code>). A
745
progress bar is displayed, but the results are still written to standard
746
output, where they can be processed by your IDE (e.g. Emacs or Visual
747
Studio). The default behavior of the GUI is to close the window after
750
<p>Note that whatevr GUI you use, you can combine it with the
751
<code>--runner</code> option to control the formatting of the text output,
752
e.g. Visual Studio likes it better if you use
753
<code>--runner=ParenPrinter</code>.
755
<h4 class="subsection"><a name="TOC35"></a>3.5.1 Starting the GUI minimized</h4>
757
<p>If you run the generated Win32 or Qt GUIs with the command line
758
<code>-minimized</code>, the test window will start minimized (iconified)
759
and only pop up if there is an error (the bar turns red). This is useful
760
if you find the progress bar distracting and only want to check it if
763
<h4 class="subsection"><a name="TOC36"></a>3.5.2 Leaving the GUI open</h4>
765
<p>The Win32 GUI accepts the <code>-keep</code> which instructs it to leave the
766
window open after the tests are done. This allows you to see how many
767
tests failed and how much time it took.
769
<h4 class="subsection"><a name="TOC37"></a>3.5.3 Screenshots!</h4>
771
<p>As with any self-respecting GUI application, here are some screenshots for
776
<li>Using the Qt GUI on Linux (with the WindowMaker window manager):
777
<div align="center"><img src="qt.png" alt="qt.png"></div>
779
<li>Using the Win32 GUI on Windows 98:
780
<div align="center"><img src="win32.png" alt="win32.png"></div>
782
<li>Using the X11 GUI (with the venerable TWM):
783
<div align="center"><img src="x11.png" alt="x11.png"></div>
785
<li>And of course, no GUI is complete without the ability to mess around with
787
<div align="center"><img src="qt2.png" alt="qt2.png"></div>
789
<p><em>Ahhh.</em> Nothing like a beautiful user interface.
793
<h2 class="chapter"><a name="TOC38"></a>4 Advanced topics</h2>
795
<p>Topics in this section are more technical, and you probably won't find them
796
interesting unless you need them.
798
<h3 class="section"><a name="TOC39"></a>4.1 Aborting tests after failures</h3>
800
<p>Usually, when a <code>TS_ASSERT_*</code> macro fails, CxxTest moves on to the
801
next line. In many cases, however, this is not the desired behavior.
802
Consider the following code:
804
<pre class="smallexample">
805
<pre class="verbatim">
808
char *buffer = new char[1024];
810
memset( buffer, 0, 1024 ); // But what if buffer == 0?
815
<p>If you have exception handling enabled, you can make CxxTest exit each
816
test as soon as a failure occurs. To do this, you need to define
817
<code>CXXTEST_ABORT_TEST_ON_FAIL</code> before including the CxxTest
818
headers. This can be done using the <code>--abort-on-fail</code>
819
command-line option or in a template file; see
820
<code>sample/aborter.tpl</code> in the distribution. Note that if CxxTest
821
doesn't find evidence of exception handling when scanning your files,
822
this feature will not work. To overcome this, use the
823
<code>--have-eh</code> command-line option.
825
<h4 class="subsection"><a name="TOC40"></a>4.1.1 Controlling this behavior at runtime</h4>
827
<font size=-2>(v3.8.5)</font>
828
In some scenarios, you may want some tests to abort on
829
failed assertions and others to continue. To do this you use the
830
<code>--abort-on-fail</code> option and call the function
831
<code>CxxTest::setAbortTestOnFail( bool )</code> to change the runtime
832
behavior. This flag is reset (normally, to <code>true</code>) after each
833
test, but you can set it in your test suite's <code>setUp()</code> function to
834
modify the behavior for all tests in a suite.
836
<font size=-2>(v3.9.0)</font>
837
Note that this behavior is available whenever you have
838
exception handling (<code>--have-eh</code> or <code>CXXTEST_HAVE_EH</code>); all
839
<code>--abort-on-fail</code> does is set the default to <code>true</code>.
841
<h3 class="section"><a name="TOC41"></a>4.2 Commenting out tests</h3>
843
<p>CxxTest does a very simple analysis of the input files, which is sufficient in most cases.
844
This means, for example, that you can't indent you test code in "weird" ways.
846
<p>A slight inconvenience arises, however, when you want to comment out
847
tests. Commenting out the tests using C-style comments or the
848
preprocessor will not work:
850
<pre class="smallexample">
851
<pre class="verbatim">
852
class MyTest : public CxxTest::TestSuite
856
void testCommentedOutStillGetsCalled()
862
void testMarkedOutStillGetsCalled()
870
<font size=-2>(v3.10.0)</font>
871
If you need to comment out tests, use C++-style
872
comments. Also, if you just don't want CxxTest to run a specific test
873
function, you can temporarily change its name, e.g. by prefixing it with
876
<pre class="smallexample">
877
<pre class="verbatim">
878
class MyTest : public CxxTest::TestSuite
881
// void testFutureStuff()
885
void xtestFutureStuff()
892
<h3 class="section"><a name="TOC42"></a>4.3 Comparing equality for your own types</h3>
894
<p>You may have noticed that <a href="#equals"><code>TS_ASSERT_EQUALS(</code><em></em><code>)</code></a> only works for built-in
896
This is because CxxTest needs a way to compare object and to convert them to strings,
897
in order to print them should the test fail.
899
<p>If you do want to use <a href="#equals"><code>TS_ASSERT_EQUALS(</code><em></em><code>)</code></a> on your own data types,
900
this is how you do it.
902
<h4 class="subsection"><a name="TOC43"></a>4.3.1 The equality operator</h4>
904
<p>First of all, don't forget to implement the equality operator (<code>operator==()</code>)
907
<h4 class="subsection"><a name="TOC44"></a>4.3.2 Value traits</h4>
909
<p>Since CxxTest tries not to rely on any external library (including the standard library,
910
which is not always available), conversion from arbitrary data types to strings
911
is done using value traits.
913
<p>For example, to convert an integer to a string, CxxTest does the following actions:
915
<li><code>int i = </code><em>value to convert</em><code>;</code>
916
<li><code>CxxTest::ValueTraits<int> converter(i);</code>
917
<li><code>string = converter.asString();</code>
920
<p>CxxTest comes with predefined <code>ValueTrait</code>s for <code>int</code>,
921
<code>char</code>, <code>dobule</code> etc. in <code>cxxtest/ValueTraits.h</code> in the
922
<code>cxxtest-selftest</code> archive.
924
<h4 class="subsection"><a name="TOC45"></a>4.3.3 Unknown types</h4>
926
<p>Obviously, CxxTest doesn't "know" about all possible types.
927
The default ValueTraits class for unknown types dumps up to 8 bytes of the value in hex format.
929
<p>For example, the following code
930
<pre class="smallexample">
931
<pre class="verbatim">
932
#include <cxxtest/TestSuite.h>
934
class TestMyData : public CxxTest::TestSuite
942
void testCompareData()
945
memset( x.data, 0x12, sizeof(x.data) );
946
memset( y.data, 0xF6, sizeof(y.data) );
947
TS_ASSERT_EQUALS( x, y );
953
<pre class="smallexample">
954
<pre class="verbatim">
956
TestMyData.h:16: Expected (x == y), found ({ 12 12 12 } != { F6 F6 F6 })
962
<h4 class="subsection"><a name="TOC46"></a>4.3.4 Enumeration traits</h4>
964
<font size=-2>(v3.10.0)</font>
965
CxxTest provides a simple way to define value traits for
966
your enumeration types, which is very handy for things like status
967
codes. To do this, simply use <code>CXXTEST_VALUE_TRAITS</code> as in the
970
<pre class="smallexample">
971
<pre class="verbatim">
972
enum Status { STATUS_IDLE, STATUS_BUSY, STATUS_ERROR };
974
CXXTEST_ENUM_TRAITS( Status,
975
CXXTEST_ENUM_MEMBER( STATUS_IDLE )
976
CXXTEST_ENUM_MEMBER( STATUS_BUSY )
977
CXXTEST_ENUM_MEMBER( STATUS_ERROR ) );
981
<p>See <code>sample/EnumTraits.h</code> for a working sample.
983
<h4 class="subsection"><a name="TOC47"></a>4.3.5 Defining new value traits</h4>
985
<p>Defining value traits for new (non-enumeration) types is easy. All you
986
need is to define a way to convert an object of your class to a
987
string. You can use this example as a possible skeleton:
989
<pre class="smallexample">
990
<pre class="verbatim">
996
MyClass( int value ) : _value( value ) {}
997
int value() const { return _value; }
999
// CxxTest requires a copy constructor
1000
MyClass( const MyClass &other ) : _value( other._value ) {}
1002
// If you want to use TS_ASSERT_EQUALS
1003
bool operator== ( const MyClass &other ) const { return _value == other._value; }
1005
// If you want to use TS_ASSERT_LESS_THAN
1006
bool operator== ( const MyClass &other ) const { return _value < other._value; }
1009
#ifdef CXXTEST_RUNNING
1010
#include <cxxtest/ValueTraits.h>
1011
#include <stdio.h>
1015
CXXTEST_TEMPLATE_INSTANTIATION
1016
class ValueTraits<MyClass>
1021
ValueTraits( const MyClass &m ) { sprintf( _s, "MyClass( %i )", m.value() ); }
1022
const char *asString() const { return _s; }
1025
#endif // CXXTEST_RUNNING
1029
<h5 class="subsubsection"><a name="TOC48"></a>4.3.5.1 Defining value traits for template classes</h5>
1031
<p>A simple modification to the above scheme allows you to define value
1032
traits for your template classes. Unfortunately, this syntax (partial
1033
template specialization) is not supported by some popular C++ compilers.
1036
<pre class="smallexample">
1037
<pre class="verbatim">
1038
template<class T>
1044
TMyClass( const T &value ) : _value( value );
1045
const T &value() const { return _value; }
1047
// CxxTest requires a copy constructor
1048
TMyClass( const TMyClass<T> &other ) : _value( other._value ) {}
1050
// If you want to use TS_ASSERT_EQUALS
1051
bool operator== ( const TMyClass<T> &other ) const { return _value == other._value; }
1054
#ifdef CXXTEST_RUNNING
1055
#include <cxxtest/ValueTraits.h>
1056
#include <typeinfo>
1057
#include <sstream>
1061
template<class T>
1062
class ValueTraits< TMyClass<T> >
1064
std::ostringstream _s;
1067
ValueTraits( const TMyClass<T> &t )
1068
{ _s << typeid(t).name() << "( " << t.value() << " )"; }
1069
const char *asString() const { return _s.str().c_str(); }
1072
#endif // CXXTEST_RUNNING
1076
<h4 class="subsection"><a name="TOC49"></a>4.3.6 Overriding the default value traits</h4>
1078
<font size=-2>(v2.8.2)</font>
1079
If you don't like the way CxxTest defines the default <code>ValueTrait</code>s,
1080
you can override them by <code>#define</code>-ing <code>CXXTEST_USER_VALUE_TRAITS</code>;
1081
this causes CxxTest to omit the default definitions, and from there on you are
1082
free to implement them as you like.
1084
<p>You can see a sample of this technique in <code>test/UserTraits.tpl</code> in
1085
the <code>cxxtest-selftest</code> archive.
1087
<h3 class="section"><a name="TOC50"></a>4.4 Global Fixtures</h3>
1089
<font size=-2>(v3.5.1)</font>
1090
The <code>setUp()</code> and <code>tearDown()</code> functions allow
1091
to to have code executed before and after each test. What if you want
1092
some code to be executed before all tests in <em>all</em> test suites?
1093
Rather than duplicate that code, you can use <dfn>global fixtures</dfn>.
1094
These are basically classes that inherit from
1095
<code>CxxTest::GlobalFixture</code>. All objects of such classes are
1096
automatically notified before and after each test case. It is best to
1097
create them as static objects so they get called right from the start.
1098
Look at <code>test/GlobalFixtures.h</code> in the <code>cxxtest-selftest</code>
1101
<p><em>Note:</em> Unlike <code>setUp()</code> and <code>tearDown()</code> in
1102
<code>TestSuite</code>, global fixtures should return a <code>bool</code> value to
1103
indicate success/failure.
1105
<h4 class="subsection"><a name="TOC51"></a>4.4.1 World fixtures</h4>
1107
<font size=-2>(v3.8.1)</font>
1108
CxxTest also allows you to specify code which is executed
1109
once at the start of the testing process (and the corresponding cleanup
1110
code). To do this, create (one or more) global fixture objects and
1111
implement <code>setUpWorld()</code>/<code>tearDownWorld()</code>. For an example,
1112
see <code>test/WorldFixtures.h</code> in the <code>cxxtest-selftest</code> archive.
1114
<h3 class="section"><a name="TOC52"></a>4.5 Mock Objects</h3>
1116
<font size=-2>(v3.10.0)</font>
1117
Mock Objects are a very useful testing tool, which
1118
consists (in a nutshell) of passing special objects to tested code. For
1119
instance, to test a class that implements some protocol over TCP, you
1120
might have it use an abstract <code>ISocket</code> interface and in the tests
1121
pass it a <code>MockSocket</code> object. This <code>MockSocket</code> object can
1122
then do anything your tests find useful, e.g. keep a log of all data
1123
"sent" to verify later.
1125
<p>So far, so good. But the problem when developing in C/C++ is that your
1126
code probably needs to call <em>global</em> functions which you cannot
1127
override. Just consider any code which uses <code>fopen()</code>,
1128
<code>fwrite()</code> and <code>fclose()</code>. It is not very elegant to have
1129
this code actually create files while being tested. Even more
1130
importantly, you (should) want to test how the code behaves when "bad"
1131
things happen, say when <code>fopen()</code> fails. Although for some cases
1132
you can cause the effects to happen in the test code, this quickly
1133
becomes "hairy" and unmaintainable.
1135
<p>CxxTest solves this problem by allowing you to override any global
1136
function while testing. Here is an outline of how it works, before we
1137
see an actual example:
1140
<li>For each function you want to override, you use the macro
1141
<code>CXXTEST_MOCK_GLOBAL</code> to "prepare" the function (all is explained
1142
below in excruciating detail).
1144
<li>In the tested code you do not call the global functions directly;
1145
rather, you access them in the <code>T</code> (for <em>Test</em>) namespace. For
1146
instance, your code needs to call <code>T::fopen()</code> instead of
1147
<code>fopen()</code>. This is the equivalent of using abstract interfaces
1148
instead of concrete classes.
1150
<li>You link the "real" binary with a source file that implements
1151
<code>T::fopen()</code> by simply calling the original <code>fopen()</code>.
1153
<li>You link the test binary with a source file that implements
1154
<code>T::fopen()</code> by calling a mock object.
1156
<li>To test, you should create a class that inherits <code>T::Base_fopen</code>
1157
and implement its <code>fopen()</code> function. Simply by creating an object
1158
of this class, calls made to <code>T::fopen()</code> will be redirected to it.
1162
<p>This may seem daunting at first, so let us work our way through a simple
1163
example. Say we want to override the well known standard library
1164
function <code>time()</code>.
1168
<li>Prepare a header file to be used by both the real and test code.
1169
<pre class="smallexample">
1170
<pre class="verbatim">
1172
#include <time.h>
1173
#include <cxxtest/Mock.h>
1175
CXXTEST_MOCK_GLOBAL( time_t, /* Return type */
1176
time, /* Name of the function */
1177
( time_t *t ), /* Prototype */
1178
( t ) /* Argument list */ );
1182
<li>In our tested code, we now include the special header instead of the
1183
system-supplied one, and call <code>T::time()</code> instead of <code>time()</code>.
1184
<pre class="smallexample">
1185
<pre class="verbatim">
1187
#include <T/time.h>
1189
int generateRandomNumber()
1191
return T::time( NULL ) * 3;
1196
<li>We also need to create a source file that implements <code>T::time()</code> by
1197
calling the real function. This is extremely easy: just define
1198
<code>CXXTEST_MOCK_REAL_SOURCE_FILE</code> before you include the header file:
1199
<pre class="smallexample">
1200
<pre class="verbatim">
1202
#define CXXTEST_MOCK_REAL_SOURCE_FILE
1203
#include <T/time.h>
1207
<li>Before we can start testing, we need a different implementation of
1208
<code>T::time()</code> for our tests. This is just as easy as the previous
1210
<pre class="smallexample">
1211
<pre class="verbatim">
1213
#define CXXTEST_MOCK_TEST_SOURCE_FILE
1214
#include <T/time.h>
1218
<li>Now comes the fun part. In our test code, all we need to do is create a
1219
mock, and the tested code will magically call it:
1220
<pre class="smallexample">
1221
<pre class="verbatim">
1223
#include <cxxtest/TestSuite.h>
1224
#include <T/time.h>
1226
class TheTimeIsOne : public T::Base_time
1229
time_t time( time_t * ) { return 1; }
1232
class TestRandom : public CxxTest::TestSuite
1238
TS_ASSERT_EQUALS( generateRandomNumber(), 3 );
1246
<h4 class="subsection"><a name="TOC53"></a>4.5.1 Actually doing it</h4>
1248
<p>I know that this might seem a bit heavy at first glance, but once you
1249
start using mock objects you will never go back. The hardest part may
1250
be getting this to work with your build system, which is why I have
1251
written a simple example much like this one in <code>sample/mock</code>, which
1252
uses GNU Make and G++.
1254
<h4 class="subsection"><a name="TOC54"></a>4.5.2 Advanced topic with mock functions</h4>
1256
<h5 class="subsubsection"><a name="TOC55"></a>4.5.2.1 Void functions</h5>
1258
<p>Void function are a little different, and you use
1259
<code>CXXTEST_MOCK_VOID_GLOBAL</code> to override them. This is identical to
1260
<code>CXXTEST_MOCK_GLOBAL</code> except that it doesn't specify the return
1261
type. Take a look in <code>sample/mock/T/stdlib.h</code> for a demonstation.
1263
<h5 class="subsubsection"><a name="TOC56"></a>4.5.2.2 Calling the real functions while testing</h5>
1265
<p>From time to time, you might want to let the tested code call the real
1266
functions (while being tested). To do this, you create a special mock
1267
object called e.g. <code>T::Real_time</code>. While an object of this class
1268
is present, calls to <code>T::time()</code> will be redirected to the real
1271
<h5 class="subsubsection"><a name="TOC57"></a>4.5.2.3 When there is no real function</h5>
1273
<p>Sometimes your code needs to call functions which are not available when
1274
testing. This happens for example when you test driver code using a
1275
user-mode test runner, and you need to call kernel functions. You can
1276
use CxxTest's mock framework to provide testable implementations for the
1277
test code, while maintaing the original functions for the real code.
1278
This you do with <code>CXXTEST_SUPPLY_GLOBAL</code> (and
1279
<code>CXXTEST_SUPPLY_VOID_GLOBAL</code>). For example, say you want to supply
1280
your code with the Win32 kernel function <code>IoCallDriver</code>:
1281
<pre class="smallexample">
1282
<pre class="verbatim">
1283
CXXTEST_SUPPLY_GLOBAL( NTSTATUS, /* Return type */
1284
IoCallDriver, /* Name */
1285
( PDEVICE_OBJECT Device, /* Prototype */
1287
( Device, Irp ) /* How to call */ );
1290
The tested code (your driver) can now call <code>IoCallDriver()</code>
1291
normally (no need for <code>T::</code>), and the test code uses
1292
<code>T::Base_IoCallDriver</code> as with normal mock objects.
1294
<p><strong>Note:</strong> Since these macros can also be used to actually declare
1295
the function prototypes (e.g. in the above example you might not be able
1296
to include the real <code><ntddk.h></code> from test code), they also have an
1297
<code>extern "C"</code> version which declares the functions with <code>C</code>
1298
linkage. These are <code>CXXTEST_SUPPLY_GLOBAL_C</code> and
1299
<code>CXXTEST_SUPPLY_GLOBAL_VOID_C</code>.
1301
<h5 class="subsubsection"><a name="TOC58"></a>4.5.2.4 Functions in namespaces</h5>
1303
<p>Sometimes the functions you want to override are not in the global
1304
namespace like <code>time()</code>: they may be global functions in other
1305
namespaces or even static class member functions. The default mock
1306
implementation isn't suitable for these. For them, you can use the
1307
generic <code>CXXTEST_MOCK</code>, which is best explained by example. Say you
1308
have a namespace <code>Files</code>, and you want to override the function
1309
<code>bool Files::FileExists( const String &name )</code>, so that the mock
1310
class will be called <code>T::Base_Files_FileExists</code> and the function to
1311
implement would be <code>fileExists</code>. You would define it thus (of
1312
course, you would normally want the mock class name and member function
1313
to be the same as the real function):
1314
<pre class="smallexample">
1315
<pre class="verbatim">
1316
CXXTEST_MOCK( Files_FileExists, /* Suffix of mock class */
1317
bool, /* Return type */
1318
fileExists, /* Name of mock member */
1319
( const String &name ), /* Prototype */
1320
Files::FileExists, /* Name of real function */
1321
( name ) /* Parameter list */ );
1324
Needless to say, there is also <code>CXXTEST_MOCK_VOID</code> for void functions.
1326
<p>There is also an equivalent version for <code>CXXTEST_SUPPLY_GLOBAL</code>, as
1327
demonstrated by another function from the Win32 DDK:
1328
<pre class="smallexample">
1329
<pre class="verbatim">
1330
CXXTEST_SUPPLY( AllocateIrp, /* => T::Base_AllocateIrp */
1331
PIRP, /* Return type */
1332
allocateIrp, /* Name of mock member */
1333
( CCHAR StackSize ), /* Prototype */
1334
IoAllocateIrp, /* Name of real function */
1335
( StackSize ) /* Parameter list */ );
1338
And, with this macro you have <code>CXXTEST_SUPPLY_VOID</code> and of course
1339
<code>CXXTEST_SUPPLY_C</code> and <code>CXXTEST_SUPPLY_VOID_C</code>.
1341
<h5 class="subsubsection"><a name="TOC59"></a>4.5.2.5 Overloaded functions</h5>
1343
<p>If you have two or more global functions which have the same name, you
1344
cannot create two mock classes with the same name. The solution is to
1345
use the general <code>CXXTEST_MOCK</code>/<code>CXXTEST_MOCK_VOID</code> as above:
1346
just give the two mock classes different names.
1348
<h5 class="subsubsection"><a name="TOC60"></a>4.5.2.6 Changing the mock namespace</h5>
1350
<p>Finally, if you don't like or for some reason can't use the <code>T::</code>
1351
namespace for mock functions, you can change it by defining
1352
<code>CXXTEST_MOCK_NAMESPACE</code>. Have fun.
1354
<h3 class="section"><a name="TOC61"></a>4.6 Test Listeners and Test Runners</h3>
1356
<p>A <code>TestListener</code> is a class that receives notifications about
1357
the testing process, notably which assertions failed. CxxTest defines
1358
a standard test listener class, <code>ErrorPrinter</code>, which is
1359
responsible for printing the dots and messages seen above. When the
1360
test runners generated in the examples run, they create an
1361
<code>ErrorPrinter</code> and pass it to
1362
<code>TestRunner::runAllTests()</code>. As you might have guessed, this
1363
functions runs all the test you've defined and reports to the
1364
<code>TestListener</code> it was passed.
1366
<h4 class="subsection"><a name="TOC62"></a>4.6.1 Other test listeners</h4>
1368
<p>If you don't like or can't use the <code>ErrorPrinter</code>, you can use
1369
any other test listener.
1370
To do this you have to omit the <code>--error-printer</code>, <code>--runner=</code>
1371
or <code>--gui=</code> switch when generating the tests file.
1372
It is then up to you to write the <code>main()</code> function, using the
1373
test listener of your fancy.
1375
<h5 class="subsubsection"><a name="TOC63"></a>4.6.1.1 The <code>stdio</code> printer</h5>
1377
<p>If the <code>ErrorPrinter</code>'s usage of <code>std::cout</code> clashes
1378
with your environment or is unsupported by your compiler, don't dispair!
1379
You may still be able to use the <code>StdioPrinter</code>, which does the
1380
exact same thing but uses good old <code>printf()</code>.
1382
<p>To use it, invoke <code>cxxtestgen.pl</code> with the <code>--runner=StdioPrinter</code> option.
1384
<font size=-2>(v3.8.5)</font>
1385
<strong>Note:</strong> <code>cxxtest/StdioPrinter</code> makes
1386
reference to <code>stdout</code> as the default output stream. In some
1387
environments you may have <code><stdio.h></code> but not <code>stdout</code>, which
1388
will cause compiler errors. To overcome this problem, use
1389
<code>--runner=StdioFilePrinter</code>, which is exactly the same as
1390
<code>--runner=StdioPrinter</code>, but with no default output stream.
1392
<h5 class="subsubsection"><a name="TOC64"></a>4.6.1.2 The Yes/No runner</h5>
1394
<p>As an example, CxxTest also provides the simplest possible test listener,
1395
one that just reports if there were any failures.
1396
You can see an example of using this listener in <code>sample/yes_no_runner.cpp</code>.
1398
<h5 class="subsubsection"><a name="TOC65"></a>4.6.1.3 Template files</h5>
1400
<p>To use you own test runner, or to use the supplied ones in different ways, you can use
1401
CxxTest <em>template files</em>. These are ordinary source files with the embedded "command"
1402
<code><CxxTest world></code> which tells <code>cxxtestgen.pl</code> to insert the world definition
1403
at that point. You then specify the template file using the <code>--template</code> option.
1405
<p>See <code>samples/file_printer.tpl</code> for an example.
1407
<p><strong>Note:</strong> CxxTest needs to insert certain definitions and
1408
<code>#include</code> directives in the runner file. It normally does that
1409
before the first <code>#include <cxxtest/*.h></code> found in the template
1410
file. If this behvaior is not what you need, use the "command"
1411
<code><CxxTest preamble></code>. See <code>test/preamble.tpl</code> in the
1412
<code>cxxtest-selftest</code> archive for an example of this.
1414
<h3 class="section"><a name="TOC66"></a>4.7 Dynamically creating test suites</h3>
1416
<p><a name="dynamic"></a>
1417
Usually, your test suites are instantiated statically in the tests file, i.e. say you
1418
defined <code>class MyTest : public CxxTest::TestSuite</code>, the generated file will
1419
contain something like <code>static MyTest g_MyTest;</code>.
1421
<p>If, however, your test suite must be created dynamically (it may need a constructor,
1422
for instance), CxxTest doesn't know how to create it unless you tell it how.
1423
You do this by writing two static functions, <code>createSuite()</code> and <code>destroySuite()</code>.
1425
<p>See <code>sample/CreatedTest.h</code> for a demonstration.
1427
<h3 class="section"><a name="TOC67"></a>4.8 Static initialization</h3>
1429
<font size=-2>(v3.9.0)</font>
1430
The generated runner source file depends quite
1431
heavily on static initialization of the various "description" object
1432
used to run your tests. If your compiler/linker has a problem with this
1433
approach, use the <code>--no-static-init</code> option.
1435
<h2 class="appendix"><a name="TOC68"></a>Appendix A Command line options</h2>
1437
<p>Here are the different command line options for <code>cxxtestgen</code>:
1439
<h3 class="section"><a name="TOC69"></a>A.1 <code>--version</code></h3>
1441
<font size=-2>(v3.7.1)</font>
1442
Specify <code>--version</code> or <code>-v</code> to see the version of CxxTest you are using.
1444
<h3 class="section"><a name="TOC70"></a>A.2 <code>--output</code></h3>
1446
<p>Specify <code>--output=FILE</code> or <code>-o FILE</code> to determine the output file name.
1448
<h3 class="section"><a name="TOC71"></a>A.3 <code>--error-printer</code></h3>
1450
<p>This option creates a test runner which uses the standard error printer class.
1452
<h3 class="section"><a name="TOC72"></a>A.4 <code>--runner</code></h3>
1454
<p>Specify <code>--runner=CLASS</code> to generate a test
1455
runner that <code>#include</code>s <code><cxxtest/CLASS.h></code> and uses
1456
<code>CxxTest::CLASS</code> as the test runner.
1458
<p>The currently available runners are:
1460
<dt><code>--runner=ErrorPrinter</code>
1461
<dd>This is the standard error printer, which formats its output to <code>std::cout</code>.
1463
<br><dt><code>--runner=ParenPrinter</code>
1464
<dd>Identical to <code>ErrorPrinter</code> except that it prints line numbers in parantheses.
1465
This is the way Visual Studio expects it.
1467
<br><dt><code>--runner=StdioPrinter</code>
1468
<dd>The same as <code>ErrorPrinter</code> except that it uses <code>printf</code>
1469
instead of <code>cout</code>.
1471
<br><dt><code>--runner=YesNoRunner</code>
1472
<dd>This runner doesn't produce any output, merely returns a true/false result.
1476
<h3 class="section"><a name="TOC73"></a>A.5 <code>--gui</code></h3>
1478
<p>Specify <code>--gui=CLASS</code> to generate a test runner that
1479
<code>#include</code>s <code><cxxtest/CLASS.h></code> and uses <code>CxxTest::CLASS</code>
1480
to display a graphical user interface. This option can be combined with
1481
the <code>--runner</code> option to determine the text-mode output format.
1482
The default is the standard error printer.
1484
<p>There are three different GUIs:
1486
<dt><code>--gui=Win32Gui</code>
1487
<dd>A native Win32 GUI. It has been tested on Windows 98, 2000 and XP and
1488
should work unmodified on other 32-bit versions of Windows.
1490
<br><dt><code>--gui=X11Gui</code>
1491
<dd>A native XLib GUI. This GUI is very spartan and should work on any X server.
1493
<br><dt><code>--gui=QtGui</code>
1494
<dd>A GUI that uses the Qt library from Troll. It has been tested with Qt versiond 2.2.1 and 3.0.1.
1497
<h3 class="section"><a name="TOC74"></a>A.6 <code>--include</code></h3>
1499
<font size=-2>(v3.5.1)</font>
1500
If you specify <code>--include=FILE</code>, <code>cxxtestgen</code> will add
1501
<code>#include "FILE"</code> to the runner before including any other header.
1502
This allows you to define things that modify the behavior of CxxTest,
1503
e.g. your own ValueTraits.
1505
<p><strong>Note:</strong> If you want the runner to <code>#inculde <FILE></code>, specify
1506
it on the command line, e.g. <code>--include=<FILE></code>. You will most
1507
likely need to use shell escapes, e.g. <code>"--include=<FILE>"</code> or
1508
<code>--include=\<FILE\></code>.
1510
<p>Examples: <code>--include=TestDefs.h</code> or <code>--include=\<GlobalDefs.h\></code>.
1512
<h3 class="section"><a name="TOC75"></a>A.7 <code>--template</code></h3>
1514
<p>Specify <code>--template=FILE</code> to use <code>FILE</code> as a template file.
1515
This is for cases for which <code>--runner</code> and/or <code>--include</code>
1516
are not enough. One example is the Windows DDK; see
1517
<code>sample/winddk</code> in the distribution.
1519
<h3 class="section"><a name="TOC76"></a>A.8 <code>--have-eh</code></h3>
1521
<font size=-2>(v2.8.4)</font>
1522
<code>cxxtestgen</code> will scan its input files for uses of exception
1523
handling; if found, the <code>TS_</code> macros will catch exceptions,
1524
allowing the testing to continue. Use <code>--have-eh</code> to tell
1525
<code>cxxtestgen</code> to enable that functionality even if exceptions
1526
are not used in the input files.
1528
<h3 class="section"><a name="TOC77"></a>A.9 <code>--no-eh</code></h3>
1530
<font size=-2>(v3.8.5)</font>
1531
If you want <code>cxxtestgen</code> to ignore what may look as uses of
1532
exception handling in your test files, specify <code>--no-eh</code>.
1534
<h3 class="section"><a name="TOC78"></a>A.10 <code>--have-std</code></h3>
1536
<font size=-2>(v3.10.0)</font>
1537
Same as <code>--have-eh</code> but for the standard library;
1538
basically, if you use this flag, CxxTest will print the values of
1539
<code>std::string</code>.
1541
<p><strong>Note:</strong> If you reference the standard library anywhere in your
1542
test files, CxxTest will (usually) recognize it and automatically define
1545
<h3 class="section"><a name="TOC79"></a>A.11 <code>--no-std</code></h3>
1547
<font size=-2>(v3.10.0)</font>
1548
The counterpart to <code>--have-std</code>, this tells
1549
CxxTest to ignore any evidence it finds for the <code>std::</code> namespace
1550
in your code. Use it if your environment does not support <code>std::</code>
1551
but <code>cxxtestgen</code> thinks it does.
1553
<h3 class="section"><a name="TOC80"></a>A.12 <code>--longlong</code></h3>
1555
<font size=-2>(v3.6.0)</font>
1556
Specify <code>--longlong=TYPE</code> to have CxxTest recognize <code>TYPE</code>
1557
as "long long" (e.g. <code>--longlong=__int64</code>). If you specify
1558
just <code>--longlong=</code> (no type), CxxTest will use the default type
1559
name of <code>long long</code>.
1561
<h3 class="section"><a name="TOC81"></a>A.13 <code>--abort-on-fail</code></h3>
1563
<font size=-2>(v2.8.2)</font>
1564
This useful option tells CxxTest to abort the current test when any
1565
<code>TS_ASSERT</code> macro has failed.
1567
<h3 class="section"><a name="TOC82"></a>A.14 <code>--part</code></h3>
1569
<font size=-2>(v3.5.1)</font>
1570
This option tells CxxTest now to write the CxxTest globals in the output
1571
file. Use this to link together more than one generated file.
1573
<h3 class="section"><a name="TOC83"></a>A.15 <code>--root</code></h3>
1575
<font size=-2>(v3.5.1)</font>
1576
This is the counterpart of <code>--part</code>; it makes sure that the
1577
Cxxtest globals are written to the output file. If you specify this
1578
option, you can use <code>cxxtestgen</code> without any input files to
1579
create a file that hold only the "root" runner.
1581
<h3 class="section"><a name="TOC84"></a>A.16 <code>--no-static-init</code></h3>
1583
<font size=-2>(v3.9.0)</font>
1584
Use this option if you encounter problems with the static
1585
initializations in the test runner.
1587
<h2 class="appendix"><a name="TOC85"></a>Appendix B Controlling the behavior of CxxTest</h2>
1589
<p>Here are various <code>#define</code>s you can use to modify how CxxTest
1590
works. You will need to <code>#define</code> them <em>before</em> including any
1591
of the CxxTest headers, so use them in a template file or with the
1592
<code>--include</code> option.
1594
<h3 class="section"><a name="TOC86"></a>B.1 <code>CXXTEST_HAVE_STD</code></h3>
1596
<p>This is equivalent to the <code>--have-std</code> option.
1598
<h3 class="section"><a name="TOC87"></a>B.2 <code>CXXTEST_HAVE_EH</code></h3>
1600
<p>This is equivalent to the <code>--have-eh</code> option.
1602
<h3 class="section"><a name="TOC88"></a>B.3 <code>CXXTEST_ABORT_TEST_ON_FAIL</code></h3>
1604
<font size=-2>(v2.8.0)</font>
1605
This is equivalent to the <code>--abort-on-fail</code> option.
1607
<h3 class="section"><a name="TOC89"></a>B.4 <code>CXXTEST_USER_VALUE_TRAITS</code></h3>
1609
<p>This tells CxxTest you wish to define you own ValueTraits. It will only
1610
declare the default traits, which dump up to 8 bytes of the data as hex
1613
<h3 class="section"><a name="TOC90"></a>B.5 <code>CXXTEST_OLD_TEMPLATE_SYNTAX</code></h3>
1615
<p>Some compilers (e.g. Borland C++ 5) don't support the standard way of
1616
instantiating template classes. Use this define to overcome the problem.
1618
<h3 class="section"><a name="TOC91"></a>B.6 <code>CXXTEST_OLD_STD</code></h3>
1620
<p>Again, this is used to support pre-<code>std::</code> standard libraries.
1622
<h3 class="section"><a name="TOC92"></a>B.7 <code>CXXTEST_MAX_DUMP_SIZE</code></h3>
1624
<p>This sets the standard maximum number of bytes to dump if
1625
<a href="#sameData"><code>TS_ASSERT_SAME_DATA(</code><em></em><code>)</code></a> fails. The default is 0, meaning
1628
<h3 class="section"><a name="TOC93"></a>B.8 <code>CXXTEST_DEFAULT_ABORT</code></h3>
1630
<p>This sets the default value of the dynamic "abort on fail" flag. Of
1631
course, this flag is only used when "abort on fail" is enabled.
1633
<h3 class="section"><a name="TOC94"></a>B.9 <code>CXXTEST_LONGLONG</code></h3>
1635
<p>This is equivalent to <code>--longlong</code>.
1637
<h2 class="appendix"><a name="TOC95"></a>Appendix C Runtime options</h2>
1639
<p>The following functions can be called during runtime (i.e. from your
1640
tests) to control the behavior of CxxTest. They are reset to their
1641
default values after each test is executed (more precisely, after
1642
<code>tearDown()</code> is called). Consequently, if you set them in the
1643
<code>setUp()</code> function, they will be valid for the entire test suite.
1645
<h3 class="section"><a name="TOC96"></a>C.1 <code>setAbortTestOnFail( bool )</code></h3>
1647
<p>This only works when you have exception handling. It can be used to
1648
tell CxxTest to temporarily change its behavior. The default value of
1649
the flag is <code>false</code>, <code>true</code> if you set <code>--abort-on-fail</code>,
1650
or <code>CXXTEST_DEFAULT_ABORT</code> if you <code>#define</code> it.
1652
<h3 class="section"><a name="TOC97"></a>C.2 <code>setMaxDumpSize( unsigned )</code></h3>
1654
<p>This temporarily sets the maximum number of bytes to dump if
1655
<a href="#sameData"><code>TS_ASSERT_SAME_DATA(</code><em></em><code>)</code></a> fails. The default is 0, meaning
1656
no limit, or <code>CXXTEST_MAX_DUMP_SIZE</code> if you <code>#define</code> it.
1658
<h2 class="appendix"><a name="TOC98"></a>Appendix D Version history</h2>
1661
<li><strong>Version 3.10.0 (2004-11-20)</strong>
1663
<li>Added mock framework for global functions
1664
<li>Added <code>TS_ASSERT_THROWS_ASSERT</code> and <code>TS_ASSERT_THROWS_EQUALS</code>
1665
<li>Added <code>CXXTEST_ENUM_TRAITS</code>
1666
<li>Improved support for STL classes (vector, map etc.)
1667
<li>Added support for Digital Mars compiler
1668
<li>Reduced root/part compilation time and binary size
1669
<li>Support C++-style commenting of tests
1671
<li><strong>Version 3.9.1 (2004-01-19)</strong>
1673
<li>Fixed small bug with runner exit code
1674
<li>Embedded test suites are now deprecated
1676
<li><strong>Version 3.9.0 (2004-01-17)</strong>
1678
<li>Added <code>TS_TRACE</code>
1679
<li>Added <code>--no-static-init</code>
1680
<li>CxxTest::<code>setAbortTestOnFail()</code> works even without <code>--abort-on-fail</code>
1682
<li><strong>Version 3.8.5 (2004-01-08)</strong>
1684
<li>Added <code>--no-eh</code>
1685
<li>Added <code>CxxTest::setAbortTestOnFail()</code> and <code>CXXTEST_DEFAULT_ABORT</code>
1686
<li>Added <code>CxxTest::setMaxDumpSize()</code>
1687
<li>Added StdioFilePrinter
1689
<li><strong>Version 3.8.4 (2003-12-31)</strong>
1691
<li>Split distribution into cxxtest and cxxtest-selftest
1692
<li>Added <code>sample/msvc/FixFiles.bat</code>
1694
<li><strong>Version 3.8.3 (2003-12-24)</strong>
1696
<li>Added <code>TS_ASSERT_PREDICATE</code>
1697
<li>Template files can now specify where to insert the preamble
1698
<li>Added a sample Visual Studio workspace in <code>sample/msvc</code>
1699
<li>Can compile in MSVC with warning level 4
1700
<li>Changed output format slightly
1702
<li><strong>Version 3.8.1 (2003-12-21)</strong>
1704
<li>Fixed small bug when using multiple <code>--part</code> files.
1705
<li>Fixed X11 GUI crash when there's no X server.
1706
<li>Added <code>GlobalFixture::setUpWorld()</code>/<code>tearDownWorld()</code>
1707
<li>Added <code>leaveOnly()</code>, <code>activateAllTests()</code> and <code>sample/only.tpl</code>
1708
<li>Should now run without warnings on Sun compiler.
1710
<li><strong>Version 3.8.0 (2003-12-13)</strong>
1712
<li>Fixed bug where <code>Root.cpp</code> needed exception handling
1713
<li>Added <code>TS_ASSERT_RELATION</code>
1714
<li><code>TSM_</code> macros now also tell you what went wrong
1715
<li>Renamed <code>Win32Gui::free()</code> to avoid clashes
1716
<li>Now compatible with more versions of Borland compiler
1717
<li>Improved the documentation
1719
<li><strong>Version 3.7.1 (2003-09-29)</strong>
1721
<li>Added <code>--version</code>
1722
<li>Compiles with even more exotic g++ warnings
1723
<li>Win32 Gui compiles with UNICODE
1724
<li>Should compile on some more platforms (Sun Forte, HP aCC)
1726
<li><strong>Version 3.7.0 (2003-09-20)</strong>
1728
<li>Added <code>TS_ASSERT_LESS_THAN_EQUALS</code>
1731
<li><strong>Version 3.6.1 (2003-09-15)</strong>
1734
<li>Improved portability some more
1736
<li><strong>Version 3.6.0 (2003-09-04)</strong>
1738
<li>Added <code>--longlong</code>
1739
<li>Some portability improvements
1741
<li><strong>Version 3.5.1 (2003-09-03)</strong>
1743
<li>Major internal rewrite of macros
1744
<li>Added <code>TS_ASSERT_SAME_DATA</code>
1745
<li>Added <code>--include</code> option
1746
<li>Added <code>--part</code> and <code>--root</code> to enable splitting the test runner
1747
<li>Added global fixtures
1748
<li>Enhanced Win32 GUI with timers, <code>-keep</code> and <code>-title</code>
1749
<li>Now compiles with strict warnings
1751
<li><strong>Version 3.1.1 (2003-08-27)</strong>
1753
<li>Fixed small bug in <code>TS_ASSERT_THROWS_*()</code>
1755
<li><strong>Version 3.1.0 (2003-08-23)</strong>
1757
<li>Default ValueTraits now dumps value as hex bytes
1758
<li>Fixed double invocation bug (e.g. <code>TS_FAIL(</code><code>functionWithSideEffects()</code>))
1759
<li><code>TS_ASSERT_THROWS*()</code> are now "abort on fail"-friendly
1760
<li>Win32 GUI now supports Windows 98 and doesn't need comctl32.lib
1762
<li><strong>Version 3.0.1 (2003-08-07)</strong>
1764
<li>Added simple GUI for X11, Win32 and Qt
1765
<li>Added <code>TS_</code><code>WARN()</code> macro
1766
<li>Removed <code>--exit-code</code>
1767
<li>Improved samples
1768
<li>Improved support for older (pre-std::) compilers
1769
<li>Made a PDF version of the User's Guide
1771
<li><strong>Version 2.8.4 (2003-07-21)</strong>
1773
<li>Now supports g++-3.3
1774
<li>Added <code>--have-eh</code>
1775
<li>Fixed bug in <code>numberToString()</code>
1777
<li><strong>Version 2.8.3 (2003-06-30)</strong>
1779
<li>Fixed bugs in cxxtestgen.pl
1780
<li>Fixed warning for some compilers in ErrorPrinter/StdioPrinter
1781
<li>Thanks Martin Jost for pointing out these problems!
1783
<li><strong>Version 2.8.2 (2003-06-10)</strong>
1785
<li>Fixed bug when using <code>CXXTEST_ABORT_TEST_ON_FAIL</code> without standard library
1786
<li>Added <code>CXXTEST_USER_TRAITS</code>
1787
<li>Added <code>--abort-on-fail</code>
1789
<li><strong>Version 2.8.1 (2003-01-16)</strong>
1791
<li>Fixed <code>charToString()</code> for negative chars
1793
<li><strong>Version 2.8.0 (2003-01-13)</strong>
1795
<li>Added <code>CXXTEST_ABORT_TEST_ON_FAIL</code> for xUnit-like behaviour
1796
<li>Added <code>sample/winddk</code>
1797
<li>Improved ValueTraits
1798
<li>Improved output formatter
1799
<li>Started version history
1801
<li><strong>Version 2.7.0 (2002-09-29)</strong>
1803
<li>Added embedded test suites
1804
<li>Major internal improvements
1809
<p><a name="contents"></a>
1811
<div class="contents">
1812
<h2>Table of Contents</h2>
1814
<li><a name="toc_TOC0" href="#TOC0">1 Introduction</a>
1816
<li><a href="#TOC1">1.1 About this guide</a>
1818
<li><a name="toc_TOC2" href="#TOC2">2 Getting started</a>
1820
<li><a href="#TOC3">2.1 Getting CxxTest</a>
1821
<li><a href="#TOC4">2.2 Your first test!</a>
1822
<li><a href="#TOC5">2.3 Your second test</a>
1823
<li><a href="#TOC6">2.4 Graphical user interface</a>
1825
<li><a name="toc_TOC7" href="#TOC7">3 <em>Really</em> using CxxTest</a>
1827
<li><a href="#TOC8">3.1 What can you test</a>
1829
<li><a href="#TOC9">3.1.1 <code>TS_FAIL</code></a>
1830
<li><a href="#TOC10">3.1.2 <code>TS_ASSERT</code></a>
1831
<li><a href="#TOC11">3.1.3 <code>TS_ASSERT_EQUALS</code></a>
1832
<li><a href="#TOC12">3.1.4 <code>TS_ASSERT_SAME_DATA</code></a>
1833
<li><a href="#TOC13">3.1.5 <code>TS_ASSERT_DELTA</code></a>
1834
<li><a href="#TOC14">3.1.6 <code>TS_ASSERT_DIFFERS</code></a>
1835
<li><a href="#TOC15">3.1.7 <code>TS_ASSERT_LESS_THAN</code></a>
1836
<li><a href="#TOC16">3.1.8 <code>TS_ASSERT_LESS_THAN_EQUALS</code></a>
1837
<li><a href="#TOC17">3.1.9 <code>TS_ASSERT_PREDICATE</code></a>
1838
<li><a href="#TOC18">3.1.10 <code>TS_ASSERT_RELATION</code></a>
1839
<li><a href="#TOC19">3.1.11 <code>TS_ASSERT_THROWS</code> and friends</a>
1840
<li><a href="#TOC20">3.1.12 <code>TS_TRACE</code> and <code>TS_WARN</code></a>
1841
<li><a href="#TOC21">3.1.13 The <code>ETS_</code> macros</a>
1842
<li><a href="#TOC22">3.1.14 The <code>TSM_</code> macros</a>
1844
<li><a href="#TOC23">3.1.14.1 The <code>ETSM_</code> macros</a>
1847
<li><a href="#TOC24">3.2 Running the samples</a>
1848
<li><a href="#TOC25">3.3 Test fixtures</a>
1850
<li><a href="#TOC26">3.3.1 Test suite level fixtures</a>
1852
<li><a href="#TOC27">3.4 Integrating with your build environment</a>
1854
<li><a href="#TOC28">3.4.1 Overview</a>
1855
<li><a href="#TOC29">3.4.2 Actually doing it</a>
1857
<li><a href="#TOC30">3.4.2.1 Using Makefiles</a>
1858
<li><a href="#TOC31">3.4.2.2 Using Cons</a>
1859
<li><a href="#TOC32">3.4.2.3 Using Microsoft Visual Studio</a>
1860
<li><a href="#TOC33">3.4.2.4 Using Microsoft Windows DDK</a>
1863
<li><a href="#TOC34">3.5 Graphical user interface</a>
1865
<li><a href="#TOC35">3.5.1 Starting the GUI minimized</a>
1866
<li><a href="#TOC36">3.5.2 Leaving the GUI open</a>
1867
<li><a href="#TOC37">3.5.3 Screenshots!</a>
1870
<li><a name="toc_TOC38" href="#TOC38">4 Advanced topics</a>
1872
<li><a href="#TOC39">4.1 Aborting tests after failures</a>
1874
<li><a href="#TOC40">4.1.1 Controlling this behavior at runtime</a>
1876
<li><a href="#TOC41">4.2 Commenting out tests</a>
1877
<li><a href="#TOC42">4.3 Comparing equality for your own types</a>
1879
<li><a href="#TOC43">4.3.1 The equality operator</a>
1880
<li><a href="#TOC44">4.3.2 Value traits</a>
1881
<li><a href="#TOC45">4.3.3 Unknown types</a>
1882
<li><a href="#TOC46">4.3.4 Enumeration traits</a>
1883
<li><a href="#TOC47">4.3.5 Defining new value traits</a>
1885
<li><a href="#TOC48">4.3.5.1 Defining value traits for template classes</a>
1887
<li><a href="#TOC49">4.3.6 Overriding the default value traits</a>
1889
<li><a href="#TOC50">4.4 Global Fixtures</a>
1891
<li><a href="#TOC51">4.4.1 World fixtures</a>
1893
<li><a href="#TOC52">4.5 Mock Objects</a>
1895
<li><a href="#TOC53">4.5.1 Actually doing it</a>
1896
<li><a href="#TOC54">4.5.2 Advanced topic with mock functions</a>
1898
<li><a href="#TOC55">4.5.2.1 Void functions</a>
1899
<li><a href="#TOC56">4.5.2.2 Calling the real functions while testing</a>
1900
<li><a href="#TOC57">4.5.2.3 When there is no real function</a>
1901
<li><a href="#TOC58">4.5.2.4 Functions in namespaces</a>
1902
<li><a href="#TOC59">4.5.2.5 Overloaded functions</a>
1903
<li><a href="#TOC60">4.5.2.6 Changing the mock namespace</a>
1906
<li><a href="#TOC61">4.6 Test Listeners and Test Runners</a>
1908
<li><a href="#TOC62">4.6.1 Other test listeners</a>
1910
<li><a href="#TOC63">4.6.1.1 The <code>stdio</code> printer</a>
1911
<li><a href="#TOC64">4.6.1.2 The Yes/No runner</a>
1912
<li><a href="#TOC65">4.6.1.3 Template files</a>
1915
<li><a href="#TOC66">4.7 Dynamically creating test suites</a>
1916
<li><a href="#TOC67">4.8 Static initialization</a>
1918
<li><a name="toc_TOC68" href="#TOC68">Appendix A Command line options</a>
1920
<li><a href="#TOC69">A.1 <code>--version</code></a>
1921
<li><a href="#TOC70">A.2 <code>--output</code></a>
1922
<li><a href="#TOC71">A.3 <code>--error-printer</code></a>
1923
<li><a href="#TOC72">A.4 <code>--runner</code></a>
1924
<li><a href="#TOC73">A.5 <code>--gui</code></a>
1925
<li><a href="#TOC74">A.6 <code>--include</code></a>
1926
<li><a href="#TOC75">A.7 <code>--template</code></a>
1927
<li><a href="#TOC76">A.8 <code>--have-eh</code></a>
1928
<li><a href="#TOC77">A.9 <code>--no-eh</code></a>
1929
<li><a href="#TOC78">A.10 <code>--have-std</code></a>
1930
<li><a href="#TOC79">A.11 <code>--no-std</code></a>
1931
<li><a href="#TOC80">A.12 <code>--longlong</code></a>
1932
<li><a href="#TOC81">A.13 <code>--abort-on-fail</code></a>
1933
<li><a href="#TOC82">A.14 <code>--part</code></a>
1934
<li><a href="#TOC83">A.15 <code>--root</code></a>
1935
<li><a href="#TOC84">A.16 <code>--no-static-init</code></a>
1937
<li><a name="toc_TOC85" href="#TOC85">Appendix B Controlling the behavior of CxxTest</a>
1939
<li><a href="#TOC86">B.1 <code>CXXTEST_HAVE_STD</code></a>
1940
<li><a href="#TOC87">B.2 <code>CXXTEST_HAVE_EH</code></a>
1941
<li><a href="#TOC88">B.3 <code>CXXTEST_ABORT_TEST_ON_FAIL</code></a>
1942
<li><a href="#TOC89">B.4 <code>CXXTEST_USER_VALUE_TRAITS</code></a>
1943
<li><a href="#TOC90">B.5 <code>CXXTEST_OLD_TEMPLATE_SYNTAX</code></a>
1944
<li><a href="#TOC91">B.6 <code>CXXTEST_OLD_STD</code></a>
1945
<li><a href="#TOC92">B.7 <code>CXXTEST_MAX_DUMP_SIZE</code></a>
1946
<li><a href="#TOC93">B.8 <code>CXXTEST_DEFAULT_ABORT</code></a>
1947
<li><a href="#TOC94">B.9 <code>CXXTEST_LONGLONG</code></a>
1949
<li><a name="toc_TOC95" href="#TOC95">Appendix C Runtime options</a>
1951
<li><a href="#TOC96">C.1 <code>setAbortTestOnFail( bool )</code></a>
1952
<li><a href="#TOC97">C.2 <code>setMaxDumpSize( unsigned )</code></a>
1954
<li><a name="toc_TOC98" href="#TOC98">Appendix D Version history</a>
added
removed
cxxtest/docs/guide.html
