| onqtam | 8126b56 | 2016-05-27 17:01:15 +0300 | [diff] [blame] | 1 | <!DOCTYPE html> |
| 2 | <html> |
| 3 | <title>features</title> |
| 4 | <xmp theme="united" style="display:none;"> |
| 5 | |
| 6 | ## Features and design goals |
| 7 | |
| onqtam | 4aff18c | 2017-05-17 04:10:03 +0300 | [diff] [blame] | 8 | **doctest** has been designed from the start to be as **light** and **unintrusive** as possible. These key features should be kept. |
| onqtam | 1435c01 | 2016-09-21 15:29:11 +0300 | [diff] [blame] | 9 | |
| onqtam | 8126b56 | 2016-05-27 17:01:15 +0300 | [diff] [blame] | 10 | ## Unintrusive (transparent): |
| 11 | |
| onqtam | 1435c01 | 2016-09-21 15:29:11 +0300 | [diff] [blame] | 12 | - everything testing-related can be removed from the binary executable by defining the [**```DOCTEST_CONFIG_DISABLE```**](configuration.html#doctest_config_disable) identifier |
| onqtam | e34600e | 2016-11-15 02:16:56 +0200 | [diff] [blame] | 13 | - very small and easy to integrate - single header |
| onqtam | b8220c5 | 2017-05-16 00:21:15 +0300 | [diff] [blame] | 14 | - **Extremely** low footprint on compile times - [**around 25ms**](benchmarks.html#cost-of-including-the-header) of compile time overhead for including the header in a file |
| onqtam | e34600e | 2016-11-15 02:16:56 +0200 | [diff] [blame] | 15 | - The [**fastest possible**](benchmarks.html#cost-of-an-assertion-macro) assertion macros - 50k asserts can compile for under 30 seconds (even under 10 sec) |
| onqtam | 8126b56 | 2016-05-27 17:01:15 +0300 | [diff] [blame] | 16 | - doesn't drag any headers when included (except for in the translation unit where the library gets implemented) |
| 17 | - everything is in the ```doctest``` namespace (and the implementation details are in a nested ```detail``` namespace) |
| 18 | - all macros have prefixes - some by default have unprefixed versions as well but that is optional - see [**configuration**](configuration.html) |
| 19 | - 0 warnings even with the most aggresive flags (on all tested compilers!!!) |
| 20 | - ```-Weverything -pedantic``` for **clang** |
| onqtam | 4aff18c | 2017-05-17 04:10:03 +0300 | [diff] [blame] | 21 | - ```-Wall -Wextra -pedantic``` and **>> over 35 <<** other warnings **not** covered by these flags for **GCC**!!! - see [**here**](../../scripts/cmake/common.cmake#L84) |
| onqtam | 8126b56 | 2016-05-27 17:01:15 +0300 | [diff] [blame] | 22 | - ```/W4``` for **MSVC** (```/Wall``` is too much there - even their own headers produce **thousands** of warnings with that option) |
| 23 | - doesn't error on unrecognized [**command line**](commandline.html) options and supports prefixes for interop with client command line parsing |
| 24 | - can set options [**procedurally**](main.html) and not deal with passing ```argc```/```argv``` from the command line |
| 25 | - doesn't leave warnings disabled after itself |
| 26 | |
| 27 | ## Extremely portable: |
| 28 | |
| 29 | - Standards compliant **C++98** code - should work with any **C++98** compiler |
| onqtam | 4aff18c | 2017-05-17 04:10:03 +0300 | [diff] [blame] | 30 | - tested with **GCC**: **4.4**, **4.5**, **4.6**, **4.7**, **4.8**, **4.9**, **5**, **6**, **7** |
| onqtam | 6ff3d35 | 2017-09-11 14:35:06 +0300 | [diff] [blame] | 31 | - tested with **Clang**: **3.5**, **3.6**, **3.7**, **3.8**, **3.9**, **4**, **5** |
| onqtam | b8220c5 | 2017-05-16 00:21:15 +0300 | [diff] [blame] | 32 | - tested with **MSVC**: **2008**, **2010**, **2012**, **2013**, **2015**, **2017** |
| onqtam | 8126b56 | 2016-05-27 17:01:15 +0300 | [diff] [blame] | 33 | - per-commit tested on **travis** and **appveyor** CI services |
| onqtam | 375568c | 2017-05-17 04:19:58 +0300 | [diff] [blame] | 34 | - warnings as errors even on the most aggressive warning levels - see [**here**](../../scripts/cmake/common.cmake#L84) |
| onqtam | 0c65bef | 2017-09-11 15:34:43 +0300 | [diff] [blame^] | 35 | - statically analyzed on the CI - [**Cppcheck**](http://cppcheck.sourceforge.net/) / [**Clang-Tidy**](http://oclint.org/) / [**Coverity Scan**](https://scan.coverity.com/) / [**OCLint**](https://scan.coverity.com/) / [**Visual Studio Analyzer**](https://docs.microsoft.com/en-us/visualstudio/code-quality/analyzing-c-cpp-code-quality-by-using-code-analysis) |
| onqtam | 8126b56 | 2016-05-27 17:01:15 +0300 | [diff] [blame] | 36 | - all tests have their output compared to reference output of a previous known good run |
| 37 | - all tests built and ran in **Debug**/**Release** and also in **32**/**64** bit modes |
| 38 | - all tests ran through **valgrind** under **Linux**/**OSX** |
| 39 | - all tests ran through **address** and **UB** sanitizers under **Linux**/**OSX** |
| onqtam | 6ff3d35 | 2017-09-11 14:35:06 +0300 | [diff] [blame] | 40 | - tests are ran in more than **330** different configurations on UNIX (Linux + OSX) on **travis** CI |
| onqtam | b8220c5 | 2017-05-16 00:21:15 +0300 | [diff] [blame] | 41 | - tests are ran in a total of **24** different configurations on Windows on **appveyor** CI |
| onqtam | 8126b56 | 2016-05-27 17:01:15 +0300 | [diff] [blame] | 42 | |
| 43 | ## Other features: |
| 44 | |
| 45 | - really easy to get started - it's just 1 header file - see the [**tutorial**](tutorial.html) |
| 46 | - **very** light, unintrusive and portable - see the sections above - and also the [**benchmarks**](benchmarks.html) |
| onqtam | 1435c01 | 2016-09-21 15:29:11 +0300 | [diff] [blame] | 47 | - offers a way to remove **everything** testing-related from the binary with the [**```DOCTEST_CONFIG_DISABLE```**](configuration.html#doctest_config_disable) macro |
| onqtam | 8126b56 | 2016-05-27 17:01:15 +0300 | [diff] [blame] | 48 | - tests are registered automatically - no need to add them to a collection manually |
| onqtam | b8220c5 | 2017-05-16 00:21:15 +0300 | [diff] [blame] | 49 | - [**Subcases**](tutorial.html#test-cases-and-subcases) - an intuitive way to share common setup and teardown code for test cases (alternative to [**test fixtures**](testcases.html#test-fixtures) which are also supported) |
| 50 | - [**templated test cases**](parameterized-tests.html#templated-test-cases---parameterized-by-type) - parameterized by type |
| 51 | - supports [**logging macros**](logging.html) for capturing local variables and strings - as a message for when an assert fails - with lazy stringification and no allocations when possible! |
| 52 | - crash handling support - uses signals for UNIX and SEH for Windows |
| onqtam | 8126b56 | 2016-05-27 17:01:15 +0300 | [diff] [blame] | 53 | - output from all compilers on all platforms is the same - byte by byte |
| onqtam | b8220c5 | 2017-05-16 00:21:15 +0300 | [diff] [blame] | 54 | - binaries (exe/dll) can use the test runner of another binary - so tests end up in a single registry - [**example**](../../examples/executable_dll_and_plugin/) |
| onqtam | 8126b56 | 2016-05-27 17:01:15 +0300 | [diff] [blame] | 55 | - supports [**BDD style**](testcases.html) tests |
| onqtam | b8220c5 | 2017-05-16 00:21:15 +0300 | [diff] [blame] | 56 | - one core [**assertion macro**](assertions.html) for comparisons - standard C++ operators are used for the comparison (less than, equal, greater than...) - yet the full expression is decomposed and left and right values of the expression are logged |
| onqtam | 8126b56 | 2016-05-27 17:01:15 +0300 | [diff] [blame] | 57 | - assertion macros for [**exceptions**](assertions.html) - if something should or shouldn't throw |
| 58 | - floating point comparison support - see the [**```Approx()```**](assertions.html#floating-point-comparisons) helper |
| onqtam | b8220c5 | 2017-05-16 00:21:15 +0300 | [diff] [blame] | 59 | - powerful mechanism for [**stringification**](stringification.html) of user types - including [**exceptions**](stringification.html#translating-exceptions)! |
| 60 | - tests can be grouped in [**test suites**](testcases.html#test-suites) |
| 61 | - test case [**decorators**](testcases.html#decorators) such as ```description``` / ```skip``` / ```may_fail``` / ```should_fail``` / ```expected_failures``` / ```timeout``` |
| 62 | - can be used without exceptions and rtti - checkout [**```DOCTEST_CONFIG_NO_EXCEPTIONS```**](configuration.html#doctest_config_no_exceptions) |
| onqtam | 8126b56 | 2016-05-27 17:01:15 +0300 | [diff] [blame] | 63 | - powerful [**command line**](commandline.html) with lots of options |
| onqtam | b8220c5 | 2017-05-16 00:21:15 +0300 | [diff] [blame] | 64 | - can report the duration of test cases |
| onqtam | 8126b56 | 2016-05-27 17:01:15 +0300 | [diff] [blame] | 65 | - tests can be [**filtered**](commandline.html) based on their name/file/test suite using wildcards |
| onqtam | b8220c5 | 2017-05-16 00:21:15 +0300 | [diff] [blame] | 66 | - can [**filter**](commandline.html) subcases using wildcards and by specifying the nesting levels for which those filters should work |
| onqtam | 8126b56 | 2016-05-27 17:01:15 +0300 | [diff] [blame] | 67 | - failures can (optionally) break into the debugger on Windows and Mac |
| 68 | - integration with the output window of Visual Studio for failing tests |
| onqtam | 1435c01 | 2016-09-21 15:29:11 +0300 | [diff] [blame] | 69 | - a ```main()``` can be provided when implementing the library with the [**```DOCTEST_CONFIG_IMPLEMENT_WITH_MAIN```**](main.html#doctest_config_implement_with_main) identifier |
| onqtam | 8126b56 | 2016-05-27 17:01:15 +0300 | [diff] [blame] | 70 | - can write tests in headers - they will still be registered only once in the executable/shared object |
| onqtam | b8220c5 | 2017-05-16 00:21:15 +0300 | [diff] [blame] | 71 | - [**range-based**](commandline.html) execution of tests - see the [**example python script**](../../examples/range_based_execution.py) |
| onqtam | 8126b56 | 2016-05-27 17:01:15 +0300 | [diff] [blame] | 72 | - colored output in the console |
| 73 | - controlling the order of test execution |
| onqtam | b8220c5 | 2017-05-16 00:21:15 +0300 | [diff] [blame] | 74 | - different ```doctest::Context```s can be created and ran many times within a single execution of the program |
| 75 | - ability to query if code is currently being ran in a test - ```doctest::isRunningInTest()``` |
| onqtam | 8126b56 | 2016-05-27 17:01:15 +0300 | [diff] [blame] | 76 | |
| 77 | There is a list of planned features which are all important and big - see the [**roadmap**](roadmap.html). |
| 78 | |
| 79 | --------------- |
| 80 | |
| 81 | [Home](readme.html#reference) |
| 82 | |
| 83 | |
| 84 | </xmp> |
| 85 | <script src="strapdown.js/strapdown.js"></script> |
| 86 | </html> |