1 <html lang="en">
2 <head>
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">
8 </head>
9 <body>
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:
18 <ul>
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)
23 </ul>
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
28 even display a GUI.
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:
59 <ol type=1 start=1>
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">
70 // MyTestSuite.h
71 #include <cxxtest/TestSuite.h>
73 class MyTestSuite : public CxxTest::TestSuite
74 {
75 public:
76 void testAddition( void )
77 {
78 TS_ASSERT( 1 + 1 > 1 );
79 TS_ASSERT_EQUALS( 1 + 1, 2 );
80 }
81 };
82 </pre>
83 </pre>
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
89 </pre>
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
95 </pre>
97 </p><li>You would then simply compile the resulting file:
99 <pre class="verbatim">
100 # g++ -o runner runner.cpp
101 </pre>
103 <p>or perhaps
105 <pre class="verbatim">
106 C:\tmp> cl -GX -o runner.exe runner.cpp
107 </pre>
109 <p>or maybe even
111 <pre class="verbatim">
112 C:\tmp> bcc32 -erunner.exe runner.cpp
113 </pre>
115 </p><li>Finally, you run the tests and enjoy a well tested piece of software:
117 <pre class="verbatim">
118 # ./runner
119 Running 1 test.OK!
120 </pre>
122 </ol>
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">
131 // MyTestSuite.h
132 #include <cxxtest/TestSuite.h>
134 class MyTestSuite : public CxxTest::TestSuite
135 {
136 public:
137 void testAddition( void )
138 {
139 TS_ASSERT( 1 + 1 > 1 );
140 TS_ASSERT_EQUALS( 1 + 1, 2 );
141 }
143 void testMultiplication( void )
144 {
145 TS_ASSERT_EQUALS( 2 * 2, 5 );
146 }
147 };
148 </pre>
149 </pre>
151 <p>Generate, compile and run the test runner, and you will get this:
153 <pre class="smallexample">
154 <pre class="verbatim">
155 # ./runner
156 Running 2 tests.
157 MyTestSuite.h:15: Expected (2 * 2 == 5), found (4 != 5)
158 Failed 1 of 2 tests
159 Success rate: 50%
160 </pre>
161 </pre>
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:
170 <ul>
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.
184 </ul>
186 <p>See <a href="#GUI">Graphical user interface</a> and <a href="#samples">Running the samples</a> for
187 more information.
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.
277 For example:
279 <pre class="smallexample">
280 <pre class="verbatim">
281 void testSomething( void )
282 {
283 TS_FAIL( "I don't know how to test this!" );
284 }
285 </pre>
286 </pre>
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
294 use!) An example:
296 <pre class="smallexample">
297 <pre class="verbatim">
298 void testSquare( void )
299 {
300 MyFileLibrary::createEmptyFile( "test.bin" );
301 TS_ASSERT( access( "test.bin", 0 ) == 0 );
302 }
303 </pre>
304 </pre>
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 )
316 {
317 TS_ASSERT_EQUALS( square(-5), 25 );
318 }
319 </pre>
320 </pre>
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
330 values.
332 <pre class="smallexample">
333 <pre class="verbatim">
334 void testCopyMemory( void )
335 {
336 char input[77], output[77];
337 myCopyMemory( output, input, 77 );
338 TS_ASSERT_SAME_DATA( input, output, 77 );
339 }
340 </pre>
341 </pre>
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 )
354 {
355 TS_ASSERT_DELTA( squareRoot(4.0), 2.0, 0.00001 );
356 }
357 </pre>
358 </pre>
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 )
370 {
371 int first = generateNumber();
372 int second = generateNumber();
373 TS_ASSERT_DIFFERS( first, second );
374 }
375 </pre>
376 </pre>
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 )
387 {
388 TS_ASSERT_LESS_THAN( 23, findLargerNumber(23) );
389 }
390 </pre>
391 </pre>
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 )
403 {
404 TS_ASSERT_LESS_THAN_EQUALS( bufferSize(), MAX_BUFFER_SIZE );
405 }
406 </pre>
407 </pre>
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">
422 class IsPrime
423 {
424 public:
425 bool operator()( unsigned ) const;
426 };
428 // ...
430 void testPrimeGenerator( void )
431 {
432 TS_ASSERT_PREDICATE( IsPrime, generatePrime() );
433 }
434 </pre>
435 </pre>
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>
442 Closely related to
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 )
455 {
456 TS_ASSERT_RELATION( std::greater<int>, ticketsSold(), 1000 );
457 }
458 </pre>
459 </pre>
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
478 example.
480 <pre class="smallexample">
481 <pre class="verbatim">
482 void testFunctionsWhichThrowExceptions( void )
483 {
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 ) );
492 }
493 </pre>
494 </pre>
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>
499 <a name="trace"></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 )
509 {
510 TS_WARN( "TODO: Write some tests!" );
511 TS_WARN( "TODO: Make $$$ fast!" );
512 }
513 </pre>
514 </pre>
516 <p>In the GUI, <code>TS_WARN</code> sets the bar color to yellow (unless it was
517 already red).
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()
533 {
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() ); }
540 }
541 </pre>
542 </pre>
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
556 {
557 public:
558 void testValues()
559 {
560 checkValue( 0, "My hovercraft" );
561 checkValue( 1, "is full" );
562 checkValue( 2, "of eels" );
563 }
565 void checkValue( unsigned value, const char *message )
566 {
567 TSM_ASSERT( message, value );
568 TSM_ASSERT_EQUALS( message, value, value * value );
569 }
570 };
571 </pre>
572 </pre>
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
601 the mess you left.
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>
607 after each test.
609 <pre class="smallexample">
610 <pre class="verbatim">
611 class TestFileOps : public CxxTest::TestSuite
612 {
613 public:
614 void setUp() { mkdir( "playground" ); }
615 void tearDown() { system( "rm -Rf playground"); }
617 void testCreateFile()
618 {
619 FileCreator fc( "playground" );
620 fc.createFile( "test.bin" );
621 TS_ASSERT_EQUALS( access( "playground/test.bin", 0 ), 0 );
622 }
623 };
624 </pre>
625 </pre>
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:
647 <ul>
648 <li>Split the application into a library and a main module that just calls
649 the library classes.
650 This way, the test runner will be able to access all your classes through
651 the library.
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.
655 </ul>
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
674 lib: ...
676 app: ...
678 # A rule that runs the unit tests
679 run_tests: runner
680 ./runner
682 # How to build the test runner
683 runner: runner.cpp lib
684 g++ -o $@ $^
686 # How to generate the test runner
687 runner.cpp: SimpleTest.h ComplicatedTest.h
688 cxxtestgen.pl -o $@ --error-printer $^
689 </pre>
690 </pre>
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
698 with Cons.
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
705 projects:
707 <ul>
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.
713 </ul>
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
721 some of the process.
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>
732 file.
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
748 the last test.
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
761 something happens.
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
772 you to enjoy:
774 <ul>
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>
778 <br><p>
779 <li>Using the Win32 GUI on Windows 98:
780 <div align="center"><img src="win32.png" alt="win32.png"></div>
781 <br><p>
782 <li>Using the X11 GUI (with the venerable TWM):
783 <div align="center"><img src="x11.png" alt="x11.png"></div>
784 <br><p>
785 <li>And of course, no GUI is complete without the ability to mess around with
786 its appearance:
787 <div align="center"><img src="qt2.png" alt="qt2.png"></div>
788 <br><p>
789 <p><em>Ahhh.</em> Nothing like a beautiful user interface.
791 </ul>
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">
806 void test_memset()
807 {
808 char *buffer = new char[1024];
809 TS_ASSERT( buffer );
810 memset( buffer, 0, 1024 ); // But what if buffer == 0?
811 }
812 </pre>
813 </pre>
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
853 {
854 public:
855 /*
856 void testCommentedOutStillGetsCalled()
857 {
858 }
859 */
861 #if 0
862 void testMarkedOutStillGetsCalled()
863 {
864 }
865 #endif
866 };
867 </pre>
868 </pre>
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
874 <code>x</code>:
876 <pre class="smallexample">
877 <pre class="verbatim">
878 class MyTest : public CxxTest::TestSuite
879 {
880 public:
881 // void testFutureStuff()
882 // {
883 // }
885 void xtestFutureStuff()
886 {
887 }
888 };
889 </pre>
890 </pre>
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
895 types.
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>)
905 on your data types!
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:
914 <ul>
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>
918 </ul>
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
935 {
936 public:
937 struct Data
938 {
939 char data[3];
940 };
942 void testCompareData()
943 {
944 Data x, y;
945 memset( x.data, 0x12, sizeof(x.data) );
946 memset( y.data, 0xF6, sizeof(y.data) );
947 TS_ASSERT_EQUALS( x, y );
948 }
949 };
950 </pre>
951 </pre>
952 would output
953 <pre class="smallexample">
954 <pre class="verbatim">
955 Running 1 test.
956 TestMyData.h:16: Expected (x == y), found ({ 12 12 12 } != { F6 F6 F6 })
957 Failed 1 of 1 test
958 Success rate: 0%
959 </pre>
960 </pre>
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
968 following example:
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 ) );
978 </pre>
979 </pre>
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">
991 class MyClass
992 {
993 int _value;
995 public:
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; }
1007 };
1009 #ifdef CXXTEST_RUNNING
1010 #include <cxxtest/ValueTraits.h>
1011 #include <stdio.h>
1013 namespace CxxTest
1014 {
1015 CXXTEST_TEMPLATE_INSTANTIATION
1016 class ValueTraits<MyClass>
1017 {
1018 char _s[256];
1020 public:
1021 ValueTraits( const MyClass &m ) { sprintf( _s, "MyClass( %i )", m.value() ); }
1022 const char *asString() const { return _s; }
1023 };
1024 };
1025 #endif // CXXTEST_RUNNING
1026 </pre>
1027 </pre>
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.
1034 Here is an example:
1036 <pre class="smallexample">
1037 <pre class="verbatim">
1038 template<class T>
1039 class TMyClass
1040 {
1041 T _value;
1043 public:
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; }
1052 };
1054 #ifdef CXXTEST_RUNNING
1055 #include <cxxtest/ValueTraits.h>
1056 #include <typeinfo>
1057 #include <sstream>
1059 namespace CxxTest
1060 {
1061 template<class T>
1062 class ValueTraits< TMyClass<T> >
1063 {
1064 std::ostringstream _s;
1066 public:
1067 ValueTraits( const TMyClass<T> &t )
1068 { _s << typeid(t).name() << "( " << t.value() << " )"; }
1069 const char *asString() const { return _s.str().c_str(); }
1070 };
1071 };
1072 #endif // CXXTEST_RUNNING
1073 </pre>
1074 </pre>
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>
1099 archive.
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:
1138 <ul>
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.
1160 </ul>
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>.
1166 <ul>
1168 <li>Prepare a header file to be used by both the real and test code.
1169 <pre class="smallexample">
1170 <pre class="verbatim">
1171 // T/time.h
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 */ );
1179 </pre>
1180 </pre>
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">
1186 // code.cpp
1187 #include <T/time.h>
1189 int generateRandomNumber()
1190 {
1191 return T::time( NULL ) * 3;
1192 }
1193 </pre>
1194 </pre>
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">
1201 // real_time.cpp
1202 #define CXXTEST_MOCK_REAL_SOURCE_FILE
1203 #include <T/time.h>
1204 </pre>
1205 </pre>
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
1209 one:
1210 <pre class="smallexample">
1211 <pre class="verbatim">
1212 // mock_time.cpp
1213 #define CXXTEST_MOCK_TEST_SOURCE_FILE
1214 #include <T/time.h>
1215 </pre>
1216 </pre>
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">
1222 // TestRandom.h
1223 #include <cxxtest/TestSuite.h>
1224 #include <T/time.h>
1226 class TheTimeIsOne : public T::Base_time
1227 {
1228 public:
1229 time_t time( time_t * ) { return 1; }
1230 };
1232 class TestRandom : public CxxTest::TestSuite
1233 {
1234 public:
1235 void test_Random()
1236 {
1237 TheTimeIsOne t;
1238 TS_ASSERT_EQUALS( generateRandomNumber(), 3 );
1239 }
1240 };
1241 </pre>
1242 </pre>
1244 </ul>
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
1269 function.
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 */
1286 PIRP Irp ),
1287 ( Device, Irp ) /* How to call */ );
1288 </pre>
1289 </pre>
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 */ );
1322 </pre>
1323 </pre>
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 */ );
1336 </pre>
1337 </pre>
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:
1459 <dl>
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.
1474 </dl>
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:
1485 <dl>
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.
1495 </dl>
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
1543 this.
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
1611 values.
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
1626 no limit.
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>
1660 <ul>
1661 <li><strong>Version 3.10.0 (2004-11-20)</strong>
1662 <ul>
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
1670 </ul>
1671 <li><strong>Version 3.9.1 (2004-01-19)</strong>
1672 <ul>
1673 <li>Fixed small bug with runner exit code
1674 <li>Embedded test suites are now deprecated
1675 </ul>
1676 <li><strong>Version 3.9.0 (2004-01-17)</strong>
1677 <ul>
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>
1681 </ul>
1682 <li><strong>Version 3.8.5 (2004-01-08)</strong>
1683 <ul>
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
1688 </ul>
1689 <li><strong>Version 3.8.4 (2003-12-31)</strong>
1690 <ul>
1691 <li>Split distribution into cxxtest and cxxtest-selftest
1692 <li>Added <code>sample/msvc/FixFiles.bat</code>
1693 </ul>
1694 <li><strong>Version 3.8.3 (2003-12-24)</strong>
1695 <ul>
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
1701 </ul>
1702 <li><strong>Version 3.8.1 (2003-12-21)</strong>
1703 <ul>
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.
1709 </ul>
1710 <li><strong>Version 3.8.0 (2003-12-13)</strong>
1711 <ul>
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
1718 </ul>
1719 <li><strong>Version 3.7.1 (2003-09-29)</strong>
1720 <ul>
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)
1725 </ul>
1726 <li><strong>Version 3.7.0 (2003-09-20)</strong>
1727 <ul>
1728 <li>Added <code>TS_ASSERT_LESS_THAN_EQUALS</code>
1729 <li>Minor cleanups
1730 </ul>
1731 <li><strong>Version 3.6.1 (2003-09-15)</strong>
1732 <ul>
1733 <li>Improved QT GUI
1734 <li>Improved portability some more
1735 </ul>
1736 <li><strong>Version 3.6.0 (2003-09-04)</strong>
1737 <ul>
1738 <li>Added <code>--longlong</code>
1739 <li>Some portability improvements
1740 </ul>
1741 <li><strong>Version 3.5.1 (2003-09-03)</strong>
1742 <ul>
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
1750 </ul>
1751 <li><strong>Version 3.1.1 (2003-08-27)</strong>
1752 <ul>
1753 <li>Fixed small bug in <code>TS_ASSERT_THROWS_*()</code>
1754 </ul>
1755 <li><strong>Version 3.1.0 (2003-08-23)</strong>
1756 <ul>
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
1761 </ul>
1762 <li><strong>Version 3.0.1 (2003-08-07)</strong>
1763 <ul>
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
1770 </ul>
1771 <li><strong>Version 2.8.4 (2003-07-21)</strong>
1772 <ul>
1773 <li>Now supports g++-3.3
1774 <li>Added <code>--have-eh</code>
1775 <li>Fixed bug in <code>numberToString()</code>
1776 </ul>
1777 <li><strong>Version 2.8.3 (2003-06-30)</strong>
1778 <ul>
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!
1782 </ul>
1783 <li><strong>Version 2.8.2 (2003-06-10)</strong>
1784 <ul>
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>
1788 </ul>
1789 <li><strong>Version 2.8.1 (2003-01-16)</strong>
1790 <ul>
1791 <li>Fixed <code>charToString()</code> for negative chars
1792 </ul>
1793 <li><strong>Version 2.8.0 (2003-01-13)</strong>
1794 <ul>
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
1800 </ul>
1801 <li><strong>Version 2.7.0 (2002-09-29)</strong>
1802 <ul>
1803 <li>Added embedded test suites
1804 <li>Major internal improvements
1805 </ul>
1807 </ul>
1809 <p><a name="contents"></a>
1811 <div class="contents">
1812 <h2>Table of Contents</h2>
1813 <ul>
1814 <li><a name="toc_TOC0" href="#TOC0">1 Introduction</a>
1815 <ul>
1816 <li><a href="#TOC1">1.1 About this guide</a>
1817 </li></ul>
1818 <li><a name="toc_TOC2" href="#TOC2">2 Getting started</a>
1819 <ul>
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>
1824 </li></ul>
1825 <li><a name="toc_TOC7" href="#TOC7">3 <em>Really</em> using CxxTest</a>
1826 <ul>
1827 <li><a href="#TOC8">3.1 What can you test</a>
1828 <ul>
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>
1843 <ul>
1844 <li><a href="#TOC23">3.1.14.1 The <code>ETSM_</code> macros</a>
1845 </li></ul>
1846 </li></ul>
1847 <li><a href="#TOC24">3.2 Running the samples</a>
1848 <li><a href="#TOC25">3.3 Test fixtures</a>
1849 <ul>
1850 <li><a href="#TOC26">3.3.1 Test suite level fixtures</a>
1851 </li></ul>
1852 <li><a href="#TOC27">3.4 Integrating with your build environment</a>
1853 <ul>
1854 <li><a href="#TOC28">3.4.1 Overview</a>
1855 <li><a href="#TOC29">3.4.2 Actually doing it</a>
1856 <ul>
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>
1861 </li></ul>
1862 </li></ul>
1863 <li><a href="#TOC34">3.5 Graphical user interface</a>
1864 <ul>
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>
1868 </li></ul>
1869 </li></ul>
1870 <li><a name="toc_TOC38" href="#TOC38">4 Advanced topics</a>
1871 <ul>
1872 <li><a href="#TOC39">4.1 Aborting tests after failures</a>
1873 <ul>
1874 <li><a href="#TOC40">4.1.1 Controlling this behavior at runtime</a>
1875 </li></ul>
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>
1878 <ul>
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>
1884 <ul>
1885 <li><a href="#TOC48">4.3.5.1 Defining value traits for template classes</a>
1886 </li></ul>
1887 <li><a href="#TOC49">4.3.6 Overriding the default value traits</a>
1888 </li></ul>
1889 <li><a href="#TOC50">4.4 Global Fixtures</a>
1890 <ul>
1891 <li><a href="#TOC51">4.4.1 World fixtures</a>
1892 </li></ul>
1893 <li><a href="#TOC52">4.5 Mock Objects</a>
1894 <ul>
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>
1897 <ul>
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>
1904 </li></ul>
1905 </li></ul>
1906 <li><a href="#TOC61">4.6 Test Listeners and Test Runners</a>
1907 <ul>
1908 <li><a href="#TOC62">4.6.1 Other test listeners</a>
1909 <ul>
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>
1913 </li></ul>
1914 </li></ul>
1915 <li><a href="#TOC66">4.7 Dynamically creating test suites</a>
1916 <li><a href="#TOC67">4.8 Static initialization</a>
1917 </li></ul>
1918 <li><a name="toc_TOC68" href="#TOC68">Appendix A Command line options</a>
1919 <ul>
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>
1936 </li></ul>
1937 <li><a name="toc_TOC85" href="#TOC85">Appendix B Controlling the behavior of CxxTest</a>
1938 <ul>
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>
1948 </li></ul>
1949 <li><a name="toc_TOC95" href="#TOC95">Appendix C Runtime options</a>
1950 <ul>
1951 <li><a href="#TOC96">C.1 <code>setAbortTestOnFail( bool )</code></a>
1952 <li><a href="#TOC97">C.2 <code>setMaxDumpSize( unsigned )</code></a>
1953 </li></ul>
1954 <li><a name="toc_TOC98" href="#TOC98">Appendix D Version history</a>
1955 </li></ul>
1956 </div>
1959 </body></html>