Gitiles
Code Review Sign In
gerrit.cesnet.cz / github / onqtam / doctest / 8ee354591f81f0159a2cb9b2795fae9999844df5 / . / doc / html_generated / configuration.html
blob: 23360263d593e9ae126bd8b1be68a16a44640ac9 [file] [log] [blame]
onqtam8126b562016-05-27 17:01:15 +0300[diff] [blame]1<!DOCTYPE html>
2<html>
3<title>configuration</title>
4<xmp theme="united" style="display:none;">
5
6## Configuration
7
onqtam1435c012016-09-21 15:29:11 +0300[diff] [blame]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
10The identifiers should be defined before the inclusion of the framework header.
11
onqtamb8220c52017-05-16 00:21:15 +0300[diff] [blame]12Defining something ```globally``` means for every source file of the binary (executable / shared object).
13
onqtam1435c012016-09-21 15:29:11 +0300[diff] [blame]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)
onqtamb8220c52017-05-16 00:21:15 +0300[diff] [blame]17- [**```DOCTEST_CONFIG_IMPLEMENTATION_IN_DLL```**](#doctest_config_implementation_in_dll)
onqtam1435c012016-09-21 15:29:11 +0300[diff] [blame]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_SUPER_FAST_ASSERTS```**](#doctest_config_super_fast_asserts)
onqtam92dce5b2019-03-23 14:24:47 +0200[diff] [blame]21- [**```DOCTEST_CONFIG_USE_STD_HEADERS```**](#doctest_config_use_std_headers)
onqtam505b05c2019-05-06 11:39:02 +0300[diff] [blame]22- [**```DOCTEST_CONFIG_VOID_CAST_EXPRESSIONS```**](#doctest_config_void_cast_expressions)
onqtam1435c012016-09-21 15:29:11 +0300[diff] [blame]23- [**```DOCTEST_CONFIG_NO_COMPARISON_WARNING_SUPPRESSION```**](#doctest_config_no_comparison_warning_suppression)
Thomas Blehera420d8c2018-11-30 16:37:54 +0100[diff] [blame]24- [**```DOCTEST_CONFIG_OPTIONS_PREFIX```**](#doctest_config_options_prefix)
onqtam1435c012016-09-21 15:29:11 +0300[diff] [blame]25- [**```DOCTEST_CONFIG_NO_UNPREFIXED_OPTIONS```**](#doctest_config_no_unprefixed_options)
onqtame34600e2016-11-15 02:16:56 +0200[diff] [blame]26- [**```DOCTEST_CONFIG_NO_TRY_CATCH_IN_ASSERTS```**](#doctest_config_no_try_catch_in_asserts)
27- [**```DOCTEST_CONFIG_NO_EXCEPTIONS```**](#doctest_config_no_exceptions)
28- [**```DOCTEST_CONFIG_NO_EXCEPTIONS_BUT_WITH_ALL_ASSERTS```**](#doctest_config_no_exceptions_but_with_all_asserts)
onqtam1435c012016-09-21 15:29:11 +0300[diff] [blame]29- [**```DOCTEST_CONFIG_ASSERTION_PARAMETERS_BY_VALUE```**](#doctest_config_assertion_parameters_by_value)
30- [**```DOCTEST_CONFIG_COLORS_NONE```**](#doctest_config_colors_none)
31- [**```DOCTEST_CONFIG_COLORS_WINDOWS```**](#doctest_config_colors_windows)
32- [**```DOCTEST_CONFIG_COLORS_ANSI```**](#doctest_config_colors_ansi)
onqtamb8220c52017-05-16 00:21:15 +0300[diff] [blame]33- [**```DOCTEST_CONFIG_WINDOWS_SEH```**](#doctest_config_windows_seh)
34- [**```DOCTEST_CONFIG_NO_WINDOWS_SEH```**](#doctest_config_no_windows_seh)
35- [**```DOCTEST_CONFIG_POSIX_SIGNALS```**](#doctest_config_posix_signals)
36- [**```DOCTEST_CONFIG_NO_POSIX_SIGNALS```**](#doctest_config_no_posix_signals)
onqtam6a5da422017-09-04 17:56:08 +0300[diff] [blame]37- [**```DOCTEST_CONFIG_INCLUDE_TYPE_TRAITS```**](#doctest_config_include_type_traits)
Martin Ankerlf6de4872020-12-31 11:22:00 +0100[diff] [blame]38- [**```DOCTEST_CONFIG_NO_MULTI_LANE_ATOMICS```**](#doctest_config_no_multi_lane_atomics)
onqtamb8220c52017-05-16 00:21:15 +0300[diff] [blame]39
onqtam8126b562016-05-27 17:01:15 +0300[diff] [blame]40For most people the only configuration needed is telling **doctest** which source file should host all the implementation code:
41
onqtam1435c012016-09-21 15:29:11 +0300[diff] [blame]42### **```DOCTEST_CONFIG_IMPLEMENT_WITH_MAIN```**
onqtam8126b562016-05-27 17:01:15 +0300[diff] [blame]43
onqtam1435c012016-09-21 15:29:11 +0300[diff] [blame]44```
onqtam8126b562016-05-27 17:01:15 +0300[diff] [blame]45#define DOCTEST_CONFIG_IMPLEMENT_WITH_MAIN
46#include "doctest.h"
onqtam1435c012016-09-21 15:29:11 +0300[diff] [blame]47```
onqtam8126b562016-05-27 17:01:15 +0300[diff] [blame]48
Thomas Bleher04f37982018-09-26 09:20:49 +0200[diff] [blame]49This should be defined only in the source file where the library is implemented. It also creates a ```main()``` entry point.
onqtam8126b562016-05-27 17:01:15 +0300[diff] [blame]50
onqtam1435c012016-09-21 15:29:11 +0300[diff] [blame]51### **```DOCTEST_CONFIG_IMPLEMENT```**
onqtam8126b562016-05-27 17:01:15 +0300[diff] [blame]52
Michael Letterled33d1e82021-11-04 09:01:07 -0400[diff] [blame]53If 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.
onqtam8126b562016-05-27 17:01:15 +0300[diff] [blame]54
Thomas Bleher04f37982018-09-26 09:20:49 +0200[diff] [blame]55This should be defined only in the source file where the library is implemented.
onqtam8126b562016-05-27 17:01:15 +0300[diff] [blame]56
onqtam1435c012016-09-21 15:29:11 +0300[diff] [blame]57### **```DOCTEST_CONFIG_DISABLE```**
onqtam8126b562016-05-27 17:01:15 +0300[diff] [blame]58
onqtam1435c012016-09-21 15:29:11 +0300[diff] [blame]59One of the most most important configuration option - 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**.
onqtam8126b562016-05-27 17:01:15 +0300[diff] [blame]60
onqtam1435c012016-09-21 15:29:11 +0300[diff] [blame]61This should be defined globally.
onqtam8126b562016-05-27 17:01:15 +0300[diff] [blame]62
onqtamb8220c52017-05-16 00:21:15 +0300[diff] [blame]63### **```DOCTEST_CONFIG_IMPLEMENTATION_IN_DLL```**
64
65This 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.
66
67To 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.
68
69Checkout 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).
70
71This should be defined globally in binaries that import the symbols.
72
73This should be defined only in the source file where the library is implemented for binaries that export the test runner.
74
onqtam1435c012016-09-21 15:29:11 +0300[diff] [blame]75### **```DOCTEST_CONFIG_NO_SHORT_MACRO_NAMES```**
onqtam8126b562016-05-27 17:01:15 +0300[diff] [blame]76
onqtamad21bfc2021-12-10 23:40:00 +0200[diff] [blame]77This 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).
onqtam8126b562016-05-27 17:01:15 +0300[diff] [blame]78
onqtam1435c012016-09-21 15:29:11 +0300[diff] [blame]79This can be defined both globally and in specific source files only.
80
81### **```DOCTEST_CONFIG_TREAT_CHAR_STAR_AS_STRING```**
82
83By 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.
84
85This should be defined globally.
86
87### **```DOCTEST_CONFIG_SUPER_FAST_ASSERTS```**
88
onqtam8e989862019-01-15 20:50:44 +0200[diff] [blame]89This 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))
onqtam1435c012016-09-21 15:29:11 +0300[diff] [blame]90
onqtam72ca33b2018-12-05 17:34:33 +0200[diff] [blame]91Each 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.
92
93It 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).
onqtam1435c012016-09-21 15:29:11 +0300[diff] [blame]94
95This can be defined both globally and in specific source files only.
96
onqtam92dce5b2019-03-23 14:24:47 +0200[diff] [blame]97### **```DOCTEST_CONFIG_USE_STD_HEADERS```**
onqtam1435c012016-09-21 15:29:11 +0300[diff] [blame]98
onqtam92dce5b2019-03-23 14:24:47 +0200[diff] [blame]99The 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.
onqtam1435c012016-09-21 15:29:11 +0300[diff] [blame]100
101Also 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.
102
103This should be defined globally.
104
onqtam505b05c2019-05-06 11:39:02 +0300[diff] [blame]105### **```DOCTEST_CONFIG_VOID_CAST_EXPRESSIONS```**
106
107This 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.
108
109This can be defined both globally and in specific source files only.
110
onqtam1435c012016-09-21 15:29:11 +0300[diff] [blame]111### **```DOCTEST_CONFIG_NO_COMPARISON_WARNING_SUPPRESSION```**
112
113By default the library suppresses warnings about comparing signed and unsigned types, etc.
114
115- g++/clang ```-Wsign-conversion```
116- g++/clang ```-Wsign-compare```
onqtam1435c012016-09-21 15:29:11 +0300[diff] [blame]117- msvc ```C4389``` 'operator' : signed/unsigned mismatch
118- msvc ```C4018``` 'expression' : signed/unsigned mismatch
119
onqtam8ee35452021-12-15 15:42:40 +0200[diff] [blame^]120You can checkout [**this**](https://github.com/doctest/doctest/issues/16#issuecomment-246803303) issue to better understand why I suppress these warnings by default.
onqtam1435c012016-09-21 15:29:11 +0300[diff] [blame]121
122This can be defined both globally and in specific source files only.
123
Thomas Blehera420d8c2018-11-30 16:37:54 +0100[diff] [blame]124### **```DOCTEST_CONFIG_OPTIONS_PREFIX```**
125
126Defining 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.
127
128This should be defined only in the source file where the library is implemented (it's relevant only there).
129
onqtam1435c012016-09-21 15:29:11 +0300[diff] [blame]130### **```DOCTEST_CONFIG_NO_UNPREFIXED_OPTIONS```**
131
132This 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.
133
134This should be defined only in the source file where the library is implemented (it's relevant only there).
135
onqtame34600e2016-11-15 02:16:56 +0200[diff] [blame]136### **```DOCTEST_CONFIG_NO_TRY_CATCH_IN_ASSERTS```**
137
138This will remove all ```try``` / ```catch``` sections from:
139
140- the [normal asserts](assertions.html#expression-decomposing-asserts)
onqtam72ca33b2018-12-05 17:34:33 +0200[diff] [blame]141- the [binary and unary asserts](assertions.html#binary-and-unary-asserts)
onqtame34600e2016-11-15 02:16:56 +0200[diff] [blame]142
143so exceptions thrown while evaluating the expression in an assert will terminate the current test case.
144
onqtam72ca33b2018-12-05 17:34:33 +0200[diff] [blame]145This 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).
146
onqtame34600e2016-11-15 02:16:56 +0200[diff] [blame]147This can be defined both globally and in specific source files only.
148
149### **```DOCTEST_CONFIG_NO_EXCEPTIONS```**
150
onqtam92dce5b2019-03-23 14:24:47 +0200[diff] [blame]151This 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).
onqtame34600e2016-11-15 02:16:56 +0200[diff] [blame]152
153What gets changed:
154
155- asserts that evaluate the expression in a ```try``` / ```catch``` section no longer evaluate in such a context
156- ```REQUIRE``` macros are gone (undefined)
157- [exception macros](assertions.html#exceptions) are gone (undefined)
158- the ```abort-after``` option won't be fully working because an exception is used to terminate test cases
159
160The ```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.
161
onqtamb8220c52017-05-16 00:21:15 +0300[diff] [blame]162Also 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()```.
163
onqtame34600e2016-11-15 02:16:56 +0200[diff] [blame]164[**```DOCTEST_CONFIG_NO_EXCEPTIONS```**](#doctest_config_no_exceptions) implies [**```DOCTEST_CONFIG_NO_TRY_CATCH_IN_ASSERTS```**](#doctest_config_no_try_catch_in_asserts)
165
166If 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.
167
168This should be defined globally.
169
onqtame34600e2016-11-15 02:16:56 +0200[diff] [blame]170### **```DOCTEST_CONFIG_NO_EXCEPTIONS_BUT_WITH_ALL_ASSERTS```**
171
172When building with no exceptions (see [**```DOCTEST_CONFIG_NO_EXCEPTIONS```**](#doctest_config_no_exceptions)) ```REQUIRE``` asserts and the ones about dealing with exceptions are gone.
173
174If 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:
175
176- ```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
177- the [asserts for dealing with exceptions](assertions.html#exceptions) are turned into a no-op (instead of being totally undefined)
178
179This can be defined both globally and in specific source files only.
180
onqtam1435c012016-09-21 15:29:11 +0300[diff] [blame]181### **```DOCTEST_CONFIG_ASSERTION_PARAMETERS_BY_VALUE```**
182
183This 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):
184
185```
186template<typename T> struct type_traits { static const bool value = false; };
187
188// unless DOCTEST_CONFIG_ASSERTION_PARAMETERS_BY_VALUE is defined the following assertion
onqtamb8220c52017-05-16 00:21:15 +0300[diff] [blame]189// will lead to a linker error if type_traits<int>::value isn't defined in a translation unit
190CHECK(type_traits<int>::value == false);
onqtam1435c012016-09-21 15:29:11 +0300[diff] [blame]191```
192
193This can be defined both globally and in specific source files only.
194
195### **```DOCTEST_CONFIG_COLORS_NONE```**
196
197This will remove support for colors in the console output of the framework.
198
199This should be defined only in the source file where the library is implemented (it's relevant only there).
200
201### **```DOCTEST_CONFIG_COLORS_WINDOWS```**
202
203This will force the support for colors in the console output to use the Windows APIs and headers.
204
205This should be defined only in the source file where the library is implemented (it's relevant only there).
206
207### **```DOCTEST_CONFIG_COLORS_ANSI```**
208
209This will force the support for colors in the console output to use ANSI escape codes.
210
211This should be defined only in the source file where the library is implemented (it's relevant only there).
212
onqtamb8220c52017-05-16 00:21:15 +0300[diff] [blame]213### **```DOCTEST_CONFIG_WINDOWS_SEH```**
214
215This 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.
216
217This should be defined only in the source file where the library is implemented (it's relevant only there).
218
219### **```DOCTEST_CONFIG_NO_WINDOWS_SEH```**
220
221This can be used to disable **```DOCTEST_CONFIG_WINDOWS_SEH```** when it is auto-selected by the library.
222
223This should be defined only in the source file where the library is implemented (it's relevant only there).
224
225### **```DOCTEST_CONFIG_POSIX_SIGNALS```**
226
227This will enable the use of signals under UNIX for handling crashes. On by default.
228
229This should be defined only in the source file where the library is implemented (it's relevant only there).
230
231### **```DOCTEST_CONFIG_NO_POSIX_SIGNALS```**
232
233This can be used to disable **```DOCTEST_CONFIG_POSIX_SIGNALS```** when it is auto-selected by the library.
234
235This should be defined only in the source file where the library is implemented (it's relevant only there).
236
onqtam6a5da422017-09-04 17:56:08 +0300[diff] [blame]237### **```DOCTEST_CONFIG_INCLUDE_TYPE_TRAITS```**
238
onqtam8ee35452021-12-15 15:42:40 +0200[diff] [blame^]239This 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.
onqtam6a5da422017-09-04 17:56:08 +0300[diff] [blame]240
241This can be defined both globally and in specific source files only.
242
Martin Ankerlf6de4872020-12-31 11:22:00 +0100[diff] [blame]243### **```DOCTEST_CONFIG_NO_MULTI_LANE_ATOMICS```**
244
245This 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.
246
onqtam8126b562016-05-27 17:01:15 +0300[diff] [blame]247---------------
248
249[Home](readme.html#reference)
250
onqtamf8d57192018-08-23 16:02:12 +0300[diff] [blame]251<p align="center"><img src="../../scripts/data/logo/icon_2.svg"></p>
252
onqtam8126b562016-05-27 17:01:15 +0300[diff] [blame]253
254</xmp>
255<script src="strapdown.js/strapdown.js"></script>
256</html>