]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
1 | [/ |
2 | / Copyright (c) 2003 Boost.Test contributors | |
3 | / | |
4 | / Distributed under the Boost Software License, Version 1.0. (See accompanying | |
5 | / file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) | |
6 | /] | |
7 | ||
8 | [#ref_usage_recommendations][section Practical usage recommendations] | |
9 | ||
10 | Following pages present tips and recommendations on how to use and apply the __UTF__ in your real life practice. | |
11 | You don't necessarily need to follow them, but we found them handy. | |
12 | ||
13 | Here you will also find some tutorials from Boost.Test authors and world wide. | |
14 | ||
15 | [section General] | |
16 | ||
17 | [h4 Prefer offline compiled libraries to the inline included components] | |
18 | If you are just want to write quick simple test in environment where you never used Boost.Test before - yes, | |
19 | use included components. But if you plan to use Boost.Test on permanent basis, small investment of time needed | |
20 | to build (if not build yet), install and change you makefiles/project settings will soon return to you in a | |
21 | form of shorter compilation time. Why do you need to make your compiler do the same work over and over again? | |
22 | ||
23 | [h4 If you use only free function based test cases advance to the automatic registration facility] | |
24 | It's really easy to switch to automatic registration. And you don't need to worry about forgotten test cases. | |
25 | ||
26 | [h4 To find location of first error reported by test tool within reused template function, use special hook within framework headers] | |
27 | In some cases you are reusing the same template based code from within one test case (actually we recommend | |
28 | better solution in such case - see below). Now if an error gets reported by the test tool within that reused | |
29 | code you may have difficulty locating were exactly error occurred. To address this issue you could either a add | |
30 | __BOOST_TEST_MESSAGE__ statements in templated code that log current type id of template parameters or you can use special hook located in | |
31 | `unit_test_result.hpp` called `first_failed_assertion()`. If you set a breakpoint right on the line where this | |
32 | function is defined you will be able to unroll the stack and see where error actually occurred. | |
33 | ||
34 | ||
35 | [h4 To test reusable template base component with different template parameter use test case template facility] | |
36 | If you writing unit test for generic reusable component you may have a need to test it against set of different | |
37 | template parameter types . Most probably you will end up with a code like this: | |
38 | ||
39 | `` | |
40 | template<typename TestType> | |
41 | void specific_type_test( TestType* = 0 ) | |
42 | { | |
43 | MyComponent<TestType> c; | |
44 | // ... here we perform actual testing | |
45 | } | |
46 | ||
47 | void my_component_test() | |
48 | { | |
49 | specific_type_test( (int*)0 ); | |
50 | specific_type_test( (float*)0 ); | |
51 | specific_type_test( (UDT*)0 ); | |
52 | // ... | |
53 | } | |
54 | `` | |
55 | ||
56 | This is namely the situation where you would use test case template facility. It not only simplifies this kind | |
57 | of unit testing by automating some of the work, in addition every argument type gets tested separately under | |
58 | unit test monitor. As a result if one of types produce exception or non-fatal error you may still continue and | |
59 | get results from testing with other types. | |
60 | ||
61 | [endsect][/ General] | |
62 | ||
63 | [section IDE usage recommendations] | |
64 | ||
65 | This recommendation is shown using Microsoft Visual Studio as an example, but you can apply similar steps in | |
66 | different IDEs. | |
67 | ||
68 | [h4 Use custom build step to automatically start test program after compilation] | |
69 | I found it most convenient to put test program execution as a post-build step in compilation. To do so use | |
70 | project property page: | |
71 | ||
72 | [$images/post_build_event.jpg] | |
73 | ||
74 | Full command you need in "Command Line" field is: | |
75 | ||
76 | [pre | |
77 | "$(TargetDir)\$(TargetName).exe" --[link boost_test.utf_reference.rt_param_reference.result_code `result_code`]=no --[link boost_test.utf_reference.rt_param_reference.report_level `report_level`]=no | |
78 | ] | |
79 | ||
80 | Note that both report level and result code are suppressed. This way the only output you may see from this | |
81 | command are possible runtime errors. But the best part is that you could jump through these errors using usual | |
82 | keyboard shortcuts/mouse clicks you use for compilation error analysis: | |
83 | ||
84 | [$images/post_build_out.jpg] | |
85 | ||
86 | [h4 If you got fatal exception somewhere within test case, make debugger break at the point the failure by adding | |
87 | extra command line argument] | |
88 | ||
89 | If you got "memory access violation" message (or any other message indication fatal or system error) when you | |
90 | run you test, to get more information of error location add | |
91 | ||
92 | [pre | |
93 | --[link boost_test.utf_reference.rt_param_reference.catch_system catch_system_error]=no | |
94 | ] | |
95 | to the test run command line: | |
96 | ||
97 | [$images/run_args.jpg] | |
98 | ||
99 | Now run the test again under debugger and it will break at the point of failure. | |
100 | ||
101 | [endsect] [/ IDE] | |
102 | ||
103 | [section Command line usage recommendations] | |
104 | ||
105 | [h4 If you got fatal exception somewhere within test case, make program generate coredump by adding extra command | |
106 | line argument] | |
107 | If you got "memory access violation" message (or any other message indication fatal or system error) when you | |
108 | run you test, to get more information about the error location add | |
109 | ||
110 | [pre | |
111 | --[link boost_test.utf_reference.rt_param_reference.catch_system catch_system_error]=no | |
112 | ] | |
113 | ||
114 | to the test run command line. Now run the test again and it will create a coredump you could analyze using you preferable | |
115 | debugger. Or run it under debugger in a first place and it will break at the point of failure. | |
116 | ||
117 | [h4 How to use test module build with Boost.Test framework under management of automated regression test facilities?] | |
118 | ||
119 | My first recommendation is to make sure that the test framework catches all fatal errors by adding argument | |
120 | ||
121 | [pre | |
122 | --[link boost_test.utf_reference.rt_param_reference.catch_system catch_system_error]=yes | |
123 | ] | |
124 | ||
125 | to all test modules invocations. Otherwise test program may produce unwanted dialogs (depends on compiler and OS) that will halt you | |
126 | regression tests run. The second recommendation is to suppress result report output by adding | |
127 | ||
128 | [pre | |
129 | --__param_report_level__=no | |
130 | ] | |
131 | ||
132 | argument and test log output by adding | |
133 | ||
134 | [pre | |
135 | --[link boost_test.utf_reference.rt_param_reference.log_level log_level]=nothing | |
136 | ] | |
137 | ||
138 | argument, so that test module won't produce undesirable output no one is going to look at | |
139 | anyway. We recommend relying only on result code that will be consistent for all test programs. An | |
140 | alternative to my second recommendation is direct both log and report to separate file you could analyze | |
141 | later on. Moreover you can make Boost.Test to produce them in XML format using | |
142 | ||
143 | [pre | |
144 | --[link boost_test.utf_reference.rt_param_reference.output_format output_format]=XML | |
145 | ] | |
146 | and use some automated tool that will format this information as you like. | |
147 | ||
148 | [endsect][/command line] | |
149 | ||
150 | [section Tutorials] | |
151 | ||
152 | [include tutorials/new_year_resolution.qbk] | |
153 | [include tutorials/hello_world.qbk] | |
154 | ||
155 | [endsect] [/ tutorials] | |
156 | ||
157 | [include tutorials/web_wisdom.qbk] | |
158 | ||
159 | [endsect] [/ recommendations] | |
160 | ||
161 | [/EOF] |