blob: 3d3c86b853ed6f7743abbb88359dc8b1b6a2eb92 [file] [log] [blame]
onqtam8126b562016-05-27 17:01:15 +03001<!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 +03008**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 +030012Defining something ```globally``` means for every source file of the binary (executable / shared object).
13
onqtam1435c012016-09-21 15:29:11 +030014- [**```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 +030017- [**```DOCTEST_CONFIG_IMPLEMENTATION_IN_DLL```**](#doctest_config_implementation_in_dll)
onqtam1435c012016-09-21 15:29:11 +030018- [**```DOCTEST_CONFIG_NO_SHORT_MACRO_NAMES```**](#doctest_config_no_short_macro_names)
onqtamb8220c52017-05-16 00:21:15 +030019- [**```DOCTEST_CONFIG_NUM_CAPTURES_ON_STACK```**](#doctest_config_num_captures_on_stack)
onqtam1435c012016-09-21 15:29:11 +030020- [**```DOCTEST_CONFIG_TREAT_CHAR_STAR_AS_STRING```**](#doctest_config_treat_char_star_as_string)
21- [**```DOCTEST_CONFIG_SUPER_FAST_ASSERTS```**](#doctest_config_super_fast_asserts)
22- [**```DOCTEST_CONFIG_USE_IOSFWD```**](#doctest_config_use_iosfwd)
23- [**```DOCTEST_CONFIG_NO_COMPARISON_WARNING_SUPPRESSION```**](#doctest_config_no_comparison_warning_suppression)
24- [**```DOCTEST_CONFIG_NO_UNPREFIXED_OPTIONS```**](#doctest_config_no_unprefixed_options)
onqtame34600e2016-11-15 02:16:56 +020025- [**```DOCTEST_CONFIG_NO_TRY_CATCH_IN_ASSERTS```**](#doctest_config_no_try_catch_in_asserts)
26- [**```DOCTEST_CONFIG_NO_EXCEPTIONS```**](#doctest_config_no_exceptions)
27- [**```DOCTEST_CONFIG_NO_EXCEPTIONS_BUT_WITH_ALL_ASSERTS```**](#doctest_config_no_exceptions_but_with_all_asserts)
onqtam1435c012016-09-21 15:29:11 +030028- [**```DOCTEST_CONFIG_ASSERTION_PARAMETERS_BY_VALUE```**](#doctest_config_assertion_parameters_by_value)
29- [**```DOCTEST_CONFIG_COLORS_NONE```**](#doctest_config_colors_none)
30- [**```DOCTEST_CONFIG_COLORS_WINDOWS```**](#doctest_config_colors_windows)
31- [**```DOCTEST_CONFIG_COLORS_ANSI```**](#doctest_config_colors_ansi)
onqtamb8220c52017-05-16 00:21:15 +030032- [**```DOCTEST_CONFIG_WINDOWS_SEH```**](#doctest_config_windows_seh)
33- [**```DOCTEST_CONFIG_NO_WINDOWS_SEH```**](#doctest_config_no_windows_seh)
34- [**```DOCTEST_CONFIG_POSIX_SIGNALS```**](#doctest_config_posix_signals)
35- [**```DOCTEST_CONFIG_NO_POSIX_SIGNALS```**](#doctest_config_no_posix_signals)
onqtam6a5da422017-09-04 17:56:08 +030036- [**```DOCTEST_CONFIG_INCLUDE_TYPE_TRAITS```**](#doctest_config_include_type_traits)
onqtamb8220c52017-05-16 00:21:15 +030037
38Detection of modern C++ features:
39
40- [**```DOCTEST_CONFIG_WITH_DELETED_FUNCTIONS```**](#doctest_config_with_deleted_functions)
41- [**```DOCTEST_CONFIG_WITH_RVALUE_REFERENCES```**](#doctest_config_with_rvalue_references)
42- [**```DOCTEST_CONFIG_WITH_VARIADIC_MACROS```**](#doctest_config_with_variadic_macros)
onqtam1435c012016-09-21 15:29:11 +030043- [**```DOCTEST_CONFIG_WITH_NULLPTR```**](#doctest_config_with_nullptr)
44- [**```DOCTEST_CONFIG_WITH_LONG_LONG```**](#doctest_config_with_long_long)
45- [**```DOCTEST_CONFIG_WITH_STATIC_ASSERT```**](#doctest_config_with_static_assert)
onqtamb8220c52017-05-16 00:21:15 +030046- [**```DOCTEST_CONFIG_NO_DELETED_FUNCTIONS```**](#doctest_config_no_deleted_functions)
47- [**```DOCTEST_CONFIG_NO_RVALUE_REFERENCES```**](#doctest_config_no_rvalue_references)
48- [**```DOCTEST_CONFIG_NO_VARIADIC_MACROS```**](#doctest_config_no_variadic_macros)
onqtam1435c012016-09-21 15:29:11 +030049- [**```DOCTEST_CONFIG_NO_NULLPTR```**](#doctest_config_no_nullptr)
50- [**```DOCTEST_CONFIG_NO_LONG_LONG```**](#doctest_config_no_long_long)
51- [**```DOCTEST_CONFIG_NO_STATIC_ASSERT```**](#doctest_config_no_static_assert)
onqtam8126b562016-05-27 17:01:15 +030052
53For most people the only configuration needed is telling **doctest** which source file should host all the implementation code:
54
onqtam1435c012016-09-21 15:29:11 +030055### **```DOCTEST_CONFIG_IMPLEMENT_WITH_MAIN```**
onqtam8126b562016-05-27 17:01:15 +030056
onqtam1435c012016-09-21 15:29:11 +030057```
onqtam8126b562016-05-27 17:01:15 +030058#define DOCTEST_CONFIG_IMPLEMENT_WITH_MAIN
59#include "doctest.h"
onqtam1435c012016-09-21 15:29:11 +030060```
onqtam8126b562016-05-27 17:01:15 +030061
onqtam1435c012016-09-21 15:29:11 +030062This should be defined only in the source file where the library is implemented.
onqtam8126b562016-05-27 17:01:15 +030063
onqtam1435c012016-09-21 15:29:11 +030064### **```DOCTEST_CONFIG_IMPLEMENT```**
onqtam8126b562016-05-27 17:01:15 +030065
onqtam1435c012016-09-21 15:29:11 +030066If 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 his existing project codebase) this identifier should be used.
onqtam8126b562016-05-27 17:01:15 +030067
onqtam1435c012016-09-21 15:29:11 +030068This 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 +030069
onqtam1435c012016-09-21 15:29:11 +030070### **```DOCTEST_CONFIG_DISABLE```**
onqtam8126b562016-05-27 17:01:15 +030071
onqtam1435c012016-09-21 15:29:11 +030072One 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 +030073
onqtam1435c012016-09-21 15:29:11 +030074This should be defined globally.
onqtam8126b562016-05-27 17:01:15 +030075
onqtamb8220c52017-05-16 00:21:15 +030076### **```DOCTEST_CONFIG_IMPLEMENTATION_IN_DLL```**
77
78This 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.
79
80To 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.
81
82Checkout 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).
83
84This should be defined globally in binaries that import the symbols.
85
86This should be defined only in the source file where the library is implemented for binaries that export the test runner.
87
onqtam1435c012016-09-21 15:29:11 +030088### **```DOCTEST_CONFIG_NO_SHORT_MACRO_NAMES```**
onqtam8126b562016-05-27 17:01:15 +030089
onqtamb8220c52017-05-16 00:21:15 +030090This 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 his own short versions of these macros - [**example**](../../examples/all_features/alternative_macros.cpp).
onqtam8126b562016-05-27 17:01:15 +030091
onqtam1435c012016-09-21 15:29:11 +030092This can be defined both globally and in specific source files only.
93
onqtamb8220c52017-05-16 00:21:15 +030094### **```DOCTEST_CONFIG_NUM_CAPTURES_ON_STACK```**
95
96With this identifier the user may configure the number of captures on the stack by the ```INFO()``` [**logging macros**](logging.html) (read there for more info). The default is ```5``` - which means that for a call like this: ```INFO(var1 << "la la" << var2);``` all 3 logged variables will be captured on the stack (with the ability to hold 2 more - so no heap allocation unless an assert fails later in the same scope) - and a total of ```5 * (sizeof(void*) * 2))``` bytes are used on the stack for captures. A subsequent call to ```INFO()``` will have it's own stack space. Note that ```0``` is an invalid value. Examples:
97
98```
99#define DOCTEST_CONFIG_NUM_CAPTURES_ON_STACK 10
100#include <doctest.h>
101```
102
103or through the command line: ```-DDOCTEST_CONFIG_NUM_CAPTURES_ON_STACK=10```
104
105This should be defined globally.
106
onqtam1435c012016-09-21 15:29:11 +0300107### **```DOCTEST_CONFIG_TREAT_CHAR_STAR_AS_STRING```**
108
109By 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.
110
111This should be defined globally.
112
113### **```DOCTEST_CONFIG_SUPER_FAST_ASSERTS```**
114
onqtam4aff18c2017-05-17 04:10:03 +0300115This makes the fast assert macros (```FAST_CHECK_EQ(a,b)``` - with a ```FAST_``` prefix) compile [**even faster**](benchmarks.html#cost-of-an-assertion-macro)! (50-80%)
onqtam1435c012016-09-21 15:29:11 +0300116
117Each fast 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.
118
119This can be defined both globally and in specific source files only.
120
121### **```DOCTEST_CONFIG_USE_IOSFWD```**
122
123The library by default provides a forward declaration of ```std::ostream``` in order to support the ```operator<<``` [**stringification**](stringification.html) mechanism. 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 ```<iosfwd>```.
124
125Also 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.
126
127This should be defined globally.
128
129### **```DOCTEST_CONFIG_NO_COMPARISON_WARNING_SUPPRESSION```**
130
131By default the library suppresses warnings about comparing signed and unsigned types, etc.
132
133- g++/clang ```-Wsign-conversion```
134- g++/clang ```-Wsign-compare```
onqtam1435c012016-09-21 15:29:11 +0300135- msvc ```C4389``` 'operator' : signed/unsigned mismatch
136- msvc ```C4018``` 'expression' : signed/unsigned mismatch
137
138You can checkout [**this**](https://github.com/onqtam/doctest/issues/16#issuecomment-246803303) issue to better understand why I suppress these warnings by default.
139
140This can be defined both globally and in specific source files only.
141
142### **```DOCTEST_CONFIG_NO_UNPREFIXED_OPTIONS```**
143
144This 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.
145
146This should be defined only in the source file where the library is implemented (it's relevant only there).
147
onqtame34600e2016-11-15 02:16:56 +0200148### **```DOCTEST_CONFIG_NO_TRY_CATCH_IN_ASSERTS```**
149
150This will remove all ```try``` / ```catch``` sections from:
151
152- the [normal asserts](assertions.html#expression-decomposing-asserts)
onqtamb8220c52017-05-16 00:21:15 +0300153- the [binary and unary asserts](assertions.html#binary-and-unary-asserts) - making them functionally the same as the [**fast asserts**](assertions.html#fast-asserts) (but not for compile time speed)
onqtame34600e2016-11-15 02:16:56 +0200154
155so exceptions thrown while evaluating the expression in an assert will terminate the current test case.
156
157This can be defined both globally and in specific source files only.
158
159### **```DOCTEST_CONFIG_NO_EXCEPTIONS```**
160
161This will remove everything that uses exceptions from the framework - it is also auto detectable for some compilers (GCC, Clang) if exceptions are disabled with ```-fno-exceptions```. For MSVC ```_HAS_EXCEPTIONS``` cannot be used for auto detecting because it is defined in system headers instead of as a project define - and doctest will not include a header just for that.
162
163What gets changed:
164
165- asserts that evaluate the expression in a ```try``` / ```catch``` section no longer evaluate in such a context
166- ```REQUIRE``` macros are gone (undefined)
167- [exception macros](assertions.html#exceptions) are gone (undefined)
168- the ```abort-after``` option won't be fully working because an exception is used to terminate test cases
169
170The ```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.
171
onqtamb8220c52017-05-16 00:21:15 +0300172Also 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()```.
173
onqtame34600e2016-11-15 02:16:56 +0200174[**```DOCTEST_CONFIG_NO_EXCEPTIONS```**](#doctest_config_no_exceptions) implies [**```DOCTEST_CONFIG_NO_TRY_CATCH_IN_ASSERTS```**](#doctest_config_no_try_catch_in_asserts)
175
176If 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.
177
178This should be defined globally.
179
onqtame34600e2016-11-15 02:16:56 +0200180### **```DOCTEST_CONFIG_NO_EXCEPTIONS_BUT_WITH_ALL_ASSERTS```**
181
182When building with no exceptions (see [**```DOCTEST_CONFIG_NO_EXCEPTIONS```**](#doctest_config_no_exceptions)) ```REQUIRE``` asserts and the ones about dealing with exceptions are gone.
183
184If 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:
185
186- ```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
187- the [asserts for dealing with exceptions](assertions.html#exceptions) are turned into a no-op (instead of being totally undefined)
188
189This can be defined both globally and in specific source files only.
190
onqtam1435c012016-09-21 15:29:11 +0300191### **```DOCTEST_CONFIG_ASSERTION_PARAMETERS_BY_VALUE```**
192
193This 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):
194
195```
196template<typename T> struct type_traits { static const bool value = false; };
197
198// unless DOCTEST_CONFIG_ASSERTION_PARAMETERS_BY_VALUE is defined the following assertion
onqtamb8220c52017-05-16 00:21:15 +0300199// will lead to a linker error if type_traits<int>::value isn't defined in a translation unit
200CHECK(type_traits<int>::value == false);
onqtam1435c012016-09-21 15:29:11 +0300201```
202
203This can be defined both globally and in specific source files only.
204
205### **```DOCTEST_CONFIG_COLORS_NONE```**
206
207This will remove support for colors in the console output of the framework.
208
209This should be defined only in the source file where the library is implemented (it's relevant only there).
210
211### **```DOCTEST_CONFIG_COLORS_WINDOWS```**
212
213This will force the support for colors in the console output to use the Windows APIs and headers.
214
215This should be defined only in the source file where the library is implemented (it's relevant only there).
216
217### **```DOCTEST_CONFIG_COLORS_ANSI```**
218
219This will force the support for colors in the console output to use ANSI escape codes.
220
221This should be defined only in the source file where the library is implemented (it's relevant only there).
222
onqtamb8220c52017-05-16 00:21:15 +0300223### **```DOCTEST_CONFIG_WINDOWS_SEH```**
224
225This 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.
226
227This should be defined only in the source file where the library is implemented (it's relevant only there).
228
229### **```DOCTEST_CONFIG_NO_WINDOWS_SEH```**
230
231This can be used to disable **```DOCTEST_CONFIG_WINDOWS_SEH```** when it is auto-selected by the library.
232
233This should be defined only in the source file where the library is implemented (it's relevant only there).
234
235### **```DOCTEST_CONFIG_POSIX_SIGNALS```**
236
237This will enable the use of signals under UNIX for handling crashes. On by default.
238
239This should be defined only in the source file where the library is implemented (it's relevant only there).
240
241### **```DOCTEST_CONFIG_NO_POSIX_SIGNALS```**
242
243This can be used to disable **```DOCTEST_CONFIG_POSIX_SIGNALS```** when it is auto-selected by the library.
244
245This should be defined only in the source file where the library is implemented (it's relevant only there).
246
onqtam6a5da422017-09-04 17:56:08 +0300247### **```DOCTEST_CONFIG_INCLUDE_TYPE_TRAITS```**
248
249This 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/onqtam/doctest/issues/62) or [this](https://github.com/onqtam/doctest/issues/85) issue for more details on that.
250
251This can be defined both globally and in specific source files only.
252
onqtamb8220c52017-05-16 00:21:15 +0300253### **```DOCTEST_CONFIG_WITH_DELETED_FUNCTIONS```**
254
255doctest tries to detect if c++11 deleted functions are available but if it doesn't detect it - the user might define this.
256
257This should be defined globally.
258
259### **```DOCTEST_CONFIG_WITH_RVALUE_REFERENCES```**
260
261doctest tries to detect if c++11 rvalue references are available but if it doesn't detect it - the user might define this.
262
263This should be defined globally.
264
265### **```DOCTEST_CONFIG_WITH_VARIADIC_MACROS```**
266
267doctest tries to detect if c++11 variadic macros are available but if it doesn't detect it - the user might define this.
268
269This can be defined both globally and in specific source files only.
270
onqtam1435c012016-09-21 15:29:11 +0300271### **```DOCTEST_CONFIG_WITH_NULLPTR```**
272
273doctest tries to detect if c++11 ```nullptr``` is available but if it doesn't detect it - the user might define this.
274
275This should be defined globally.
276
277### **```DOCTEST_CONFIG_WITH_LONG_LONG```**
278
279doctest tries to detect if c++11 ```long long``` is available but if it doesn't detect it - the user might define this.
280
281This should be defined globally.
282
283### **```DOCTEST_CONFIG_WITH_STATIC_ASSERT```**
284
285doctest tries to detect if c++11 ```static_assert()``` is available but if it doesn't detect it - the user might define this.
286
287This should be defined globally.
288
onqtamb8220c52017-05-16 00:21:15 +0300289### **```DOCTEST_CONFIG_NO_DELETED_FUNCTIONS```**
290
291If doctest detects c++11 deleted functions support as available but the user knows better - this can be defined to disable it.
292
293This should be defined globally.
294
295### **```DOCTEST_CONFIG_NO_RVALUE_REFERENCES```**
296
297If doctest detects c++11 rvalue references support as available but the user knows better - this can be defined to disable it.
298
299This should be defined globally.
300
301### **```DOCTEST_CONFIG_NO_VARIADIC_MACROS```**
302
303If doctest detects c++11 variadic macros support as available but the user knows better - this can be defined to disable it.
304
305This can be defined both globally and in specific source files only.
306
onqtam1435c012016-09-21 15:29:11 +0300307### **```DOCTEST_CONFIG_NO_NULLPTR```**
308
309If doctest detects c++11 ```nullptr``` support as available but the user knows better - this can be defined to disable it.
310
311This should be defined globally.
312
313### **```DOCTEST_CONFIG_NO_LONG_LONG```**
314
315If doctest detects c++11 ```long long``` support as available but the user knows better - this can be defined to disable it.
316
317This should be defined globally.
318
319### **```DOCTEST_CONFIG_NO_STATIC_ASSERT```**
320
321If doctest detects c++11 ```static_assert()``` support as available but the user knows better - this can be defined to disable it.
322
323This should be defined globally.
onqtam8126b562016-05-27 17:01:15 +0300324
325---------------
326
327[Home](readme.html#reference)
328
329
330</xmp>
331<script src="strapdown.js/strapdown.js"></script>
332</html>