123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166 |
- [/
- / Copyright (c) 2003 Boost.Test contributors
- /
- / Distributed under the Boost Software License, Version 1.0. (See accompanying
- / file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
- /]
- [#ref_usage_recommendations][section Practical usage recommendations]
- Following pages present tips and recommendations on how to use and apply the __UTF__ in your real life practice.
- You don't necessarily need to follow them, but we found them handy.
- Here you will also find some tutorials from Boost.Test authors and world wide.
- [section General]
- [h4 Prefer offline compiled libraries to the inline included components]
- If you are just want to write quick simple test in environment where you never used Boost.Test before - yes,
- use included components. But if you plan to use Boost.Test on permanent basis, small investment of time needed
- to build (if not build yet), install and change you makefiles/project settings will soon return to you in a
- form of shorter compilation time. Why do you need to make your compiler do the same work over and over again?
- [h4 If you use only free function based test cases advance to the automatic registration facility]
- It's really easy to switch to automatic registration. And you don't need to worry about forgotten test cases.
- [h4 To find location of first error reported by test tool within reused template function, use special hook within framework headers]
- In some cases you are reusing the same template based code from within one test case (actually we recommend
- better solution in such case - see below). Now if an error gets reported by the test tool within that reused
- code you may have difficulty locating were exactly error occurred. To address this issue you could either a add
- __BOOST_TEST_MESSAGE__ statements in templated code that log current type id of template parameters or you can use special hook located in
- `unit_test_result.hpp` called `first_failed_assertion()`. If you set a breakpoint right on the line where this
- function is defined you will be able to unroll the stack and see where error actually occurred.
- [h4 To test reusable template base component with different template parameter use test case template facility]
- If you writing unit test for generic reusable component you may have a need to test it against set of different
- template parameter types . Most probably you will end up with a code like this:
- ``
- template<typename TestType>
- void specific_type_test( TestType* = 0 )
- {
- MyComponent<TestType> c;
- // ... here we perform actual testing
- }
- void my_component_test()
- {
- specific_type_test( (int*)0 );
- specific_type_test( (float*)0 );
- specific_type_test( (UDT*)0 );
- // ...
- }
- ``
- This is namely the situation where you would use test case template facility. It not only simplifies this kind
- of unit testing by automating some of the work, in addition every argument type gets tested separately under
- unit test monitor. As a result if one of types produce exception or non-fatal error you may still continue and
- get results from testing with other types.
- [endsect][/ General]
- [section IDE usage recommendations]
- This recommendation is shown using Microsoft Visual Studio as an example, but you can apply similar steps in
- different IDEs.
- [h4 Use custom build step to automatically start test program after compilation]
- I found it most convenient to put test program execution as a post-build step in compilation. To do so use
- project property page:
- [$images/post_build_event.jpg]
- Full command you need in "Command Line" field is:
- [pre
- "$(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
- ]
- Note that both report level and result code are suppressed. This way the only output you may see from this
- command are possible runtime errors. But the best part is that you could jump through these errors using usual
- keyboard shortcuts/mouse clicks you use for compilation error analysis:
- [$images/post_build_out.jpg]
- [h4 If you got fatal exception somewhere within test case, make debugger break at the point the failure by adding
- extra command line argument]
- If you got "memory access violation" message (or any other message indication fatal or system error) when you
- run you test, to get more information of error location add
- [pre
- --[link boost_test.utf_reference.rt_param_reference.catch_system catch_system_error]=no
- ]
- to the test run command line:
- [$images/run_args.jpg]
- Now run the test again under debugger and it will break at the point of failure.
- [endsect] [/ IDE]
- [section Command line usage recommendations]
- [h4 If you got fatal exception somewhere within test case, make program generate core-dump by adding extra command
- line argument]
- If you got "memory access violation" message (or any other message indication fatal or system error) when you
- run you test, to get more information about the error location add
- [pre
- --[link boost_test.utf_reference.rt_param_reference.catch_system catch_system_error]=no
- ]
- to the test run command line. Now run the test again and it will create a core-dump you could analyze using you preferable
- debugger. Or run it under debugger in a first place and it will break at the point of failure.
- [h4 How to use test module build with Boost.Test framework under management of automated regression test facilities?]
- My first recommendation is to make sure that the test framework catches all fatal errors by adding argument
- [pre
- --[link boost_test.utf_reference.rt_param_reference.catch_system catch_system_error]=yes
- ]
- to all test modules invocations. Otherwise test program may produce unwanted dialogs (depends on compiler and OS) that will halt you
- regression tests run. The second recommendation is to suppress result report output by adding
- [pre
- --[link boost_test.utf_reference.rt_param_reference.report_level report_level]=no
- ]
- argument and test log output by adding
- [pre
- --[link boost_test.utf_reference.rt_param_reference.log_level log_level]=nothing
- ]
- argument, so that test module won't produce undesirable output no one is going to look at
- anyway. We recommend relying only on result code that will be consistent for all test programs. An
- alternative to my second recommendation is direct both log and report to separate file you could analyze
- later on. Moreover you can make Boost.Test to produce them in XML or JUNIT format using
- [pre
- --[link boost_test.utf_reference.rt_param_reference.output_format output_format]=XML
- ]
- or
- [pre
- --[link boost_test.utf_reference.rt_param_reference.log_format log_format]=JUNIT
- ]
- and use some automated tool that will format this information as you like.
- [endsect][/command line]
- [section Tutorials]
- [include tutorials/new_year_resolution.qbk]
- [include tutorials/hello_world.qbk]
- [endsect] [/ tutorials]
- [include tutorials/web_wisdom.qbk]
- [endsect] [/ recommendations]
- [/EOF]
|