Boost Test Library generic recommendations

Boost.Test > Usage recommendations > Generic

# Generic usage recommendations

- Prefer the unit test framework to the test execution monitor
- Prefer offline compiled libraries to the inline included components
- If you use only free function based test cases advance to the automatic registration facility
- To find location of first error reported by test tool within reused template function, use special hook within framework headers
- To test reusable template base component with different template parameter use test case template facility
- Prefer BOOST_CHECK_EQUAL to BOOST_CHECK

##### Prefer the unit test framework to the test execution monitor

In most cases when you start working on unit test you have a choice to use either one of the components provided by the Boost.Test. Even though in simple cases test cases based solution would be couple lines longer in a long term I would opt to use unit test framework. At some point you will anyway end up with code like this:

    void test_feature1()
    {
        ...

    }

    int test_main()

    {

        test_feature1();
        test_feature1();
        ...
        test_featureN();
    }

Why then not switch to test cases? In code like above if any exception occurred in test_feature1() rest of test is skipped. While with test cases each separate feature test is executed and monitored separately and you are getting more from your test.

##### 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?

##### 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 case anymore.

##### 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 I 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_MESSAGE statements in templated code that log current type id od template parameters or you could 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.

##### 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's not only simplify 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.

##### Prefer BOOST_CHECK_EQUAL to BOOST_CHECK

Even though BOOSK_CHECK tool is most generic and allows to validate any bool convertible expression, I would recommend to use, if possible, more specific tools dedicated to the task. For example if you need you validate some variable vs. some expected value use BOOST_CHECK_EQUAL instead. The main advantage is that in case of failure you will see the mismatched value - the information most useful for error identification. The same applies to other tools supplied by the framework.