| onqtam | 8126b56 | 2016-05-27 17:01:15 +0300 | [diff] [blame] | 1 | <!DOCTYPE html> |
| 2 | <html> |
| 3 | <title>main</title> |
| 4 | <xmp theme="united" style="display:none;"> |
| 5 | |
| 6 | ## The ```main()``` entry point |
| 7 | |
| 8 | The usual way of writing tests in C++ has always been into separate source files from the code they test that form an executable containing only tests. In that scenario the default ```main()``` provided by **doctest** is usually sufficient: |
| 9 | |
| 10 | ``` |
| 11 | #define DOCTEST_CONFIG_IMPLEMENT_WITH_MAIN |
| 12 | #include "doctest.h" |
| 13 | ``` |
| 14 | |
| 15 | This should be done in exactly one source file and is even a good idea to do this in a separate file with nothing else in it. |
| 16 | |
| onqtam | 1435c01 | 2016-09-21 15:29:11 +0300 | [diff] [blame] | 17 | However if you need more control - want to set options with code to the execution context or want to integrate the framework in your production code - then the default ```main()``` just won't do the job. In that case use [**```DOCTEST_CONFIG_IMPLEMENT```**](configuration.html#doctest_config_implement). |
| onqtam | 8126b56 | 2016-05-27 17:01:15 +0300 | [diff] [blame] | 18 | |
| onqtam | b8220c5 | 2017-05-16 00:21:15 +0300 | [diff] [blame] | 19 | All the [**command line**](commandline.html) options can be set like this (flags cannot because it wouldn't make sense). Filters can only be appended or cleared with the ```addFilter()``` or ```clearFilters()``` method of a ```doctest::Context``` object - the user cannot remove a specific filter with code. |
| onqtam | 8126b56 | 2016-05-27 17:01:15 +0300 | [diff] [blame] | 20 | |
| 21 | ``` |
| 22 | #define DOCTEST_CONFIG_IMPLEMENT |
| 23 | #include "doctest.h" |
| 24 | |
| 25 | int main(int argc, char** argv) { |
| onqtam | b8220c5 | 2017-05-16 00:21:15 +0300 | [diff] [blame] | 26 | doctest::Context context; |
| 27 | |
| 28 | // !!! THIS IS JUST AN EXAMPLE SHOWING HOW DEFAULTS/OVERRIDES ARE SET !!! |
| onqtam | 1435c01 | 2016-09-21 15:29:11 +0300 | [diff] [blame] | 29 | |
| 30 | // defaults |
| 31 | context.addFilter("test-case-exclude", "*math*"); // exclude test cases with "math" in their name |
| 32 | context.setOption("abort-after", 5); // stop test execution after 5 failed assertions |
| onqtam | b8220c5 | 2017-05-16 00:21:15 +0300 | [diff] [blame] | 33 | context.setOption("order-by", "name"); // sort the test cases by their name |
| onqtam | 1435c01 | 2016-09-21 15:29:11 +0300 | [diff] [blame] | 34 | |
| 35 | context.applyCommandLine(argc, argv); |
| onqtam | 8126b56 | 2016-05-27 17:01:15 +0300 | [diff] [blame] | 36 | |
| 37 | // overrides |
| onqtam | 1435c01 | 2016-09-21 15:29:11 +0300 | [diff] [blame] | 38 | context.setOption("no-breaks", true); // don't break in the debugger when assertions fail |
| onqtam | 8126b56 | 2016-05-27 17:01:15 +0300 | [diff] [blame] | 39 | |
| 40 | int res = context.run(); // run |
| 41 | |
| onqtam | e8bdda4 | 2016-06-01 15:12:36 +0300 | [diff] [blame] | 42 | if(context.shouldExit()) // important - query flags (and --exit) rely on the user doing this |
| onqtam | 8126b56 | 2016-05-27 17:01:15 +0300 | [diff] [blame] | 43 | return res; // propagate the result of the tests |
| 44 | |
| 45 | int client_stuff_return_code = 0; |
| 46 | // your program - if the testing framework is integrated in your production code |
| 47 | |
| onqtam | 1435c01 | 2016-09-21 15:29:11 +0300 | [diff] [blame] | 48 | return res + client_stuff_return_code; // the result from doctest is propagated here as well |
| onqtam | 8126b56 | 2016-05-27 17:01:15 +0300 | [diff] [blame] | 49 | } |
| 50 | |
| 51 | ``` |
| 52 | |
| 53 | Note the call to ```.shouldExit()``` on the context - that is very important - it will be set when a query flag has been used (or the ```--no-run``` option is set to ```true```) and it is the user's responsibility to exit the application in a normal way. |
| 54 | |
| 55 | ### Dealing with shared objects (DLLs) |
| 56 | |
| onqtam | b8220c5 | 2017-05-16 00:21:15 +0300 | [diff] [blame] | 57 | The framework can be used separately in binaries (executables / shared objects) with each having it's own test runner - this way even different versions of doctest can be used - but there will be no simple way to execute the tests from all loaded binaries and have the results aggregated and summarized. |
| onqtam | 8126b56 | 2016-05-27 17:01:15 +0300 | [diff] [blame] | 58 | |
| onqtam | b8220c5 | 2017-05-16 00:21:15 +0300 | [diff] [blame] | 59 | There is also an option to have the test runner (implementation) built in a binary and shared with others (so there is a single test registry) by exporting it's public symbols (the ones needed for writing tests by the user - all the forward declarations of the framework). |
| 60 | |
| 61 | For more info on that checkout the [**```DOCTEST_CONFIG_IMPLEMENTATION_IN_DLL```**](configuration.html#doctest_config_implementation_in_dll) config identifier and [**this example**](../../examples/executable_dll_and_plugin/). |
| onqtam | 8126b56 | 2016-05-27 17:01:15 +0300 | [diff] [blame] | 62 | |
| 63 | --------------- |
| 64 | |
| 65 | [Home](readme.html#reference) |
| 66 | |
| onqtam | f8d5719 | 2018-08-23 16:02:12 +0300 | [diff] [blame^] | 67 | <p align="center"><img src="../../scripts/data/logo/icon_2.svg"></p> |
| 68 | |
| onqtam | 8126b56 | 2016-05-27 17:01:15 +0300 | [diff] [blame] | 69 | |
| 70 | </xmp> |
| 71 | <script src="strapdown.js/strapdown.js"></script> |
| 72 | </html> |