Gitiles
Code Review Sign In
gerrit.cesnet.cz / github / onqtam / doctest / e34600e5bc7fc4c627beed11b17d6f819e4fa49e / . / doc / html_generated / configuration.html
blob: 2bf7532e61e43031e0de5e70fb68fecc412c90e0 [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
12- [**```DOCTEST_CONFIG_IMPLEMENT_WITH_MAIN```**](#doctest_config_implement_with_main)
13- [**```DOCTEST_CONFIG_IMPLEMENT```**](#doctest_config_implement)
14- [**```DOCTEST_CONFIG_DISABLE```**](#doctest_config_disable)
15- [**```DOCTEST_CONFIG_NO_SHORT_MACRO_NAMES```**](#doctest_config_no_short_macro_names)
16- [**```DOCTEST_CONFIG_TREAT_CHAR_STAR_AS_STRING```**](#doctest_config_treat_char_star_as_string)
17- [**```DOCTEST_CONFIG_SUPER_FAST_ASSERTS```**](#doctest_config_super_fast_asserts)
18- [**```DOCTEST_CONFIG_USE_IOSFWD```**](#doctest_config_use_iosfwd)
19- [**```DOCTEST_CONFIG_NO_COMPARISON_WARNING_SUPPRESSION```**](#doctest_config_no_comparison_warning_suppression)
20- [**```DOCTEST_CONFIG_NO_UNPREFIXED_OPTIONS```**](#doctest_config_no_unprefixed_options)
onqtame34600e2016-11-15 02:16:56 +0200[diff] [blame^]21- [**```DOCTEST_CONFIG_NO_TRY_CATCH_IN_ASSERTS```**](#doctest_config_no_try_catch_in_asserts)
22- [**```DOCTEST_CONFIG_NO_EXCEPTIONS```**](#doctest_config_no_exceptions)
23- [**```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]24- [**```DOCTEST_CONFIG_ASSERTION_PARAMETERS_BY_VALUE```**](#doctest_config_assertion_parameters_by_value)
25- [**```DOCTEST_CONFIG_COLORS_NONE```**](#doctest_config_colors_none)
26- [**```DOCTEST_CONFIG_COLORS_WINDOWS```**](#doctest_config_colors_windows)
27- [**```DOCTEST_CONFIG_COLORS_ANSI```**](#doctest_config_colors_ansi)
28- [**```DOCTEST_CONFIG_WITH_NULLPTR```**](#doctest_config_with_nullptr)
29- [**```DOCTEST_CONFIG_WITH_LONG_LONG```**](#doctest_config_with_long_long)
30- [**```DOCTEST_CONFIG_WITH_STATIC_ASSERT```**](#doctest_config_with_static_assert)
31- [**```DOCTEST_CONFIG_NO_NULLPTR```**](#doctest_config_no_nullptr)
32- [**```DOCTEST_CONFIG_NO_LONG_LONG```**](#doctest_config_no_long_long)
33- [**```DOCTEST_CONFIG_NO_STATIC_ASSERT```**](#doctest_config_no_static_assert)
onqtam8126b562016-05-27 17:01:15 +0300[diff] [blame]34
35For most people the only configuration needed is telling **doctest** which source file should host all the implementation code:
36
onqtam1435c012016-09-21 15:29:11 +0300[diff] [blame]37### **```DOCTEST_CONFIG_IMPLEMENT_WITH_MAIN```**
onqtam8126b562016-05-27 17:01:15 +0300[diff] [blame]38
onqtam1435c012016-09-21 15:29:11 +0300[diff] [blame]39```
onqtam8126b562016-05-27 17:01:15 +0300[diff] [blame]40#define DOCTEST_CONFIG_IMPLEMENT_WITH_MAIN
41#include "doctest.h"
onqtam1435c012016-09-21 15:29:11 +0300[diff] [blame]42```
onqtam8126b562016-05-27 17:01:15 +0300[diff] [blame]43
onqtam1435c012016-09-21 15:29:11 +0300[diff] [blame]44This should be defined only in the source file where the library is implemented.
onqtam8126b562016-05-27 17:01:15 +0300[diff] [blame]45
onqtam1435c012016-09-21 15:29:11 +0300[diff] [blame]46### **```DOCTEST_CONFIG_IMPLEMENT```**
onqtam8126b562016-05-27 17:01:15 +0300[diff] [blame]47
onqtam1435c012016-09-21 15:29:11 +0300[diff] [blame]48If 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]49
onqtam1435c012016-09-21 15:29:11 +0300[diff] [blame]50This 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]51
onqtam1435c012016-09-21 15:29:11 +0300[diff] [blame]52### **```DOCTEST_CONFIG_DISABLE```**
onqtam8126b562016-05-27 17:01:15 +0300[diff] [blame]53
onqtam1435c012016-09-21 15:29:11 +0300[diff] [blame]54One 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]55
onqtam1435c012016-09-21 15:29:11 +0300[diff] [blame]56This should be defined globally.
onqtam8126b562016-05-27 17:01:15 +0300[diff] [blame]57
onqtam1435c012016-09-21 15:29:11 +0300[diff] [blame]58### **```DOCTEST_CONFIG_NO_SHORT_MACRO_NAMES```**
onqtam8126b562016-05-27 17:01:15 +0300[diff] [blame]59
onqtam1435c012016-09-21 15:29:11 +0300[diff] [blame]60This 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/alternative_macros/).
onqtam8126b562016-05-27 17:01:15 +0300[diff] [blame]61
onqtam1435c012016-09-21 15:29:11 +0300[diff] [blame]62This can be defined both globally and in specific source files only.
63
64### **```DOCTEST_CONFIG_TREAT_CHAR_STAR_AS_STRING```**
65
66By 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.
67
68This should be defined globally.
69
70### **```DOCTEST_CONFIG_SUPER_FAST_ASSERTS```**
71
72This makes the fast assert macros (```FAST_CHECK_EQ(a,b)``` - with a ```FAST_``` prefix) compile [**even faster**](benchmarks.html#cost-of-an-assertion-macro)! (35-80%)
73
74Each 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.
75
76This can be defined both globally and in specific source files only.
77
78### **```DOCTEST_CONFIG_USE_IOSFWD```**
79
80The 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>```.
81
82Also 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.
83
84This should be defined globally.
85
86### **```DOCTEST_CONFIG_NO_COMPARISON_WARNING_SUPPRESSION```**
87
88By default the library suppresses warnings about comparing signed and unsigned types, etc.
89
90- g++/clang ```-Wsign-conversion```
91- g++/clang ```-Wsign-compare```
92- g++/clang ```-Wdouble-promotion```
93- msvc ```C4389``` 'operator' : signed/unsigned mismatch
94- msvc ```C4018``` 'expression' : signed/unsigned mismatch
95
96You can checkout [**this**](https://github.com/onqtam/doctest/issues/16#issuecomment-246803303) issue to better understand why I suppress these warnings by default.
97
98This can be defined both globally and in specific source files only.
99
100### **```DOCTEST_CONFIG_NO_UNPREFIXED_OPTIONS```**
101
102This 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.
103
104This should be defined only in the source file where the library is implemented (it's relevant only there).
105
onqtame34600e2016-11-15 02:16:56 +0200[diff] [blame^]106### **```DOCTEST_CONFIG_NO_TRY_CATCH_IN_ASSERTS```**
107
108This will remove all ```try``` / ```catch``` sections from:
109
110- the [normal asserts](assertions.html#expression-decomposing-asserts)
111- the [binary and unary asserts](assertions.html#binary-and-unary-asserts)
112
113so exceptions thrown while evaluating the expression in an assert will terminate the current test case.
114
115This can be defined both globally and in specific source files only.
116
117### **```DOCTEST_CONFIG_NO_EXCEPTIONS```**
118
119This 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.
120
121What gets changed:
122
123- asserts that evaluate the expression in a ```try``` / ```catch``` section no longer evaluate in such a context
124- ```REQUIRE``` macros are gone (undefined)
125- [exception macros](assertions.html#exceptions) are gone (undefined)
126- the ```abort-after``` option won't be fully working because an exception is used to terminate test cases
127
128The ```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.
129
130[**```DOCTEST_CONFIG_NO_EXCEPTIONS```**](#doctest_config_no_exceptions) implies [**```DOCTEST_CONFIG_NO_TRY_CATCH_IN_ASSERTS```**](#doctest_config_no_try_catch_in_asserts)
131
132If 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.
133
134This should be defined globally.
135
136
137### **```DOCTEST_CONFIG_NO_EXCEPTIONS_BUT_WITH_ALL_ASSERTS```**
138
139When building with no exceptions (see [**```DOCTEST_CONFIG_NO_EXCEPTIONS```**](#doctest_config_no_exceptions)) ```REQUIRE``` asserts and the ones about dealing with exceptions are gone.
140
141If 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:
142
143- ```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
144- the [asserts for dealing with exceptions](assertions.html#exceptions) are turned into a no-op (instead of being totally undefined)
145
146This can be defined both globally and in specific source files only.
147
onqtam1435c012016-09-21 15:29:11 +0300[diff] [blame]148### **```DOCTEST_CONFIG_ASSERTION_PARAMETERS_BY_VALUE```**
149
150This 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):
151
152```
153template<typename T> struct type_traits { static const bool value = false; };
154
155// unless DOCTEST_CONFIG_ASSERTION_PARAMETERS_BY_VALUE is defined the following assertion
156// will lead to a linker error if type_traits<T>::value isn't defined in a translation unit
157CHECK(type_traits::value == false);
158```
159
160This can be defined both globally and in specific source files only.
161
162### **```DOCTEST_CONFIG_COLORS_NONE```**
163
164This will remove support for colors in the console output of the framework.
165
166This should be defined only in the source file where the library is implemented (it's relevant only there).
167
168### **```DOCTEST_CONFIG_COLORS_WINDOWS```**
169
170This will force the support for colors in the console output to use the Windows APIs and headers.
171
172This should be defined only in the source file where the library is implemented (it's relevant only there).
173
174### **```DOCTEST_CONFIG_COLORS_ANSI```**
175
176This will force the support for colors in the console output to use ANSI escape codes.
177
178This should be defined only in the source file where the library is implemented (it's relevant only there).
179
180### **```DOCTEST_CONFIG_WITH_NULLPTR```**
181
182doctest tries to detect if c++11 ```nullptr``` is available but if it doesn't detect it - the user might define this.
183
184This should be defined globally.
185
186### **```DOCTEST_CONFIG_WITH_LONG_LONG```**
187
188doctest tries to detect if c++11 ```long long``` is available but if it doesn't detect it - the user might define this.
189
190This should be defined globally.
191
192### **```DOCTEST_CONFIG_WITH_STATIC_ASSERT```**
193
194doctest tries to detect if c++11 ```static_assert()``` is available but if it doesn't detect it - the user might define this.
195
196This should be defined globally.
197
198### **```DOCTEST_CONFIG_NO_NULLPTR```**
199
200If doctest detects c++11 ```nullptr``` support as available but the user knows better - this can be defined to disable it.
201
202This should be defined globally.
203
204### **```DOCTEST_CONFIG_NO_LONG_LONG```**
205
206If doctest detects c++11 ```long long``` support as available but the user knows better - this can be defined to disable it.
207
208This should be defined globally.
209
210### **```DOCTEST_CONFIG_NO_STATIC_ASSERT```**
211
212If doctest detects c++11 ```static_assert()``` support as available but the user knows better - this can be defined to disable it.
213
214This should be defined globally.
onqtam8126b562016-05-27 17:01:15 +0300[diff] [blame]215
216---------------
217
218[Home](readme.html#reference)
219
220
221</xmp>
222<script src="strapdown.js/strapdown.js"></script>
223</html>