Gitiles
Code Review Sign In
gerrit.cesnet.cz / github / onqtam / doctest / e34600e5bc7fc4c627beed11b17d6f819e4fa49e / . / doc / html_generated / faq.html
blob: bd9283bcc670077ae9ce780a50654b1836c82d68 [file] [log] [blame]
onqtam8126b562016-05-27 17:01:15 +0300[diff] [blame]1<!DOCTYPE html>
2<html>
3<title>faq</title>
4<xmp theme="united" style="display:none;">
5
6## FAQ
7
onqtam1435c012016-09-21 15:29:11 +0300[diff] [blame]8- [**How is doctest different from Catch?**](#how-is-doctest-different-from-catch)
9- [**How to get the best compile-time performance with the framework?**](#how-to-get-the-best-compile-time-performance-with-the-framework)
10- [**Is doctest thread-aware?**](#is-doctest-thread-aware)
11- [**Why are my tests in a static library not getting registered?**](#why-are-my-tests-in-a-static-library-not-getting-registered)
12- [**Why is comparing C strings (```char*```) actually comparing pointers?**](#why-is-comparing-c-strings-char-actually-comparing-pointers)
13- [**How to write tests in header-only libraries?**](#how-to-write-tests-in-header-only-libraries)
14- [**Does the framework use exceptions?**](#does-the-framework-use-exceptions)
15- [**Why do I get compiler errors in STL headers when including the doctest header?**](#why-do-i-get-compiler-errors-in-stl-headers-when-including-the-doctest-header)
16- [**Can different versions of the framework be used within the same binary (executable/dll)?**](#can-different-versions-of-the-framework-be-used-within-the-same-binary-executabledll)
17- [**Why is doctest using macros?**](#why-is-doctest-using-macros)
18- [**How are subcases implemented?**](#how-are-subcases-implemented)
onqtam8126b562016-05-27 17:01:15 +0300[diff] [blame]19
onqtam1435c012016-09-21 15:29:11 +0300[diff] [blame]20### How is **doctest** different from Catch?
onqtam8126b562016-05-27 17:01:15 +0300[diff] [blame]21
onqtam1435c012016-09-21 15:29:11 +0300[diff] [blame]22Pros of **doctest**:
onqtam8126b562016-05-27 17:01:15 +0300[diff] [blame]23
onqtam1435c012016-09-21 15:29:11 +0300[diff] [blame]24- including the **doctest** header is [**over 50 times lighter**](benchmarks.html#cost-of-including-the-header) on compile times than that of [**Catch**](https://github.com/philsquared/Catch)
25- the asserts in **doctest** can be [**many times lighter**](benchmarks.html#cost-of-an-assertion-macro) on compile times than those of [**Catch**](https://github.com/philsquared/Catch)
26- everything testing-related can be removed from the binary by defining the [**```DOCTEST_CONFIG_DISABLE```**](configuration.html#doctest_config_disable) identifier
27- doesn't drag any headers when included (except for in the translation unit where the library gets implemented)
28- 0 warnings even on the [**most aggressive**](../../scripts/common.cmake#L71) warning levels for MSVC/GCC/Clang
29- per commit tested with 220+ builds on [**much more compilers**](features.html#extremely-portable) - and through valgrind/sanitizers
30- test cases can be written in headers - the framework will still register the tests only once - no duplicates
31- more actively maintained on GitHub
32- everything is documented (an undocumented feature is as good as a missing feature)
onqtam8126b562016-05-27 17:01:15 +0300[diff] [blame]33
onqtam1435c012016-09-21 15:29:11 +0300[diff] [blame]34Aside from everything mentioned so far doctest has some [**small features**](features.html#other-features) which [**Catch**](https://github.com/philsquared/Catch) doesn't but currently nothing big.
onqtam8126b562016-05-27 17:01:15 +0300[diff] [blame]35
onqtam1435c012016-09-21 15:29:11 +0300[diff] [blame]36Missing stuff:
onqtam8126b562016-05-27 17:01:15 +0300[diff] [blame]37
onqtam1435c012016-09-21 15:29:11 +0300[diff] [blame]38- exception translation - derivatives of ```std::exception``` don't get their ```.what()``` method called
39- no support for tags (the user can add *tags* in the test case names like this: ```TEST_CASE("[myTag] test name")```)
40- a reporter system - to a file, to xml, ability for the user to write their own reporter, etc.
41- measuring how much time a test case executes
42- adding contextual info to asserts with ```INFO```/```CONTEXT```
43- matchers and generators
onqtam8126b562016-05-27 17:01:15 +0300[diff] [blame]44
onqtam1435c012016-09-21 15:29:11 +0300[diff] [blame]45But all these things (and more!) are planned in the [**roadmap**](roadmap.html)!
onqtam8126b562016-05-27 17:01:15 +0300[diff] [blame]46
onqtam1435c012016-09-21 15:29:11 +0300[diff] [blame]47**doctest** can be thought of as a very polished, light, stable and clean subset (or reimplementation) of [**Catch**](https://github.com/philsquared/Catch) but this will change in the future as more features are added.
onqtam8126b562016-05-27 17:01:15 +0300[diff] [blame]48
onqtam1435c012016-09-21 15:29:11 +0300[diff] [blame]49### How to get the best compile-time performance with the framework?
onqtam8126b562016-05-27 17:01:15 +0300[diff] [blame]50
onqtam1435c012016-09-21 15:29:11 +0300[diff] [blame]51Using the [**fast**](assertions.html#fast-asserts) asserts in combination with [**```DOCTEST_CONFIG_SUPER_FAST_ASSERTS```**](configuration.html#doctest_config_super_fast_asserts) yelds the [**fastest**](benchmarks.html#cost-of-an-assertion-macro) compile times.
onqtam8126b562016-05-27 17:01:15 +0300[diff] [blame]52
onqtam1435c012016-09-21 15:29:11 +0300[diff] [blame]53There are only 2 drawbacks of this approach:
onqtamb6c69672016-09-21 15:41:52 +0300[diff] [blame]54
onqtam1435c012016-09-21 15:29:11 +0300[diff] [blame]55- using fast asserts (40-80% [**faster**](benchmarks.html#cost-of-an-assertion-macro) than ```CHECK(a==b)```) means that there is no ```try/catch``` block in each assert so if an expression throws the whole test case ends.
56- defining the [**```DOCTEST_CONFIG_SUPER_FAST_ASSERTS```**](configuration.html#doctest_config_super_fast_asserts) config identifier will result in even [**faster**](benchmarks.html#cost-of-an-assertion-macro) fast asserts (30-80%) at the cost of only one thing: when an assert fails and a debugger is present - the framework will break inside a doctest function so the user will have to go 1 level up in the callstack to see where the actual assert is in the source code.
onqtam8126b562016-05-27 17:01:15 +0300[diff] [blame]57
onqtam1435c012016-09-21 15:29:11 +0300[diff] [blame]58These 2 things can be considered negligible if you are dealing mainly with arithmetic (expressions are unlikely to throw exceptions) and all the tests usually pass (you don't need to often navigate to a failing assert with a debugger attached)
onqtam8126b562016-05-27 17:01:15 +0300[diff] [blame]59
onqtam1435c012016-09-21 15:29:11 +0300[diff] [blame]60If you want better aliases for the asserts instead of the long ones you could use [**```DOCTEST_CONFIG_NO_SHORT_MACRO_NAMES```**](configuration.html#doctest_config_no_short_macro_names) and then define your aliases like this: ```#define CHECK_EQ DOCTEST_FAST_CHECK_EQ``` (example in [**here**](../../examples/alternative_macros)).
61
62### Is doctest thread-aware?
63
64Currently no. Asserts cannot be used in multiple threads and test cases cannot be ran in parallel. These are long-term features that are planned on the [**roadmap**](roadmap.html).
65
66For now tests are ran serially and doing asserts in multiple user threads will lead to crashes.
67
68There is an option to run a [**range**](commandline.html) of tests from an executable - so tests can be ran in parallel with multiple process invocations - see [**the example**](../../examples/range_based_execution/) (the **run.py** script).
69
70### Why are my tests in a static library not getting registered?
71
onqtamb6c69672016-09-21 15:41:52 +0300[diff] [blame]72This is a [**common problem**](https://groups.google.com/forum/#!msg/catch-forum/FV0Qo62DvgY/jxEO6c9_q3kJ) and it affects all modern compilers on all platforms.
onqtam1435c012016-09-21 15:29:11 +0300[diff] [blame]73
onqtamec103be2016-10-09 13:46:25 +0300[diff] [blame]74The problem is that when a static library is being linked to a binary (executable or dll) - only object files from the static library that define a symbol being required from the binary will get pulled in (this is a linker/dependency optimization).
onqtam1435c012016-09-21 15:29:11 +0300[diff] [blame]75
76I have created a CMake function that forces every object file from a static library to be linked into a binary target - it is called [**```doctest_force_link_static_lib_in_target()```**](../../examples/exe_with_static_libs/doctest_force_link_static_lib_in_target.cmake). It is unintrusive - no source file gets changed - everything is done with compiler flags per source files. An example project using it can be found [**here**](../../examples/exe_with_static_libs).
77
78It doesn't work in 2 scenarios:
onqtamb6c69672016-09-21 15:41:52 +0300[diff] [blame]79
onqtam1435c012016-09-21 15:29:11 +0300[diff] [blame]80- either the target or the library uses a precompiled header - see [**this**](https://github.com/onqtam/doctest/issues/21#issuecomment-247001423) issue for details
81- either the target or the library is an imported target (pre-built) and not built within the current cmake tree
82
83For an alternative you can checkout the [**pthom/doctest_registerlibrary**](https://github.com/pthom/doctest_registerlibrary) repository.
84
85### Why is comparing C strings (```char*```) actually comparing pointers?
86
87**doctest** by default treats ```char*``` as normal pointers. Using the [**```DOCTEST_CONFIG_TREAT_CHAR_STAR_AS_STRING```**](configuration.html#doctest_config_treat_char_star_as_string) changes that.
88
89### How to write tests in header-only libraries?
90
91There are 2 options:
92
93- just include the doctest header in your headers and write the tests - the doctest header should be shipped with your headers and the user will have to implement the doctest runner in one of his source files.
94- don't include the doctest header and guard your test cases with ```#ifdef DOCTEST_LIBRARY_INCLUDED``` and ```#endif``` - that way your tests will be compiled and registered if the user includes the doctest header before your headers (and he will also have to implement the test runner somewhere).
95
96Also note that it would be a good idea to add a tag in your test case names (like this: ```TEST_CASE("[the_lib] testing foo")```) so the user can easily filter them out with ```--test-case-exclude=*the_lib*``` if he wishes to.
97
98### Does the framework use exceptions?
99
onqtame34600e2016-11-15 02:16:56 +0200[diff] [blame^]100Yes - but they can be disabled - see the [**```DOCTEST_CONFIG_NO_EXCEPTIONS```**](configuration.html#doctest_config_no_exceptions) config identifier.
onqtam1435c012016-09-21 15:29:11 +0300[diff] [blame]101
102### Why do I get compiler errors in STL headers when including the doctest header?
103
104Try using the [**```DOCTEST_CONFIG_USE_IOSFWD```**](configuration.html#doctest_config_use_iosfwd) configuration identifier.
105
106### Can different versions of the framework be used within the same binary (executable/dll)?
107
108Currently no. Single header libraries like [**stb**](https://github.com/nothings/stb) have this as an option (everything gets declared static - making it with internal linkage) but it isn't very logical for **doctest** - the main point is to write tests in any source file of the project and have the test runner implemented in only one source file.
109
110### Why is doctest using macros?
111
112Aren't they evil and not *modern*? - Check out the answer Phil Nash gives to this question [**here**](http://accu.org/index.php/journals/2064) (the creator of [**Catch**](https://github.com/philsquared/Catch)).
113
114### How are subcases implemented?
115
116Look at [**this example**](../../scripts/how_subcases_work/main.cpp) in the repository.
onqtam8126b562016-05-27 17:01:15 +0300[diff] [blame]117
118---------------
119
120[Home](readme.html#reference)
121
122
123</xmp>
124<script src="strapdown.js/strapdown.js"></script>
125</html>