cxxtest/docs/guide.html

   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>
  12
  13 <h2 class="chapter"><a name="TOC0"></a>1 Introduction</h2>
  14
  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++.
  16
  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.
  29
  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>).
  34
  35    <p>CxxTest is available under the
  36 <a href="http://www.gnu.org/copyleft/lesser.html">GNU Lesser General Public License</a>.
  37
  38 <h3 class="section"><a name="TOC1"></a>1.1 About this guide</h3>
  39
  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.
  42
  43 <h2 class="chapter"><a name="TOC2"></a>2 Getting started</h2>
  44
  45 <h3 class="section"><a name="TOC3"></a>2.1 Getting CxxTest</h3>
  46
  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>.
  54
  55 <h3 class="section"><a name="TOC4"></a>2.2 Your first test!</h3>
  56
  57    <p>Here's a simple step-by-step guide:
  58
  59      <ol type=1 start=1>
  60
  61      <li>Tests are organized into "Test Suites".
  62   Test suites are written in header files.
  63
  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>.
  67
  68      <pre class="smallexample">
  69           <pre class="verbatim">
  70           // MyTestSuite.h
  71           #include &lt;cxxtest/TestSuite.h>
  72
  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>
  84
  85      </p><li>After you have your test suites, you use CxxTest to generate a "test runner" source file:
  86
  87      <pre class="verbatim">
  88      # cxxtestgen.pl --error-printer -o runner.cpp MyTestSuite.h
  89      </pre>
  90
  91      <p>or, for those less fortunate:
  92
  93      <pre class="verbatim">
  94      C:\tmp> perl -w cxxtestgen.pl --error-printer -o runner.cpp MyTestSuite.h
  95      </pre>
  96
  97      </p><li>You would then simply compile the resulting file:
  98
  99      <pre class="verbatim">
 100      # g++ -o runner runner.cpp
 101      </pre>
 102
 103      <p>or perhaps
 104
 105      <pre class="verbatim">
 106      C:\tmp> cl -GX -o runner.exe runner.cpp
 107      </pre>
 108
 109      <p>or maybe even
 110
 111      <pre class="verbatim">
 112      C:\tmp> bcc32 -erunner.exe runner.cpp
 113      </pre>
 114
 115      </p><li>Finally, you run the tests and enjoy a well tested piece of software:
 116
 117      <pre class="verbatim">
 118      # ./runner
 119      Running 1 test.OK!
 120      </pre>
 121
 122         </ol>
 123
 124 <h3 class="section"><a name="TOC5"></a>2.3 Your second test</h3>
 125
 126    <p>Now let's see what failed tests look like.
 127 We will add a failing test to the previous example:
 128
 129 <pre class="smallexample">
 130      <pre class="verbatim">
 131      // MyTestSuite.h
 132      #include &lt;cxxtest/TestSuite.h>
 133
 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         }
 142
 143         void testMultiplication( void )
 144         {
 145            TS_ASSERT_EQUALS( 2 * 2, 5 );
 146         }
 147      };
 148      </pre>
 149      </pre>
 150
 151    <p>Generate, compile and run the test runner, and you will get this:
 152
 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>
 162
 163    <p>Fixing the bug is left as an excercise to the reader.
 164
 165 <h3 class="section"><a name="TOC6"></a>2.4 Graphical user interface</h3>
 166
 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>
 171
 172      <li>Under Windows with Visual C++, run <code>perl cxxtestgen.pl -o&nbsp;runner.cpp
 173 </code><em>--gui=Win32Gui</em><code> MyTestSuite.h</code>.
 174
 175      <li>Under X-Windows, try <code>./cxxtestgen.pl -o&nbsp;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&nbsp;runner
 178 -L/usr/X11R6/lib runner.cpp -lX11</code>.
 179
 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.
 183
 184    </ul>
 185
 186    <p>See <a href="#GUI">Graphical user interface</a> and <a href="#samples">Running the samples</a> for
 187 more information.
 188
 189 <h2 class="chapter"><a name="TOC7"></a>3 <em>Really</em> using CxxTest</h2>
 190
 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.
 194
 195 <h3 class="section"><a name="TOC8"></a>3.1 What can you test</h3>
 196
 197    <p>Here are the different "assertions" you can use in your tests:
 198
 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>
 200
 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>
 204
 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>
 208
 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>
 212
 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>
 216
 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>
 220
 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>
 224
 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&lt;y)</em><code></code>
 227 </td><td valign="top"><code>TS_ASSERT_LESS_THAN(ship.speed(), SPEED_OF_LIGHT);</code>
 228
 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&lt;=y)</em><code></code>
 231 </td><td valign="top"><code>TS_ASSERT_LESS_THAN_EQUALS(requests, items);</code>
 232
 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>
 236
 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>
 240
 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>
 244
 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)
 248
 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)
 252
 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>
 256
 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>
 260
 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>
 264
 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>
 268
 269    <br></td></tr></table>
 270
 271 <h4 class="subsection"><a name="TOC9"></a>3.1.1 <code>TS_FAIL</code></h4>
 272
 273    <p><a name="fail"></a>
 274
 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:
 278
 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>
 287
 288 <h4 class="subsection"><a name="TOC10"></a>3.1.2 <code>TS_ASSERT</code></h4>
 289
 290    <p><a name="assert"></a>
 291
 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:
 295
 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>
 305
 306 <h4 class="subsection"><a name="TOC11"></a>3.1.3 <code>TS_ASSERT_EQUALS</code></h4>
 307
 308    <p><a name="equals"></a>
 309
 310    <p>This is the second most useful tester.
 311 As the name hints, it is used to test if two values are equal.
 312
 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>
 321
 322 <h4 class="subsection"><a name="TOC12"></a>3.1.4 <code>TS_ASSERT_SAME_DATA</code></h4>
 323
 324    <p><a name="sameData"></a>
 325
 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.
 331
 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>
 342
 343 <h4 class="subsection"><a name="TOC13"></a>3.1.5 <code>TS_ASSERT_DELTA</code></h4>
 344
 345    <p><a name="delta"></a>
 346
 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.
 350
 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>
 359
 360 <h4 class="subsection"><a name="TOC14"></a>3.1.6 <code>TS_ASSERT_DIFFERS</code></h4>
 361
 362    <p><a name="differs"></a>
 363
 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.
 366
 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>
 377
 378 <h4 class="subsection"><a name="TOC15"></a>3.1.7 <code>TS_ASSERT_LESS_THAN</code></h4>
 379
 380    <p><a name="lessthan"></a>
 381
 382    <p>This macro asserts that the first operand is less than the second.
 383
 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>
 392
 393 <h4 class="subsection"><a name="TOC16"></a>3.1.8 <code>TS_ASSERT_LESS_THAN_EQUALS</code></h4>
 394
 395    <p><a name="lte"></a>
 396
 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.
 399
 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>
 408
 409 <h4 class="subsection"><a name="TOC17"></a>3.1.9 <code>TS_ASSERT_PREDICATE</code></h4>
 410
 411    <p><a name="predicate"></a>
 412
 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.
 419
 420 <pre class="smallexample">
 421      <pre class="verbatim">
 422      class IsPrime
 423      {
 424      public:
 425         bool operator()( unsigned ) const;
 426      };
 427
 428      // ...
 429
 430      void testPrimeGenerator( void )
 431      {
 432         TS_ASSERT_PREDICATE( IsPrime, generatePrime() );
 433      }
 434      </pre>
 435      </pre>
 436
 437 <h4 class="subsection"><a name="TOC18"></a>3.1.10 <code>TS_ASSERT_RELATION</code></h4>
 438
 439    <p><a name="relation"></a>
 440
 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.
 451
 452 <pre class="smallexample">
 453      <pre class="verbatim">
 454      void testGreater( void )
 455      {
 456         TS_ASSERT_RELATION( std::greater&lt;int>, ticketsSold(), 1000 );
 457      }
 458      </pre>
 459      </pre>
 460
 461 <h4 class="subsection"><a name="TOC19"></a>3.1.11 <code>TS_ASSERT_THROWS</code> and friends</h4>
 462
 463    <p><a name="throwsx"></a>
 464
 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.
 470
 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.
 479
 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() );
 487
 488         TS_ASSERT_THROWS_EQUALS( validate(), const std::exception &amp;e,
 489                                  e.what(), "Invalid value" );
 490         TS_ASSERT_THROWS_ASSERT( validate(), const Error &amp;e,
 491                                  TS_ASSERT_DIFFERS( e.code(), SUCCESS ) );
 492      }
 493      </pre>
 494      </pre>
 495
 496 <h4 class="subsection"><a name="TOC20"></a>3.1.12 <code>TS_TRACE</code> and <code>TS_WARN</code></h4>
 497
 498    <p><a name="warn"></a>
 499 <a name="trace"></a>
 500
 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:
 505
 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>
 515
 516    <p>In the GUI, <code>TS_WARN</code> sets the bar color to yellow (unless it was
 517 already red).
 518
 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.
 522
 523 <h4 class="subsection"><a name="TOC21"></a>3.1.13 The <code>ETS_</code> macros</h4>
 524
 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.
 529
 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 );
 536
 537         // More elaborate way:
 538         try { ETS_ASSERT_EQUALS( foo(2), 4 ); }
 539         catch( const BadFoo &amp;e ) { TS_FAIL( e.bar() ); }
 540      }
 541      </pre>
 542      </pre>
 543
 544 <h4 class="subsection"><a name="TOC22"></a>3.1.14 The <code>TSM_</code> macros</h4>
 545
 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.
 549
 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:
 552
 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         }
 564
 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>
 573
 574 <h5 class="subsubsection"><a name="TOC23"></a>3.1.14.1 The <code>ETSM_</code> macros</h5>
 575
 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.
 578
 579 <h3 class="section"><a name="TOC24"></a>3.2 Running the samples</h3>
 580
 581    <p><a name="samples"></a>
 582
 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.
 589
 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.
 594
 595 <h3 class="section"><a name="TOC25"></a>3.3 Test fixtures</h3>
 596
 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.
 602
 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.
 608
 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"); }
 616
 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>
 626
 627    <p><strong>Note new users:</strong> This is probably the single most important
 628 feature to use when your tests become non-trivial.
 629
 630 <h4 class="subsection"><a name="TOC26"></a>3.3.1 Test suite level fixtures</h4>
 631
 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.
 636
 637 <h3 class="section"><a name="TOC27"></a>3.4 Integrating with your build environment</h3>
 638
 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!
 642
 643 <h4 class="subsection"><a name="TOC28"></a>3.4.1 Overview</h4>
 644
 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>
 656
 657 <h4 class="subsection"><a name="TOC29"></a>3.4.2 Actually doing it</h4>
 658
 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.
 661
 662    <p>I will try to outline the usage for some cases.
 663
 664 <h5 class="subsubsection"><a name="TOC30"></a>3.4.2.1 Using Makefiles</h5>
 665
 666    <p>Generating the tests with a makefile is pretty straightforward.
 667 Simply add rules to generate, compile and run the test runner.
 668
 669 <pre class="smallexample">
 670      <pre class="verbatim">
 671      all: lib run_tests app
 672
 673      # Rules to build your targets
 674      lib: ...
 675
 676      app: ...
 677
 678      # A rule that runs the unit tests
 679      run_tests: runner
 680              ./runner
 681
 682      # How to build the test runner
 683      runner: runner.cpp lib
 684              g++ -o $@ $^
 685
 686      # How to generate the test runner
 687      runner.cpp: SimpleTest.h ComplicatedTest.h
 688               cxxtestgen.pl -o $@ --error-printer $^
 689      </pre>
 690      </pre>
 691
 692 <h5 class="subsubsection"><a name="TOC31"></a>3.4.2.2 Using Cons</h5>
 693
 694    <a href="http://dsmit.com/cons/">Cons</a> is a powerful and
 695 versatile make replacement which uses Perl scripts instead of Makefiles.
 696
 697    <p>See <code>sample/Construct</code> in the CxxTest distribution for an example of building CxxTest test runners
 698 with Cons.
 699
 700 <h5 class="subsubsection"><a name="TOC32"></a>3.4.2.3 Using Microsoft Visual Studio</h5>
 701
 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:
 706
 707      <ul>
 708 <li>The project <code>CxxTest_3_Generate</code> runs <code>cxxtestgen</code>.
 709
 710      <li>The project <code>CxxTest_2_Build</code> compiles the generated file.
 711
 712      <li>The project <code>CxxTest_1_Run</code> runs the tests.
 713 </ul>
 714
 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.
 722
 723 <h5 class="subsubsection"><a name="TOC33"></a>3.4.2.4 Using Microsoft Windows DDK</h5>
 724
 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.
 728
 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.
 733
 734    <p>You can see an example of how to do this in the CxxTest distribution
 735 under <code>sample/winddk</code>.
 736
 737 <h3 class="section"><a name="TOC34"></a>3.5 Graphical user interface</h3>
 738
 739    <p><a name="GUI"></a>
 740
 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.
 749
 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>.
 754
 755 <h4 class="subsection"><a name="TOC35"></a>3.5.1 Starting the GUI minimized</h4>
 756
 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.
 762
 763 <h4 class="subsection"><a name="TOC36"></a>3.5.2 Leaving the GUI open</h4>
 764
 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.
 768
 769 <h4 class="subsection"><a name="TOC37"></a>3.5.3 Screenshots!</h4>
 770
 771    <p>As with any self-respecting GUI application, here are some screenshots for
 772 you to enjoy:
 773
 774      <ul>
 775
 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.
 790
 791    </ul>
 792
 793 <h2 class="chapter"><a name="TOC38"></a>4 Advanced topics</h2>
 794
 795    <p>Topics in this section are more technical, and you probably won't find them
 796 interesting unless you need them.
 797
 798 <h3 class="section"><a name="TOC39"></a>4.1 Aborting tests after failures</h3>
 799
 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:
 803
 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>
 814
 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.
 824
 825 <h4 class="subsection"><a name="TOC40"></a>4.1.1 Controlling this behavior at runtime</h4>
 826
 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.
 835
 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>.
 840
 841 <h3 class="section"><a name="TOC41"></a>4.2 Commenting out tests</h3>
 842
 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.
 845
 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:
 849
 850 <pre class="smallexample">
 851      <pre class="verbatim">
 852      class MyTest : public CxxTest::TestSuite
 853      {
 854      public:
 855      /*
 856         void testCommentedOutStillGetsCalled()
 857         {
 858         }
 859      */
 860
 861      #if 0
 862         void testMarkedOutStillGetsCalled()
 863         {
 864         }
 865      #endif
 866      };
 867      </pre>
 868      </pre>
 869
 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>:
 875
 876 <pre class="smallexample">
 877      <pre class="verbatim">
 878      class MyTest : public CxxTest::TestSuite
 879      {
 880      public:
 881      // void testFutureStuff()
 882      // {
 883      // }
 884
 885         void xtestFutureStuff()
 886         {
 887         }
 888      };
 889      </pre>
 890      </pre>
 891
 892 <h3 class="section"><a name="TOC42"></a>4.3 Comparing equality for your own types</h3>
 893
 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.
 898
 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.
 901
 902 <h4 class="subsection"><a name="TOC43"></a>4.3.1 The equality operator</h4>
 903
 904    <p>First of all, don't forget to implement the equality operator (<code>operator==()</code>)
 905 on your data types!
 906
 907 <h4 class="subsection"><a name="TOC44"></a>4.3.2 Value traits</h4>
 908
 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.
 912
 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&lt;int&gt; converter(i);</code>
 917 <li><code>string = converter.asString();</code>
 918 </ul>
 919
 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.
 923
 924 <h4 class="subsection"><a name="TOC45"></a>4.3.3 Unknown types</h4>
 925
 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.
 928
 929    <p>For example, the following code
 930 <pre class="smallexample">
 931      <pre class="verbatim">
 932      #include &lt;cxxtest/TestSuite.h>
 933
 934      class TestMyData : public CxxTest::TestSuite
 935      {
 936      public:
 937         struct Data
 938         {
 939            char data[3];
 940         };
 941
 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>
 961
 962 <h4 class="subsection"><a name="TOC46"></a>4.3.4 Enumeration traits</h4>
 963
 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:
 969
 970 <pre class="smallexample">
 971      <pre class="verbatim">
 972      enum Status { STATUS_IDLE, STATUS_BUSY, STATUS_ERROR };
 973
 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>
 980
 981    <p>See <code>sample/EnumTraits.h</code> for a working sample.
 982
 983 <h4 class="subsection"><a name="TOC47"></a>4.3.5 Defining new value traits</h4>
 984
 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:
 988
 989 <pre class="smallexample">
 990      <pre class="verbatim">
 991      class MyClass
 992      {
 993         int _value;
 994
 995      public:
 996         MyClass( int value ) : _value( value ) {}
 997         int value() const { return _value; }
 998
 999         // CxxTest requires a copy constructor
1000         MyClass( const MyClass &amp;other ) : _value( other._value ) {}
1001
1002         // If you want to use TS_ASSERT_EQUALS
1003         bool operator== ( const MyClass &amp;other ) const { return _value == other._value; }
1004
1005         // If you want to use TS_ASSERT_LESS_THAN
1006         bool operator== ( const MyClass &amp;other ) const { return _value &lt; other._value; }
1007      };
1008
1009      #ifdef CXXTEST_RUNNING
1010      #include &lt;cxxtest/ValueTraits.h>
1011      #include &lt;stdio.h>
1012
1013      namespace CxxTest
1014      {
1015         CXXTEST_TEMPLATE_INSTANTIATION
1016         class ValueTraits&lt;MyClass>
1017         {
1018            char _s[256];
1019
1020         public:
1021            ValueTraits( const MyClass &amp;m ) { sprintf( _s, "MyClass( %i )", m.value() ); }
1022            const char *asString() const { return _s; }
1023         };
1024      };
1025      #endif // CXXTEST_RUNNING
1026      </pre>
1027      </pre>
1028
1029 <h5 class="subsubsection"><a name="TOC48"></a>4.3.5.1 Defining value traits for template classes</h5>
1030
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:
1035
1036 <pre class="smallexample">
1037      <pre class="verbatim">
1038      template&lt;class T>
1039      class TMyClass
1040      {
1041         T _value;
1042
1043      public:
1044         TMyClass( const T &amp;value ) : _value( value );
1045         const T &amp;value() const { return _value; }
1046
1047         // CxxTest requires a copy constructor
1048         TMyClass( const TMyClass&lt;T> &amp;other ) : _value( other._value ) {}
1049
1050         // If you want to use TS_ASSERT_EQUALS
1051         bool operator== ( const TMyClass&lt;T> &amp;other ) const { return _value == other._value; }
1052      };
1053
1054      #ifdef CXXTEST_RUNNING
1055      #include &lt;cxxtest/ValueTraits.h>
1056      #include &lt;typeinfo>
1057      #include &lt;sstream>
1058
1059      namespace CxxTest
1060      {
1061         template&lt;class T>
1062         class ValueTraits&lt; TMyClass&lt;T> >
1063         {
1064            std::ostringstream _s;
1065
1066         public:
1067            ValueTraits( const TMyClass&lt;T> &amp;t )
1068               { _s &lt;&lt; typeid(t).name() &lt;&lt; "( " &lt;&lt; t.value() &lt;&lt; " )"; }
1069            const char *asString() const { return _s.str().c_str(); }
1070         };
1071      };
1072      #endif // CXXTEST_RUNNING
1073      </pre>
1074      </pre>
1075
1076 <h4 class="subsection"><a name="TOC49"></a>4.3.6 Overriding the default value traits</h4>
1077
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.
1083
1084    <p>You can see a sample of this technique in <code>test/UserTraits.tpl</code> in
1085 the <code>cxxtest-selftest</code> archive.
1086
1087 <h3 class="section"><a name="TOC50"></a>4.4 Global Fixtures</h3>
1088
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.
1100
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.
1104
1105 <h4 class="subsection"><a name="TOC51"></a>4.4.1 World fixtures</h4>
1106
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.
1113
1114 <h3 class="section"><a name="TOC52"></a>4.5 Mock Objects</h3>
1115
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.
1124
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.
1134
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>
1139
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).
1143
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.
1149
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>.
1152
1153      <li>You link the test binary with a source file that implements
1154 <code>T::fopen()</code> by calling a mock object.
1155
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.
1159
1160    </ul>
1161
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>.
1165
1166      <ul>
1167
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 &lt;time.h>
1173           #include &lt;cxxtest/Mock.h>
1174
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>
1181
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 &lt;T/time.h>
1188
1189           int generateRandomNumber()
1190           {
1191               return T::time( NULL ) * 3;
1192           }
1193           </pre>
1194           </pre>
1195
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 &lt;T/time.h>
1204           </pre>
1205           </pre>
1206
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 &lt;T/time.h>
1215           </pre>
1216           </pre>
1217
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 &lt;cxxtest/TestSuite.h>
1224           #include &lt;T/time.h>
1225
1226           class TheTimeIsOne : public T::Base_time
1227           {
1228           public:
1229               time_t time( time_t * ) { return 1; }
1230           };
1231
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>
1243
1244    </ul>
1245
1246 <h4 class="subsection"><a name="TOC53"></a>4.5.1 Actually doing it</h4>
1247
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++.
1253
1254 <h4 class="subsection"><a name="TOC54"></a>4.5.2 Advanced topic with mock functions</h4>
1255
1256 <h5 class="subsubsection"><a name="TOC55"></a>4.5.2.1 Void functions</h5>
1257
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.
1262
1263 <h5 class="subsubsection"><a name="TOC56"></a>4.5.2.2 Calling the real functions while testing</h5>
1264
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.
1270
1271 <h5 class="subsubsection"><a name="TOC57"></a>4.5.2.3 When there is no real function</h5>
1272
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.
1293
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>&lt;ntddk.h&gt;</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>.
1300
1301 <h5 class="subsubsection"><a name="TOC58"></a>4.5.2.4 Functions in namespaces</h5>
1302
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 &amp;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 &amp;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.
1325
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>.
1340
1341 <h5 class="subsubsection"><a name="TOC59"></a>4.5.2.5 Overloaded functions</h5>
1342
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.
1347
1348 <h5 class="subsubsection"><a name="TOC60"></a>4.5.2.6 Changing the mock namespace</h5>
1349
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.
1353
1354 <h3 class="section"><a name="TOC61"></a>4.6 Test Listeners and Test Runners</h3>
1355
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.
1365
1366 <h4 class="subsection"><a name="TOC62"></a>4.6.1 Other test listeners</h4>
1367
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.
1374
1375 <h5 class="subsubsection"><a name="TOC63"></a>4.6.1.1 The <code>stdio</code> printer</h5>
1376
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>.
1381
1382    <p>To use it, invoke <code>cxxtestgen.pl</code> with the <code>--runner=StdioPrinter</code> option.
1383
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>&lt;stdio.h&gt;</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.
1391
1392 <h5 class="subsubsection"><a name="TOC64"></a>4.6.1.2 The Yes/No runner</h5>
1393
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>.
1397
1398 <h5 class="subsubsection"><a name="TOC65"></a>4.6.1.3 Template files</h5>
1399
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>&lt;CxxTest world&gt;</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.
1404
1405    <p>See <code>samples/file_printer.tpl</code> for an example.
1406
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 &lt;cxxtest/*.h&gt;</code> found in the template
1410 file.  If this behvaior is not what you need, use the "command"
1411 <code>&lt;CxxTest preamble&gt;</code>. See <code>test/preamble.tpl</code> in the
1412 <code>cxxtest-selftest</code> archive for an example of this.
1413
1414 <h3 class="section"><a name="TOC66"></a>4.7 Dynamically creating test suites</h3>
1415
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>.
1420
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>.
1424
1425    <p>See <code>sample/CreatedTest.h</code> for a demonstration.
1426
1427 <h3 class="section"><a name="TOC67"></a>4.8 Static initialization</h3>
1428
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.
1434
1435 <h2 class="appendix"><a name="TOC68"></a>Appendix A Command line options</h2>
1436
1437    <p>Here are the different command line options for <code>cxxtestgen</code>:
1438
1439 <h3 class="section"><a name="TOC69"></a>A.1 <code>--version</code></h3>
1440
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.
1443
1444 <h3 class="section"><a name="TOC70"></a>A.2 <code>--output</code></h3>
1445
1446    <p>Specify <code>--output=FILE</code> or <code>-o FILE</code> to determine the output file name.
1447
1448 <h3 class="section"><a name="TOC71"></a>A.3 <code>--error-printer</code></h3>
1449
1450    <p>This option creates a test runner which uses the standard  error printer class.
1451
1452 <h3 class="section"><a name="TOC72"></a>A.4 <code>--runner</code></h3>
1453
1454    <p>Specify <code>--runner=CLASS</code> to generate a test
1455 runner that <code>#include</code>s <code>&lt;cxxtest/CLASS.h&gt;</code> and uses
1456 <code>CxxTest::CLASS</code> as the test runner.
1457
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>.
1462
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.
1466
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>.
1470
1471      <br><dt><code>--runner=YesNoRunner</code>
1472      <dd>This runner doesn't produce any output, merely returns a true/false result.
1473
1474    </dl>
1475
1476 <h3 class="section"><a name="TOC73"></a>A.5 <code>--gui</code></h3>
1477
1478    <p>Specify <code>--gui=CLASS</code> to generate a test runner that
1479 <code>#include</code>s <code>&lt;cxxtest/CLASS.h&gt;</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.
1483
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.
1489
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.
1492
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>
1496
1497 <h3 class="section"><a name="TOC74"></a>A.6 <code>--include</code></h3>
1498
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.
1504
1505    <p><strong>Note:</strong> If you want the runner to <code>#inculde &lt;FILE&gt;</code>, specify
1506 it on the command line, e.g. <code>--include=&lt;FILE&gt;</code>.  You will most
1507 likely need to use shell escapes, e.g. <code>"--include=&lt;FILE&gt;"</code> or
1508 <code>--include=\&lt;FILE\&gt;</code>.
1509
1510    <p>Examples: <code>--include=TestDefs.h</code> or <code>--include=\&lt;GlobalDefs.h\&gt;</code>.
1511
1512 <h3 class="section"><a name="TOC75"></a>A.7 <code>--template</code></h3>
1513
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.
1518
1519 <h3 class="section"><a name="TOC76"></a>A.8 <code>--have-eh</code></h3>
1520
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.
1527
1528 <h3 class="section"><a name="TOC77"></a>A.9 <code>--no-eh</code></h3>
1529
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>.
1533
1534 <h3 class="section"><a name="TOC78"></a>A.10 <code>--have-std</code></h3>
1535
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>.
1540
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.
1544
1545 <h3 class="section"><a name="TOC79"></a>A.11 <code>--no-std</code></h3>
1546
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.
1552
1553 <h3 class="section"><a name="TOC80"></a>A.12 <code>--longlong</code></h3>
1554
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>.
1560
1561 <h3 class="section"><a name="TOC81"></a>A.13 <code>--abort-on-fail</code></h3>
1562
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.
1566
1567 <h3 class="section"><a name="TOC82"></a>A.14 <code>--part</code></h3>
1568
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.
1572
1573 <h3 class="section"><a name="TOC83"></a>A.15 <code>--root</code></h3>
1574
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.
1580
1581 <h3 class="section"><a name="TOC84"></a>A.16 <code>--no-static-init</code></h3>
1582
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.
1586
1587 <h2 class="appendix"><a name="TOC85"></a>Appendix B Controlling the behavior of CxxTest</h2>
1588
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.
1593
1594 <h3 class="section"><a name="TOC86"></a>B.1 <code>CXXTEST_HAVE_STD</code></h3>
1595
1596    <p>This is equivalent to the <code>--have-std</code> option.
1597
1598 <h3 class="section"><a name="TOC87"></a>B.2 <code>CXXTEST_HAVE_EH</code></h3>
1599
1600    <p>This is equivalent to the <code>--have-eh</code> option.
1601
1602 <h3 class="section"><a name="TOC88"></a>B.3 <code>CXXTEST_ABORT_TEST_ON_FAIL</code></h3>
1603
1604    <font size=-2>(v2.8.0)</font>
1605 This is equivalent to the <code>--abort-on-fail</code> option.
1606
1607 <h3 class="section"><a name="TOC89"></a>B.4 <code>CXXTEST_USER_VALUE_TRAITS</code></h3>
1608
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.
1612
1613 <h3 class="section"><a name="TOC90"></a>B.5 <code>CXXTEST_OLD_TEMPLATE_SYNTAX</code></h3>
1614
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.
1617
1618 <h3 class="section"><a name="TOC91"></a>B.6 <code>CXXTEST_OLD_STD</code></h3>
1619
1620    <p>Again, this is used to support pre-<code>std::</code> standard libraries.
1621
1622 <h3 class="section"><a name="TOC92"></a>B.7 <code>CXXTEST_MAX_DUMP_SIZE</code></h3>
1623
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.
1627
1628 <h3 class="section"><a name="TOC93"></a>B.8 <code>CXXTEST_DEFAULT_ABORT</code></h3>
1629
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.
1632
1633 <h3 class="section"><a name="TOC94"></a>B.9 <code>CXXTEST_LONGLONG</code></h3>
1634
1635    <p>This is equivalent to <code>--longlong</code>.
1636
1637 <h2 class="appendix"><a name="TOC95"></a>Appendix C Runtime options</h2>
1638
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.
1644
1645 <h3 class="section"><a name="TOC96"></a>C.1 <code>setAbortTestOnFail( bool )</code></h3>
1646
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.
1651
1652 <h3 class="section"><a name="TOC97"></a>C.2 <code>setMaxDumpSize( unsigned )</code></h3>
1653
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.
1657
1658 <h2 class="appendix"><a name="TOC98"></a>Appendix D Version history</h2>
1659
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>
1806
1807    </ul>
1808
1809    <p><a name="contents"></a>
1810
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>
1957
1958
1959    </body></html>
1960