docs/tech/tn0017.txt

   1                     How to write unit tests for wxWidgets
   2                     =====================================
   3
   4  Unit tests for wxWidgets are written using small cppunit framework. To compile
   5 (but not to run) them you need to have it installed. Hence the first part of
   6 this note explains how to do it while the second one explains how to write the
   7 test.
   8
   9 I. CppUnit Installation
  10 -----------------------
  11
  12 1. Get it from http://www.sourceforge.net/projects/cppunit
  13    (latest version as of the time of this writing is 1.8.0)
  14
  15 2. Build the library:
  16  a) Under Windows using VC++ (both versions 6 and 7 work):
  17     - build everything in CppUnitLibraries.dsw work space
  18     - add include and lib subdirectories of the directory
  19       where you installed cppunit to the compiler search path
  20       using "Tools|Options" menu in VC IDEA
  21
  22  b) Under Unix: run configure && make && make install as usual
  23
  24
  25 II. Writing tests with CppUnit
  26 ------------------------------
  27
  28 1. Create a new directory tests/foo
  29
  30 2. Write a cpp file for the test copying, if you want,
  31    from one of the existing tests. The things to look for:
  32  a) #include "wx/cppunit.h" instead of directly including CppUnit headers
  33  b) don't put too many things in one test case nor in one method of a test
  34     case as it makes understanding what exactly failed harder later
  35  c) 'register' your tests as follows so that the test program will find and
  36     execute them:
  37
  38     // register in the unnamed registry so that these tests are run by default
  39     CPPUNIT_TEST_SUITE_REGISTRATION(MBConvTestCase);
  40
  41     // also include in it's own registry so that these tests can be run alone
  42     CPPUNIT_TEST_SUITE_NAMED_REGISTRATION(MBConvTestCase, "MBConvTestCase");
  43
  44    Read CppUnit documentation for more.
  45
  46 3. add a '<sources>' tag for your source file to tests/test.bkl
  47
  48
  49 III. Running the tests
  50 ----------------------
  51
  52 1. Regenerate the make/project files from test.bkl using bakefile_gen, e.g.:
  53         cd build/bakefiles
  54         bakefile_gen -b ../../tests/test.bkl
  55    and if you're on a unix system re-run configure.
  56
  57 2. Build the test program using one of the make/project files in the tests
  58    subdirectory.
  59
  60 3. Run the test program with no arguments to run the default set of tests
  61    (which are all those registered with CPPUNIT_TEST_SUITE_REGISTRATION).
  62    Or to list the test suites without running them:
  63       test -l
  64
  65 4. Tests that have been registered under a name using
  66    CPPUNIT_TEST_SUITE_NAMED_REGISTRATION can also be run separately. For
  67    example:
  68       test MBConvTestCase
  69    or to list the tests:
  70       test -L MBConvTestCase
  71
  72 5. Fault navigation.
  73    VC++ users can run the programs as a post build step (Projects/Settings/
  74    Post-build step) to see the test results in an IDE window. This allows
  75    errors to be jumped to in the same way as for compiler errors, for
  76    example by pressing F4 or highlighting the error and pressing return.
  77
  78    Similarly for makefile users: makefiles can be modified to execute the
  79    test programs as a final step. Then you can navigate to any errors in the
  80    same way as for compiler errors, if your editor supports that.
  81
  82    Another alternative is to run the tests manually, redirecting the output
  83    to a file. Then use your editor to jump to any failures. Using Vim, for
  84    example, ':cf test.log' would take you to the first error in test.log, and
  85    ':cn' to the next.
  86
  87    If you would like to set a breakpoint on a failing test using a debugger,
  88    put the breakpoint on the function 'CppUnit::Asserter::fail()'. This will
  89    stop on each failing test.
  90
  91
  92 IV. Notes
  93 ---------
  94
  95 1. You can register your tests (or a subset of them) just under a name, and not
  96    in the unnamed registry if you don't want them to be executed by default.
  97
  98 2. If you are going to register your tests both in the unnamed registry
  99    and under a name, then use the name that the tests have in the 'test -l'
 100    listing.
 101
 102 3. Tests which fail can be temporarily registered under "fixme" while the
 103    problems they expose are fixed, instead of the unnamed registry. That
 104    way they can easily be run, but they do not make regression testing with
 105    the default suite more difficult. E.g.:
 106
 107     // register in the unnamed registry so that these tests are run by default
 108     //CPPUNIT_TEST_SUITE_REGISTRATION(wxRegExTestCase);
 109     CPPUNIT_TEST_SUITE_NAMED_REGISTRATION(wxRegExTestCase, "fixme");
 110
 111     // also include in it's own registry so that these tests can be run alone
 112     CPPUNIT_TEST_SUITE_NAMED_REGISTRATION(wxRegExTestCase, "wxRegExTestCase");
 113
 114 4. Tests which take a long time to execute can be registered under "advanced"
 115    instead of the unnamed registry. The default suite should execute reasonably
 116    quickly. To run the default and advanced tests together:
 117     test "" advanced
 118
 119
 120 === EOF ===
 121
 122 Author:  VZ & MW
 123 Version: $Id$