test/doc/closing_chapters/faq.qbk

[/
 / 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)
 /]

[section:section_faq Frequently Asked Questions]

[h3 Where the latest version of the Boost Test Library is located?]
The latest version of Boost Test Library is available online at [@http://www.boost.org/libs/test].

[h3 I found a bug. Where can I report it?]
You can send a bug report to the boost users' mailing list and/or fill a ticket here [@https://svn.boost.org/trac/boost/].


[h3 I have a request for a new feature. Where can I ask for it?]
You can send a request to the boost developers' mailing list and/or and/or fill a ticket here [@https://svn.boost.org/trac/boost/].


[h3 How to create test case using the Unit Test Framework?]
To create a test case, use the macro

  __BOOST_AUTO_TEST_CASE__( test_function );

For more details see the Unit Test Framework __BOOST_AUTO_TEST_CASE__ documentation.

[h3 How to create test suite using the Unit Test Framework?]
To create a test suite use the macro

  __BOOST_AUTO_TEST_SUITE__( suite_name );

For more details see the Unit Test Framework __BOOST_AUTO_TEST_SUITE__ documentation.


[h3 Why did I get a linker error when compiling my test program?]

Boost Test Library components provide several usage variants: to create a test program you can
link with the one of the precompiled library variants or use header-only variant. For example, to use Unit Test
Framework you may either include

``
  #include <boost/test/unit_test.hpp>
``
and link with ``libunit_test_framework.lib`` or you can include

``
 #include <boost/test/included/unit_test.hpp>
``

in which case you should not need to link with any pre-compiled component. Note also that
you should strictly follow specification on initialization function in other case some compilers may produce linker
error like this.

``
  Unresolved external init_unit_test_suite(int, char**).
``


The reason for this error is that in your implementation you should specify second argument of
`init_unit_test_suite` exactly as in the specification, i.e.: `char* []`.

[h3 How can I redirect testing output?]
Use ``unit_test_log::instance().set_log_output( std::ostream & )``
For more details see the __UTF__ __output_test_stream_tool__ documentation.

[h3 I want different default log trace level]
Use environment variable __BOOST_TEST_LOG_LEVEL__ to define desired log trace level. You still will be able to reset
this value from the command line. For the list of acceptable values see the __UTF__
__runtime_configuration__ documentation.

[h3 Is there DLL version of Boost.Test components available on Win32 platform?]
Yes. Starting with Boost 1.34.0.


[h3 How to set up a CMake project using __UTF__ (extended)]

Suppose, you are building a test module from one translation unit `test_file.cpp`. First, let's do it using the [link boost_test.usage_variants.single_header header-only usage variant] of the __UTF__.

Let's paste the following content in a `CMakeLists.txt`
at the same location than our test file `test_file.cpp`:

[pre
cmake_minimum_required(VERSION 2.8.7)
project(my_first_test)
enable_testing()

# indicates the location of the boost installation tree.
# hard-coded for our simple example.
set(BOOST_INCLUDE_DIRS $boost_installation_prefix/include)

# creates the executable
add_executable(test_executable test_file.cpp)
# indicates the include paths
target_include_directories(test_executable PRIVATE ${BOOST_INCLUDE_DIRS})

# declares a test with our executable
add_test(NAME test1 COMMAND test_executable)
]

We will now create the build directory for this project (separate directory),
configure and build the project, as follow:
```
> cd ``$``test_path
> mkdir build     /*< we create a directory dedicated to the build, to avoid
                      any pollution of the sources with the temporary
                      build files >*/
> cd build
> cmake  ..       /*< configuration of the project >*/
> cmake --build . /*< this command builds the project, cmake drives a native
                      tool that is configured on the previous command line >*/
> ctest           /*< runs the tests declared in the project and prints a report >*/
```

In the case you are using the [link boost_test.usage_variants.shared_lib shared libraries] variant of __UTF__,
some modifications should be done in your CMakeLists.txt.

[pre
cmake_minimum_required(VERSION 2.8.11)
project(my_first_test)
enable_testing()

# replace XX with the version you have
set(Boost_ADDITIONAL_VERSIONS "1.XX" "1.XX.0")

# finds boost, triggers an error otherwise
find_package(Boost XX REQUIRED COMPONENTS unit_test_framework)

# creates the executable
add_executable(test_executable test_file.cpp)
# indicates the include paths
target_include_directories(test_executable PRIVATE ${Boost_INCLUDE_DIRS})
# indicates the shared library variant
target_compile_definitions(test_executable PRIVATE "BOOST_TEST_DYN_LINK=1")
# indicates the link paths
target_link_libraries(test_executable ${Boost_UNIT_TEST_FRAMEWORK_LIBRARY})

# declares a test with our executable
add_test(NAME test1 COMMAND test_executable)

]

We will now create the build directory for this project (separate directory), configure and build the project,
as follow:
```
> cd ``$``test_path
> mkdir build /*< we create a directory dedicated to the build, to avoid any pollution of the sources with the temporary
                  build files >*/
> cd build
> cmake -DBOOST_ROOT=``$``boost_installation_prefix .. /*< configuration of the project, the `BOOST_ROOT` configuration element indicates the
                                                           Boost module of `cmake` where to find our installation >*/
> cmake --build . /*< this command builds the project, cmake drives a native tool that is configured on the
                      previous command line >*/
> ctest           /*< runs the tests declared in the project and prints a report >*/
```



[endsect] [/faq]