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