libs/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 Bug report of feature request: what should I do?] You can send a bug report or a feature request to the boost users' mailing list boost-users@lists.boost.org and/or fill a ticket on the GitHub issues of the project [@https://github.com/boostorg/test]. [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 Is Boost.Test thread safe?] Short answer: no, but we welcome patches! Longer answer: Boost.Test currently has no synchronization mechanisms in place to avoid any race when multiple threads are calling the assertion macros. For instance this code `` BOOST_TEST_CASE(test_parallel) { std::vector<std::string> vect(10); std::for_each( std::execution::par_unseq, vect.begin(), vect.end(), [](auto const& str) { BOOST_TEST(str == ""); }); } `` will not work as expected as the assertion `BOOST_TEST` will be called from multiple threads. [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]