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 6this note explains how to do it while the second one explains how to write the 7test. 8 9I. CppUnit Installation 10----------------------- 11 121. Get it from http://www.sourceforge.net/projects/cppunit 13 (latest version as of the time of this writing is 1.8.0) 14 152. 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 25II. Writing tests with CppUnit 26------------------------------ 27 281. Create a new directory tests/foo 29 302. 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 463. add a '<sources>' tag for your source file to tests/test.bkl 47 48 49III. Running the tests 50---------------------- 51 521. 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 572. Build the test program using one of the make/project files in the tests 58 subdirectory. 59 603. 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 654. 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 725. 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 92IV. Notes 93--------- 94 951. 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 982. 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 1023. 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 1144. 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 122Author: VZ & MW 123Version: $Id: tn0017.txt 33984 2005-05-08 16:16:34Z MW $ 124