1[/
2 / Copyright (c) 2003 Boost.Test team
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[section:section_faq Frequently Asked Questions]
9
10[h3 Where the latest version of the Boost Test Library is located?]
11The latest version of Boost Test Library is available online at [@http://www.boost.org/libs/test].
12
13[h3 I found a bug. Where can I report it?]
14You can send a bug report to the boost users' mailing list and/or fill a ticket here [@https://svn.boost.org/trac/boost/].
15
16
17[h3 I have a request for a new feature. Where can I ask for it?]
18You can send a request to the boost developers' mailing list and/or and/or fill a ticket here [@https://svn.boost.org/trac/boost/].
19
20
21[h3 How to create test case using the Unit Test Framework?]
22To create a test case, use the macro
23
24  __BOOST_AUTO_TEST_CASE__( test_function );
25
26For more details see the Unit Test Framework __BOOST_AUTO_TEST_CASE__ documentation.
27
28[h3 How to create test suite using the Unit Test Framework?]
29To create a test suite use the macro
30
31  __BOOST_AUTO_TEST_SUITE__( suite_name );
32
33For more details see the Unit Test Framework __BOOST_AUTO_TEST_SUITE__ documentation.
34
35
36[h3 Why did I get a linker error when compiling my test program?]
37
38Boost Test Library components provide several usage variants: to create a test program you can
39link with the one of the precompiled library variants or use single-header variant. For example, to use Unit Test
40Framework you may either include
41
42``
43  #include <boost/test/unit_test.hpp>
44``
45and link with ``libunit_test_framework.lib`` or you can include
46
47``
48 #include <boost/test/included/unit_test.hpp>
49``
50
51in which case you should not need to link with any precompiled component. Note also that
52you should strictly follow specification on initialization function in other case some compilers may produce linker
53error like this.
54
55``
56  Unresolved external init_unit_test_suite(int, char**).
57``
58
59
60The reason for this error is that in your implementation you should specify second argument of
61`init_unit_test_suite` exactly as in the specification, i.e.: `char* []`.
62
63[h3 How can I redirect testing output?]
64Use ``unit_test_log::instance().set_log_output( std::ostream & )``
65For more details see the __UTF__ __output_test_stream_tool__ documentation.
66
67[h3 I want different default log trace level]
68Use environment variable __BOOST_TEST_LOG_LEVEL__ to define desired log trace level. You still will be able to reset
69this value from the command line. For the list of acceptable values see the __UTF__
70__runtime_configuration__ documentation.
71
72[h3 Is there DLL version of Boost.Test components available on Win32 platform?]
73Yes. Starting with Boost 1.34.0.
74
75
76[h3 How to set up a CMake project using __UTF__ (extended)]
77
78Suppose, 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 single-header usage variant] of the __UTF__.
79
80Let's paste the following content in a `CMakeLists.txt`
81at the same location than our test file `test_file.cpp`:
82
83[pre
84cmake_minimum_required(VERSION 2.8.7)
85project(my_first_test)
86enable_testing()
87
88# indicates the location of the boost installation tree.
89# hard-coded for our simple example.
90set(BOOST_INCLUDE_DIRS $boost_installation_prefix/include)
91
92# creates the executable
93add_executable(test_executable test_file.cpp)
94# indicates the include paths
95target_include_directories(test_executable PRIVATE ${BOOST_INCLUDE_DIRS})
96
97# declares a test with our executable
98add_test(NAME test1 COMMAND test_executable)
99]
100
101We will now create the build directory for this project (separate directory),
102configure and build the project, as follow:
103```
104> cd ``$``test_path
105> mkdir build     /*< we create a directory dedicated to the build, to avoid
106                      any pollution of the sources with the temporary
107                      build files >*/
108> cd build
109> cmake  ..       /*< configuration of the project >*/
110> cmake --build . /*< this command builds the project, cmake drives a native
111                      tool that is configured on the previous command line >*/
112> ctest           /*< runs the tests declared in the project and prints a report >*/
113```
114
115In the case you are using the [link boost_test.usage_variants.shared_lib shared libraries] variant of __UTF__,
116some modifications should be done in your CMakeLists.txt.
117
118[pre
119cmake_minimum_required(VERSION 2.8.11)
120project(my_first_test)
121enable_testing()
122
123# replace XX with the version you have
124set(Boost_ADDITIONAL_VERSIONS "1.XX" "1.XX.0")
125
126# finds boost, triggers an error otherwise
127find_package(Boost XX REQUIRED COMPONENTS unit_test_framework)
128
129# creates the executable
130add_executable(test_executable test_file.cpp)
131# indicates the include paths
132target_include_directories(test_executable PRIVATE ${Boost_INCLUDE_DIRS})
133# indicates the shared library variant
134target_compile_definitions(test_executable PRIVATE "BOOST_TEST_DYN_LINK=1")
135# indicates the link paths
136target_link_libraries(test_executable ${Boost_UNIT_TEST_FRAMEWORK_LIBRARY})
137
138# declares a test with our executable
139add_test(NAME test1 COMMAND test_executable)
140
141]
142
143We will now create the build directory for this project (separate directory), configure and build the project,
144as follow:
145```
146> cd ``$``test_path
147> mkdir build /*< we create a directory dedicated to the build, to avoid any pollution of the sources with the temporary
148                  build files >*/
149> cd build
150> cmake -DBOOST_ROOT=``$``boost_installation_prefix .. /*< configuration of the project, the `BOOST_ROOT` configuration element indicates the
151                                                           Boost module of `cmake` where to find our installation >*/
152> cmake --build . /*< this command builds the project, cmake drives a native tool that is configured on the
153                      previous command line >*/
154> ctest           /*< runs the tests declared in the project and prints a report >*/
155```
156
157
158
159[endsect] [/faq]