configuration.html (19391B)
1 <!DOCTYPE html> 2 <html> 3 <title>configuration</title> 4 <xmp theme="united" style="display:none;"> 5 6 ## Configuration 7 8 **doctest** is designed to "just work" as much as possible. It also allows configuring how it is built with a set of identifiers. 9 10 The identifiers should be defined before the inclusion of the framework header. 11 12 Defining something ```globally``` means for every source file of the binary (executable / shared object). 13 14 - [**```DOCTEST_CONFIG_IMPLEMENT_WITH_MAIN```**](#doctest_config_implement_with_main) 15 - [**```DOCTEST_CONFIG_IMPLEMENT```**](#doctest_config_implement) 16 - [**```DOCTEST_CONFIG_DISABLE```**](#doctest_config_disable) 17 - [**```DOCTEST_CONFIG_IMPLEMENTATION_IN_DLL```**](#doctest_config_implementation_in_dll) 18 - [**```DOCTEST_CONFIG_NO_SHORT_MACRO_NAMES```**](#doctest_config_no_short_macro_names) 19 - [**```DOCTEST_CONFIG_TREAT_CHAR_STAR_AS_STRING```**](#doctest_config_treat_char_star_as_string) 20 - [**```DOCTEST_CONFIG_REQUIRE_STRINGIFICATION_FOR_ALL_USED_TYPES```**](#doctest_config_require_stringification_for_all_used_types) 21 - [**```DOCTEST_CONFIG_DOUBLE_STRINGIFY```**](#doctest_config_double_stringify) 22 - [**```DOCTEST_CONFIG_SUPER_FAST_ASSERTS```**](#doctest_config_super_fast_asserts) 23 - [**```DOCTEST_CONFIG_USE_STD_HEADERS```**](#doctest_config_use_std_headers) 24 - [**```DOCTEST_CONFIG_VOID_CAST_EXPRESSIONS```**](#doctest_config_void_cast_expressions) 25 - [**```DOCTEST_CONFIG_NO_COMPARISON_WARNING_SUPPRESSION```**](#doctest_config_no_comparison_warning_suppression) 26 - [**```DOCTEST_CONFIG_OPTIONS_PREFIX```**](#doctest_config_options_prefix) 27 - [**```DOCTEST_CONFIG_NO_UNPREFIXED_OPTIONS```**](#doctest_config_no_unprefixed_options) 28 - [**```DOCTEST_CONFIG_NO_TRY_CATCH_IN_ASSERTS```**](#doctest_config_no_try_catch_in_asserts) 29 - [**```DOCTEST_CONFIG_NO_EXCEPTIONS```**](#doctest_config_no_exceptions) 30 - [**```DOCTEST_CONFIG_NO_EXCEPTIONS_BUT_WITH_ALL_ASSERTS```**](#doctest_config_no_exceptions_but_with_all_asserts) 31 - [**```DOCTEST_CONFIG_ASSERTION_PARAMETERS_BY_VALUE```**](#doctest_config_assertion_parameters_by_value) 32 - [**```DOCTEST_CONFIG_COLORS_NONE```**](#doctest_config_colors_none) 33 - [**```DOCTEST_CONFIG_COLORS_WINDOWS```**](#doctest_config_colors_windows) 34 - [**```DOCTEST_CONFIG_COLORS_ANSI```**](#doctest_config_colors_ansi) 35 - [**```DOCTEST_CONFIG_WINDOWS_SEH```**](#doctest_config_windows_seh) 36 - [**```DOCTEST_CONFIG_NO_WINDOWS_SEH```**](#doctest_config_no_windows_seh) 37 - [**```DOCTEST_CONFIG_POSIX_SIGNALS```**](#doctest_config_posix_signals) 38 - [**```DOCTEST_CONFIG_NO_POSIX_SIGNALS```**](#doctest_config_no_posix_signals) 39 - [**```DOCTEST_CONFIG_INCLUDE_TYPE_TRAITS```**](#doctest_config_include_type_traits) 40 - [**```DOCTEST_CONFIG_NO_MULTITHREADING```**](#doctest_config_no_multithreading) 41 - [**```DOCTEST_CONFIG_NO_MULTI_LANE_ATOMICS```**](#doctest_config_no_multi_lane_atomics) 42 - [**```DOCTEST_CONFIG_ASSERTS_RETURN_VALUES```**](#doctest_config_asserts_return_values) 43 - [**```DOCTEST_CONFIG_EVALUATE_ASSERTS_EVEN_WHEN_DISABLED```**](#doctest_config_evaluate_asserts_even_when_disabled) 44 45 For most people the only configuration needed is telling **doctest** which source file should host all the implementation code: 46 47 ### **```DOCTEST_CONFIG_IMPLEMENT_WITH_MAIN```** 48 49 ``` 50 #define DOCTEST_CONFIG_IMPLEMENT_WITH_MAIN 51 #include "doctest.h" 52 ``` 53 54 This should be defined only in the source file where the library is implemented. It also creates a ```main()``` entry point. 55 56 ### **```DOCTEST_CONFIG_IMPLEMENT```** 57 58 If the client wants to [**supply the ```main()``` function**](main.html) (either to set an option with some value from the code or to integrate the framework into their existing project codebase) this identifier should be used. 59 60 This should be defined only in the source file where the library is implemented. 61 62 ### **```DOCTEST_CONFIG_DISABLE```** 63 64 One of the most important configuration options - everything testing-related is removed from the binary - including most of the framework implementation and every test case written anywhere! This is one of the most unique features of **doctest**. 65 66 This should be defined globally. 67 68 ### **```DOCTEST_CONFIG_IMPLEMENTATION_IN_DLL```** 69 70 This will affect the public interface of doctest - all necessary forward declarations for writing tests will be turned into imported symbols. That way the test runner doesn't have to be implemented in the binary (executable / shared object) and can be reused from another binary where it is built and exported. 71 72 To export the test runner from a binary simply use [**```DOCTEST_CONFIG_IMPLEMENTATION_IN_DLL```**](#doctest_config_implementation_in_dll) together with [**```DOCTEST_CONFIG_IMPLEMENT```**](#doctest_config_implement) (or [**```DOCTEST_CONFIG_IMPLEMENT_WITH_MAIN```**](#doctest_config_implement_with_main) but then the other binaries will have to link to the executable) in whatever source file the test runner gets implemented into. Note that this identifier should not be defined in the other source files of the binary which exports the doctest test runner - or there will be linker conflicts - having the same symbols as both imported and exported within the same binary. 73 74 Checkout the [**example**](../../examples/executable_dll_and_plugin/) - it shows how to have the test runner implemented in a dll (and there are even tests in a plugin which is dynamically loaded). 75 76 This should be defined globally in binaries that import the symbols. 77 78 This should be defined only in the source file where the library is implemented for binaries that export the test runner. 79 80 ### **```DOCTEST_CONFIG_NO_SHORT_MACRO_NAMES```** 81 82 This will remove all macros from **doctest** that don't have the **```DOCTEST_```** prefix - like **```CHECK```**, **```TEST_CASE```** and **```SUBCASE```**. Then only the full macro names will be available - **```DOCTEST_CHECK```**, **```DOCTEST_TEST_CASE```** and **```DOCTEST_SUBCASE```**. The user is free to make their own short versions of these macros - [**example**](../../examples/all_features/alternative_macros.cpp). 83 84 This can be defined both globally and in specific source files only. 85 86 ### **```DOCTEST_CONFIG_TREAT_CHAR_STAR_AS_STRING```** 87 88 By default ```char*``` is being treated as a pointer. With this option comparing ```char*``` pointers will switch to using ```strcmp()``` for comparisons and when stringified the string will be printed instead of the pointer value. 89 90 This should be defined globally. 91 92 ### **```DOCTEST_CONFIG_REQUIRE_STRINGIFICATION_FOR_ALL_USED_TYPES```** 93 94 By default if stringification is not available for a type, it is simply printed as `{?}`. By enabling this flag, whenever a type is used in an assert that does not provide stringification, the compilation is stopped. 95 96 This can be defined both globally and in specific source files only. 97 98 ### **```DOCTEST_CONFIG_DOUBLE_STRINGIFY```** 99 100 If you define your own `toString` functions that return something, that's different from `doctest::String`, but still stringifiable, you can enable this flag to stringify the result of internal stringification calls again. 101 102 You can also define `DOCTEST_STRINGIFY` yourself to override doctest's stringification behavior. 103 104 This can be defined both globally and in specific source files only. 105 106 ### **```DOCTEST_CONFIG_SUPER_FAST_ASSERTS```** 107 108 This config option makes the assert macros (except for those dealing with exceptions) compile [**much faster**](benchmarks.html#cost-of-an-assertion-macro)! (31-91% - depending on the type - [**normal**](assertions.html#expression-decomposing-asserts) or [**binary**](assertions.html#binary-and-unary-asserts)) 109 110 Each assert is turned into a single function call - the only downside of this is: if an assert fails and a debugger is attached - when it breaks it will be in an internal function - the user will have to go 1 level up in the callstack to see the actual assert. 111 112 It also implies [**```DOCTEST_CONFIG_NO_TRY_CATCH_IN_ASSERTS```**](#doctest_config_no_try_catch_in_asserts) (so exceptions thrown during the evaluation of an assert are not caught by the assert itself but by the testing framework - meaning that the test case is immediately aborted). 113 114 This can be defined both globally and in specific source files only. 115 116 ### **```DOCTEST_CONFIG_USE_STD_HEADERS```** 117 118 The library by default provides a forward declaration of ```std::ostream``` in order to support the ```operator<<``` [**stringification**](stringification.html) mechanism (also ```std::tuple<>``` and ```std::nullptr_t```). This is forbidden by the standard (even though it works everywhere on all tested compilers). However if the user wishes to be 100% standards compliant - then this configuration option can be used to force the inclusion of the relevant standard headers. 119 120 Also it is possible that some STL implementation of a compiler with niche usage defines them differently - then there will be compilation errors in STL headers and using this option should fix the problem. 121 122 This should be defined globally. 123 124 ### **```DOCTEST_CONFIG_VOID_CAST_EXPRESSIONS```** 125 126 This affects the [asserts dealing with exceptions](assertions.html#exceptions) - the expression is cast to void to avoid problems such as when functions with the ```[[nodiscard]]``` attribute are used but their result isn't checked. 127 128 This can be defined both globally and in specific source files only. 129 130 ### **```DOCTEST_CONFIG_NO_COMPARISON_WARNING_SUPPRESSION```** 131 132 By default the library suppresses warnings about comparing signed and unsigned types, etc. 133 134 - g++/clang ```-Wsign-conversion``` 135 - g++/clang ```-Wsign-compare``` 136 - msvc ```C4389``` 'operator' : signed/unsigned mismatch 137 - msvc ```C4018``` 'expression' : signed/unsigned mismatch 138 139 You can checkout [**this**](https://github.com/doctest/doctest/issues/16#issuecomment-246803303) issue to better understand why I suppress these warnings by default. 140 141 This can be defined both globally and in specific source files only. 142 143 ### **```DOCTEST_CONFIG_OPTIONS_PREFIX```** 144 145 Defining this as a string will change the prefix of the [**command line**](commandline.html) options to use the given prefix instead of the default ```dt-``` prefix. This can be useful for integrating the testing framework into a client codebase, where a command option prefix like ```selftest-``` might be more clear to users. 146 147 This should be defined only in the source file where the library is implemented (it's relevant only there). 148 149 ### **```DOCTEST_CONFIG_NO_UNPREFIXED_OPTIONS```** 150 151 This will disable the short versions of the [**command line**](commandline.html) options and only the versions with ```--dt-``` prefix will be parsed by **doctest** - this is possible for easy interoperability with client command line option handling when the testing framework is integrated within a client codebase - so there are no clashes and so that the user can exclude everything starting with ```--dt-``` from their option parsing. 152 153 This should be defined only in the source file where the library is implemented (it's relevant only there). 154 155 ### **```DOCTEST_CONFIG_NO_TRY_CATCH_IN_ASSERTS```** 156 157 This will remove all ```try``` / ```catch``` sections from: 158 159 - the [normal asserts](assertions.html#expression-decomposing-asserts) 160 - the [binary and unary asserts](assertions.html#binary-and-unary-asserts) 161 162 so exceptions thrown while evaluating the expression in an assert will terminate the current test case. 163 164 This can be used for some mild compile time savings but for greater impact look into [**```DOCTEST_CONFIG_SUPER_FAST_ASSERTS```**](configuration.html#doctest_config_super_fast_asserts). 165 166 This can be defined both globally and in specific source files only. 167 168 ### **```DOCTEST_CONFIG_NO_EXCEPTIONS```** 169 170 This will remove everything that uses exceptions from the framework - it is also auto detectable if exceptions are disabled for compilers (like with ```-fno-exceptions``` for GCC/Clang). 171 172 What gets changed: 173 174 - asserts that evaluate the expression in a ```try``` / ```catch``` section no longer evaluate in such a context 175 - ```REQUIRE``` macros are gone (undefined) 176 - [exception macros](assertions.html#exceptions) are gone (undefined) 177 - the ```abort-after``` option won't be fully working because an exception is used to terminate test cases 178 179 The ```REQUIRE``` family of asserts uses exceptions to terminate the current test case when they fail. An exception is used instead of a simple ```return;``` because asserts can be used not only in a test case but also in functions called by a test case. 180 181 Also some of the [**logging macros**](logging.html#messages-which-can-optionally-fail-test-cases) which act like a ```REQUIRE``` assert (terminating the test case) - like ```FAIL()``` - start to work differently - like a ```FAIL_CHECK()```. 182 183 [**```DOCTEST_CONFIG_NO_EXCEPTIONS```**](#doctest_config_no_exceptions) implies [**```DOCTEST_CONFIG_NO_TRY_CATCH_IN_ASSERTS```**](#doctest_config_no_try_catch_in_asserts) 184 185 If you wish to use asserts that deal with exceptions and only sometimes build without exceptions - check the [**```DOCTEST_CONFIG_NO_EXCEPTIONS_BUT_WITH_ALL_ASSERTS```**](#doctest_config_no_exceptions_but_with_all_asserts) config option. 186 187 This should be defined globally. 188 189 ### **```DOCTEST_CONFIG_NO_EXCEPTIONS_BUT_WITH_ALL_ASSERTS```** 190 191 When building with no exceptions (see [**```DOCTEST_CONFIG_NO_EXCEPTIONS```**](#doctest_config_no_exceptions)) ```REQUIRE``` asserts and the ones about dealing with exceptions are gone. 192 193 If however you want your code to use these assertions and only sometimes build without exceptions - then using this config will be of help. The effects of using it are the following: 194 195 - ```REQUIRE``` asserts are not gone - but they act like ```CHECK``` asserts - when one of them fails the whole test case will be marked as failed but will not be exited immediately 196 - the [asserts for dealing with exceptions](assertions.html#exceptions) are turned into a no-op (instead of being totally undefined) 197 198 This can be defined both globally and in specific source files only. 199 200 ### **```DOCTEST_CONFIG_ASSERTION_PARAMETERS_BY_VALUE```** 201 202 This option forces all doctest asserts to copy by value the expressions they are given instead of binding them to const references. This might be useful to avoid ODR-usage of static constants (which might lead to linker errors with g++/clang): 203 204 ``` 205 template<typename T> struct type_traits { static const bool value = false; }; 206 207 // unless DOCTEST_CONFIG_ASSERTION_PARAMETERS_BY_VALUE is defined the following assertion 208 // will lead to a linker error if type_traits<int>::value isn't defined in a translation unit 209 CHECK(type_traits<int>::value == false); 210 ``` 211 212 This can be defined both globally and in specific source files only. 213 214 ### **```DOCTEST_CONFIG_COLORS_NONE```** 215 216 This will remove support for colors in the console output of the framework. 217 218 This should be defined only in the source file where the library is implemented (it's relevant only there). 219 220 ### **```DOCTEST_CONFIG_COLORS_WINDOWS```** 221 222 This will force the support for colors in the console output to use the Windows APIs and headers. 223 224 This should be defined only in the source file where the library is implemented (it's relevant only there). 225 226 ### **```DOCTEST_CONFIG_COLORS_ANSI```** 227 228 This will force the support for colors in the console output to use ANSI escape codes. 229 230 This should be defined only in the source file where the library is implemented (it's relevant only there). 231 232 ### **```DOCTEST_CONFIG_WINDOWS_SEH```** 233 234 This will enable SEH handling on Windows. Currently enabled only when compiled with MSVC, because some versions of MinGW do not have the necessary Win32 API support. The user may choose to enable this explicitly - it is known to work with the MinGW-w64 project. 235 236 This should be defined only in the source file where the library is implemented (it's relevant only there). 237 238 ### **```DOCTEST_CONFIG_NO_WINDOWS_SEH```** 239 240 This can be used to disable [**```DOCTEST_CONFIG_WINDOWS_SEH```**](#doctest_config_windows_seh) when it is auto-selected by the library. 241 242 This should be defined only in the source file where the library is implemented (it's relevant only there). 243 244 ### **```DOCTEST_CONFIG_POSIX_SIGNALS```** 245 246 This will enable the use of signals under UNIX for handling crashes. On by default. 247 248 This should be defined only in the source file where the library is implemented (it's relevant only there). 249 250 ### **```DOCTEST_CONFIG_NO_POSIX_SIGNALS```** 251 252 This can be used to disable **```DOCTEST_CONFIG_POSIX_SIGNALS```** when it is auto-selected by the library. 253 254 This should be defined only in the source file where the library is implemented (it's relevant only there). 255 256 ### **```DOCTEST_CONFIG_INCLUDE_TYPE_TRAITS```** 257 258 This can be used to include the ```<type_traits>``` C++11 header. That in turn will enable the ability for the ```Approx``` helper to be used with strong typedefs of ```double``` - check [this](https://github.com/doctest/doctest/issues/62) or [this](https://github.com/doctest/doctest/issues/85) issue for more details on that. 259 260 This can be defined both globally and in specific source files only. 261 262 ### **```DOCTEST_CONFIG_NO_MULTITHREADING```** 263 264 This can be used to disable all multithreading support. 265 266 Speeds up single threaded applications. 267 268 Includes [**```DOCTEST_CONFIG_NO_MULTI_LANE_ATOMICS```**](#doctest_config_no_multi_lane_atomics). 269 270 This should be defined only in the source file where the library is implemented (it's relevant only there). 271 272 ### **```DOCTEST_CONFIG_NO_MULTI_LANE_ATOMICS```** 273 274 This can be used to disable multi lane atomics. Multi lane atomics can speed up highly parallel use of assert statements, but have a small overhead for single threaded applications. 275 276 This should be defined only in the source file where the library is implemented (it's relevant only there). 277 278 ### **```DOCTEST_CONFIG_ASSERTS_RETURN_VALUES```** 279 280 Makes all assertion macros return a boolean value, reporting whether the assertion succeeded. This can be used, for example, to have ```nullptr``` checks that don't terminate the test case on failure. 281 282 Example: 283 ``` 284 if (CHECK(somePtr != nullptr)) 285 CHECK(somePtr->someMethod() == 42); 286 ``` 287 288 This has a slight negative impact on performance as well as disabling some functionality inside assertions (e.g. ```co_return```). 289 290 When [**```DOCTEST_CONFIG_DISABLE```**](#doctest_config_disable) is defined, all macros return ```false``` by default. 291 292 This can be defined both globally and in specific source files only. 293 294 ### **```DOCTEST_CONFIG_EVALUATE_ASSERTS_EVEN_WHEN_DISABLED```** 295 296 When [**```DOCTEST_CONFIG_ASSERTS_RETURN_VALUES```**](#doctest_config_asserts_return_values) and [**```DOCTEST_CONFIG_DISABLE```**](#doctest_config_disable) are defined, this macro will cause conditions from assertions to evaluate properly (instead of returning `false`), although all overhead and functionality from doctest is removed. This is useful when assertions are used in production code within if statements so that the condition continues to be evaluated. 297 298 Since all ```THROWS_WITH``` assertions depend on doctest functionality which is not available when [**```DOCTEST_CONFIG_DISABLE```**](#doctest_config_disable) is defined (stringification), they will still unconditionally return ```false```. 299 300 This can be defined both globally and in specific source files only. 301 302 --------------- 303 304 [Home](readme.html#reference) 305 306 <p align="center"><img src="../../scripts/data/logo/icon_2.svg"></p> 307 308 309 </xmp> 310 <script src="strapdown.js/strapdown.js"></script> 311 </html>