| [591] | 1 | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> |
|---|
| 2 | <html xmlns="http://www.w3.org/1999/xhtml"> |
|---|
| 3 | <head> |
|---|
| 4 | <meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/> |
|---|
| [614] | 5 | <title>mixpp: Unit testing of BDM</title> |
|---|
| [591] | 6 | <link href="tabs.css" rel="stylesheet" type="text/css"/> |
|---|
| 7 | <link href="doxygen.css" rel="stylesheet" type="text/css"/> |
|---|
| 8 | </head> |
|---|
| 9 | <body> |
|---|
| 10 | <!-- Generated by Doxygen 1.6.1 --> |
|---|
| [590] | 11 | <script type="text/javascript"> |
|---|
| 12 | <!-- |
|---|
| 13 | function changeDisplayState (e){ |
|---|
| 14 | var num=this.id.replace(/[^[0-9]/g,''); |
|---|
| 15 | var button=this.firstChild; |
|---|
| 16 | var sectionDiv=document.getElementById('dynsection'+num); |
|---|
| 17 | if (sectionDiv.style.display=='none'||sectionDiv.style.display==''){ |
|---|
| 18 | sectionDiv.style.display='block'; |
|---|
| 19 | button.src='open.gif'; |
|---|
| 20 | }else{ |
|---|
| 21 | sectionDiv.style.display='none'; |
|---|
| 22 | button.src='closed.gif'; |
|---|
| 23 | } |
|---|
| 24 | } |
|---|
| 25 | function initDynSections(){ |
|---|
| 26 | var divs=document.getElementsByTagName('div'); |
|---|
| 27 | var sectionCounter=1; |
|---|
| 28 | for(var i=0;i<divs.length-1;i++){ |
|---|
| 29 | if(divs[i].className=='dynheader'&&divs[i+1].className=='dynsection'){ |
|---|
| 30 | var header=divs[i]; |
|---|
| 31 | var section=divs[i+1]; |
|---|
| 32 | var button=header.firstChild; |
|---|
| 33 | if (button!='IMG'){ |
|---|
| 34 | divs[i].insertBefore(document.createTextNode(' '),divs[i].firstChild); |
|---|
| 35 | button=document.createElement('img'); |
|---|
| 36 | divs[i].insertBefore(button,divs[i].firstChild); |
|---|
| 37 | } |
|---|
| 38 | header.style.cursor='pointer'; |
|---|
| 39 | header.onclick=changeDisplayState; |
|---|
| 40 | header.id='dynheader'+sectionCounter; |
|---|
| 41 | button.src='closed.gif'; |
|---|
| 42 | section.id='dynsection'+sectionCounter; |
|---|
| 43 | section.style.display='none'; |
|---|
| 44 | section.style.marginLeft='14px'; |
|---|
| 45 | sectionCounter++; |
|---|
| 46 | } |
|---|
| 47 | } |
|---|
| 48 | } |
|---|
| 49 | window.onload = initDynSections; |
|---|
| 50 | --> |
|---|
| 51 | </script> |
|---|
| 52 | <div class="navigation" id="top"> |
|---|
| 53 | <div class="tabs"> |
|---|
| 54 | <ul> |
|---|
| 55 | <li><a href="main.html"><span>Main Page</span></a></li> |
|---|
| 56 | <li class="current"><a href="pages.html"><span>Related Pages</span></a></li> |
|---|
| 57 | <li><a href="annotated.html"><span>Classes</span></a></li> |
|---|
| 58 | <li><a href="files.html"><span>Files</span></a></li> |
|---|
| 59 | </ul> |
|---|
| 60 | </div> |
|---|
| [614] | 61 | <div class="navpath"><a class="el" href="dev_guide2.html">Howto Contribute to BDM - Advanced development</a> |
|---|
| 62 | </div> |
|---|
| [590] | 63 | </div> |
|---|
| 64 | <div class="contents"> |
|---|
| [591] | 65 | |
|---|
| 66 | |
|---|
| [614] | 67 | <h1><a class="anchor" id="unit_testing">Unit testing of BDM </a></h1><p>Unit tests are simple, fast and easy to run tests of small pieces of code (the "units") designed to reassure developers that individual parts of the developped functionality behave as they're meant to. BDM being an object-oriented library, the independent units are classes, tested by calling their individual methods and comparing actual to expected results.</p> |
|---|
| [591] | 68 | <p>Unit tests are especially useful for C++, where the simplest change can introduce (or uncover) a difficult-to-find bug. They also facilitate changing the internal structure of classes without modifying their external behavior - unit tests can be run before and after such a change to make sure the behavior had indeed stayed the same. More ambitiously, tests can be written before implementing new functionality, serving as its machine-checkable specification. Some authorities go so far as to demand that "not a single line of code" be written before having a failing unit test for it first, but BDM unit testing isn't that demanding - it does facilitate the style for developers who prefer it, but most BDM code is tested retroactively, with new tests suggested by various considerations (see below).</p> |
|---|
| 69 | <h2><a class="anchor" id="Setup"> |
|---|
| [590] | 70 | Setup</a></h2> |
|---|
| [591] | 71 | <p>Unit tests of BDM use a 3rd-party unit testing framework, UnitTest++ (from <a href="http://unittest-cpp.sourceforge.net/">http://unittest-cpp.sourceforge.net/</a> ), which is designed specifically for C++, reasonably popular and maintained (for a C++ unit testing framework), works on Unix, Windows and Mac, allows simple test addition and proved to be readily extensible. Sources of UnitTest++ are included in directory library/tests/unittest-cpp, so that they can be built as part of the normal BDM build, without the need for explicit installation and setup, and are lightly modified for specific requirements of BDM.</p> |
|---|
| 72 | <p>Existing unit tests are collected into a testsuite executable (so that they can all easily be run together), whose sources are in library/tests. Apart from the top-level testsuite.cpp, testsuite sources are generally named <classname>_test.cpp, where <classname> is the class tested by the file (or a base class of classes tested by the file, when these derived classes are similar enough to be tested in the same way). BDM doesn't test abstract classes using mock-ups (although it does test some template instantiations on test-only classes) - all its abstract classes already have concrete children and methods of the base class can be tested on them.</p> |
|---|
| 73 | <p>When run, testsuite prints to standard output the names of performed tests and error messages when they fail, which means, among other things, that it should generally be run from the command line - even on Windows. Note that while UnitTest++ does have support for more elaborate GUIs, this support hasn't been extended for BDM-specific use cases. Testsuite can also be run under debugging tools - not only under a debugger, but also valgrind for checking memory management, coverage tools etc.</p> |
|---|
| 74 | <p>Specific tests can be run individually, by passing their name (or names) as a command-line argument to testsuite. Note that a test which behaves differently depending on which tests run before it is a bug in testsuite (this can happen e.g. when using RVs, which are global - it's probably best to include the tested class name in their names, although not all existing tests do that yet). Tests of sampling and other functionality depending on random inputs can occasionally fail. Whether that's due to skewed inputs, BDM bugs or too tight error limits is not clear. Testsuite aims for every test passing with at least 95% probability, but the quantification of error limits isn't finished yet.</p> |
|---|
| 75 | <p>Not all tests depending on UnitTest++ are in testsuite. Performance experiments have their own executables - currently just square_mat_stress, for testing BDM matrix wrappers. square_mat_stress is more configurable than testsuite: it doesn't generate its own random data, but reads them from a configuration file (named agenda.cfg by default) generated by another executable, square_mat_prep. This allows generation (and checking) of test inputs for various numerically demanding scenarios, which are encapsulated in square_mat_prep's generators - that is, classes implementing its generator interface. generators themselves are configurable using the same scripting framework as other BDM classes, and both square_mat_prep and square_mat_stress have command-line parameters - run them with '-?' to see the list. Analogical support can be created for other classes which would benefit from it. Focus of stress tests is rather different from unit tests as generally understood - that a class has stress tests doesn't mean it shouldn't be tested separately inside testsuite.</p> |
|---|
| 76 | <h2><a class="anchor" id="new_unit_tests"> |
|---|
| [590] | 77 | Adding new unit tests</a></h2> |
|---|
| [591] | 78 | <p>Adding new unit tests is encouraged - it's a good way to get acquainted with the library, and there's always space for more tests.</p> |
|---|
| 79 | <p>Unit tests are implemented by adding a block of code (it actually isn't just a function body, but it looks like one) starting with the TEST macro, whose argument is the test name:</p> |
|---|
| [590] | 80 | <div class="fragment"><pre class="fragment">TEST ( test_egiw ) { |
|---|
| [591] | 81 | epdf_harness::test_config ( <span class="stringliteral">"egiw.cfg"</span> ); |
|---|
| [590] | 82 | } |
|---|
| [591] | 83 | </pre></div><p>"UnitTest++.h" should be included in every test file to have the macro defined.</p> |
|---|
| 84 | <p>Tests are usually named test_<classname>, or test_<classname>_postfix when a class has more than one test:</p> |
|---|
| [590] | 85 | <div class="fragment"><pre class="fragment">TEST ( test_egiw_1_2 ) { |
|---|
| [591] | 86 | </pre></div><p>This is useful when a class should be thoroughly tested from multiple aspects, e.g. for different dimensions. Exception-throwing execution paths are also generally run by extra tests, whose names end with _error. Note that each test in testsuite must have a unique name, which must be a legal C++ identifier.</p> |
|---|
| 87 | <p>Testsuite has explicit support for testing classes derived from <a class="el" href="classbdm_1_1epdf.html" title="Probability density function with numerical statistics, e.g. posterior density.">bdm::epdf</a> and <a class="el" href="classbdm_1_1mpdf.html" title="Conditional probability density, e.g. modeling , where is random variable, rv, and...">bdm::mpdf</a>: bdm::epdf_harness and bdm::mpdf_harness. These classes run a list of tests on objects created from the specified configuration file (normally called <classname>.cfg) and check them against expected values also specified in that file, so that a test using harness is just a single-line call to its test_config method (as above).</p> |
|---|
| 88 | <p>Unit tests can also be written explicitly. The test body is normal C++ code, implementing the checks of actual against expected values using various CHECK_* macros defined by UnitTest++:</p> |
|---|
| [590] | 89 | <div class="fragment"><pre class="fragment"> <span class="keywordtype">double</span> summ = 0.0; |
|---|
| 90 | <span class="keywordflow">for</span> ( <span class="keywordtype">int</span> k = 0; k < n; k++ ) { <span class="comment">// ALL b</span> |
|---|
| 91 | ... |
|---|
| 92 | } |
|---|
| 93 | |
|---|
| 94 | CHECK_CLOSE ( 1.0, summ, 0.1 ); |
|---|
| [591] | 95 | </pre></div><p>Note that when checking vectors or matrices, you should also include "mat_checks.h", which defines their comparison. Unit tests shouldn't require any user interaction and probably shouldn't output anything other than error reports via the UnitTest++ facilities - among other things, UnitTest++ uses C functions for its output, and therefore a test printing via std::cout and std::cerr may report in rather confusing mixed order.</p> |
|---|
| 96 | <p>Developers wishing to add new tests can use various heuristics to come up with the specific functionality to test - a selection is described below, roughly in the order of usefulness.</p> |
|---|
| 97 | <h3><a class="anchor" id="existing_bugs"> |
|---|
| [590] | 98 | Eliciting existing bugs</a></h3> |
|---|
| [591] | 99 | <p>When the library has a bug, it may be useful to isolate the smallest possible code snippet which exhibits it - if not always, then at least as reliably as possible. Such a snippet is a good candidate for a unit test - it can be added either before the bug is fixed, or afterwards.</p> |
|---|
| 100 | <h3><a class="anchor" id="tricky_parts"> |
|---|
| [590] | 101 | Testing the code known to be tricky</a></h3> |
|---|
| [591] | 102 | <p>Every body of code has its dark corners - copy&pasted legacy code, highly optimized algorithms, complicated interactions. These should be tested first.</p> |
|---|
| 103 | <h3><a class="anchor" id="unclear_behavior"> |
|---|
| [590] | 104 | Documenting and stabilizing unclear behavior</a></h3> |
|---|
| [591] | 105 | <p>The library can behave in ways surprising its users without being necessarily "wrong". In such cases, it's most important that all maintainers agree on what the correct behavior should be (so that attempts to fix it don't run in circles). Unit tests constraining the contested functionality communicate very efficiently what their author thinks the behavior should (or shouldn't) be.</p> |
|---|
| 106 | <h3><a class="anchor" id="coverage"> |
|---|
| [590] | 107 | Increasing test coverage</a></h3> |
|---|
| [591] | 108 | <p>Ideally, unit tests should test every method of every class (there are higher ideals, but they're even less realistic). Failing that, at least some methods of every class should be tested. Coverage tools (e.g. gcov) can show which parts of the library are not exercised by testsuite. </p> |
|---|
| 109 | </div> |
|---|
| [617] | 110 | <hr size="1"/><address style="text-align: right;"><small>Generated on Tue Sep 15 23:42:47 2009 for mixpp by |
|---|
| [590] | 111 | <a href="http://www.doxygen.org/index.html"> |
|---|
| [591] | 112 | <img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.6.1 </small></address> |
|---|
| [590] | 113 | </body> |
|---|
| 114 | </html> |
|---|
