libs/test/doc/closing_chapters/faq.qbk

   1 [/
   2  / Copyright (c) 2003 Boost.Test contributors
   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?]
  11 The 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?]
  14 You 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?]
  18 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/].
  19
  20
  21 [h3 How to create test case using the Unit Test Framework?]
  22 To create a test case, use the macro
  23
  24   __BOOST_AUTO_TEST_CASE__( test_function );
  25
  26 For 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?]
  29 To create a test suite use the macro
  30
  31   __BOOST_AUTO_TEST_SUITE__( suite_name );
  32
  33 For 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
  38 Boost Test Library components provide several usage variants: to create a test program you can
  39 link with the one of the precompiled library variants or use header-only variant. For example, to use Unit Test
  40 Framework you may either include
  41
  42 ``
  43   #include <boost/test/unit_test.hpp>
  44 ``
  45 and link with ``libunit_test_framework.lib`` or you can include
  46
  47 ``
  48  #include <boost/test/included/unit_test.hpp>
  49 ``
  50
  51 in which case you should not need to link with any pre-compiled component. Note also that
  52 you should strictly follow specification on initialization function in other case some compilers may produce linker
  53 error like this.
  54
  55 ``
  56   Unresolved external init_unit_test_suite(int, char**).
  57 ``
  58
  59
  60 The 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?]
  64 Use ``unit_test_log::instance().set_log_output( std::ostream & )``
  65 For more details see the __UTF__ __output_test_stream_tool__ documentation.
  66
  67 [h3 I want different default log trace level]
  68 Use environment variable __BOOST_TEST_LOG_LEVEL__ to define desired log trace level. You still will be able to reset
  69 this 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?]
  73 Yes. Starting with Boost 1.34.0.
  74
  75
  76 [h3 How to set up a CMake project using __UTF__ (extended)]
  77
  78 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__.
  79
  80 Let's paste the following content in a `CMakeLists.txt`
  81 at the same location than our test file `test_file.cpp`:
  82
  83 [pre
  84 cmake_minimum_required(VERSION 2.8.7)
  85 project(my_first_test)
  86 enable_testing()
  87
  88 # indicates the location of the boost installation tree.
  89 # hard-coded for our simple example.
  90 set(BOOST_INCLUDE_DIRS $boost_installation_prefix/include)
  91
  92 # creates the executable
  93 add_executable(test_executable test_file.cpp)
  94 # indicates the include paths
  95 target_include_directories(test_executable PRIVATE ${BOOST_INCLUDE_DIRS})
  96
  97 # declares a test with our executable
  98 add_test(NAME test1 COMMAND test_executable)
  99 ]
 100
 101 We will now create the build directory for this project (separate directory),
 102 configure 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
 115 In the case you are using the [link boost_test.usage_variants.shared_lib shared libraries] variant of __UTF__,
 116 some modifications should be done in your CMakeLists.txt.
 117
 118 [pre
 119 cmake_minimum_required(VERSION 2.8.11)
 120 project(my_first_test)
 121 enable_testing()
 122
 123 # replace XX with the version you have
 124 set(Boost_ADDITIONAL_VERSIONS "1.XX" "1.XX.0")
 125
 126 # finds boost, triggers an error otherwise
 127 find_package(Boost XX REQUIRED COMPONENTS unit_test_framework)
 128
 129 # creates the executable
 130 add_executable(test_executable test_file.cpp)
 131 # indicates the include paths
 132 target_include_directories(test_executable PRIVATE ${Boost_INCLUDE_DIRS})
 133 # indicates the shared library variant
 134 target_compile_definitions(test_executable PRIVATE "BOOST_TEST_DYN_LINK=1")
 135 # indicates the link paths
 136 target_link_libraries(test_executable ${Boost_UNIT_TEST_FRAMEWORK_LIBRARY})
 137
 138 # declares a test with our executable
 139 add_test(NAME test1 COMMAND test_executable)
 140
 141 ]
 142
 143 We will now create the build directory for this project (separate directory), configure and build the project,
 144 as 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]