| onqtam | cb6a29f | 2018-08-23 16:24:06 +0300 | [diff] [blame] | 1 | <!DOCTYPE html> |
| 2 | <html> |
| 3 | <title>reporters</title> |
| 4 | <xmp theme="united" style="display:none;"> |
| 5 | |
| 6 | ## Reporters |
| 7 | |
| onqtam | 92dce5b | 2019-03-23 14:24:47 +0200 | [diff] [blame] | 8 | Doctest has a modular reporter/listener system with which users can write their own reporters and register them. The reporter interface can also be used for "listening" to events. |
| 9 | |
| 10 | You can list all registered reporters with ```--list-reporters```. There are a few implemented reporters in the framework: |
| 11 | - ```console``` - streaming - writes normal lines of text with coloring if a capable terminal is detected |
| 12 | - ```xml``` - streaming - writes in xml format tailored to doctest |
| 13 | |
| 14 | Streaming means that results are delivered progressively and not at the end of the test run. |
| 15 | |
| 16 | The output is by default written to ```stdout``` but can be redirected with the use of the ```--out=<filename>``` [**command line option**](commandline.html). |
| onqtam | 9639cee | 2018-10-24 17:46:32 +0300 | [diff] [blame] | 17 | |
| 18 | Example how to define your own reporter: |
| 19 | |
| 20 | ``` |
| onqtam | 92dce5b | 2019-03-23 14:24:47 +0200 | [diff] [blame] | 21 | #include <doctest/doctest.h> |
| 22 | |
| 23 | #include <mutex> |
| 24 | |
| onqtam | 9639cee | 2018-10-24 17:46:32 +0300 | [diff] [blame] | 25 | using namespace doctest; |
| 26 | |
| onqtam | 92dce5b | 2019-03-23 14:24:47 +0200 | [diff] [blame] | 27 | struct MyXmlReporter : public IReporter |
| onqtam | 9639cee | 2018-10-24 17:46:32 +0300 | [diff] [blame] | 28 | { |
| onqtam | 92dce5b | 2019-03-23 14:24:47 +0200 | [diff] [blame] | 29 | // caching pointers/references to objects of these types - safe to do |
| 30 | std::ostream& stdout_stream; |
| 31 | const ContextOptions& opt; |
| onqtam | 9639cee | 2018-10-24 17:46:32 +0300 | [diff] [blame] | 32 | const TestCaseData* tc; |
| onqtam | 92dce5b | 2019-03-23 14:24:47 +0200 | [diff] [blame] | 33 | std::mutex mutex; |
| onqtam | 9639cee | 2018-10-24 17:46:32 +0300 | [diff] [blame] | 34 | |
| onqtam | 92dce5b | 2019-03-23 14:24:47 +0200 | [diff] [blame] | 35 | // constructor has to accept the ContextOptions by ref as a single argument |
| 36 | MyXmlReporter(const ContextOptions& in) |
| 37 | : stdout_stream(*in.cout) |
| 38 | , opt(in) {} |
| onqtam | 9639cee | 2018-10-24 17:46:32 +0300 | [diff] [blame] | 39 | |
| onqtam | 92dce5b | 2019-03-23 14:24:47 +0200 | [diff] [blame] | 40 | void report_query(const QueryData& /*in*/) override {} |
| onqtam | 9639cee | 2018-10-24 17:46:32 +0300 | [diff] [blame] | 41 | |
| onqtam | 92dce5b | 2019-03-23 14:24:47 +0200 | [diff] [blame] | 42 | void test_run_start() override {} |
| 43 | |
| 44 | void test_run_end(const TestRunStats& /*in*/) override {} |
| onqtam | 9639cee | 2018-10-24 17:46:32 +0300 | [diff] [blame] | 45 | |
| 46 | void test_case_start(const TestCaseData& in) override { tc = ∈ } |
| 47 | |
| onqtam | 92dce5b | 2019-03-23 14:24:47 +0200 | [diff] [blame] | 48 | void test_case_end(const CurrentTestCaseStats& /*in*/) override {} |
| onqtam | 9639cee | 2018-10-24 17:46:32 +0300 | [diff] [blame] | 49 | |
| onqtam | 92dce5b | 2019-03-23 14:24:47 +0200 | [diff] [blame] | 50 | void test_case_exception(const TestCaseException& /*in*/) override {} |
| onqtam | 9639cee | 2018-10-24 17:46:32 +0300 | [diff] [blame] | 51 | |
| onqtam | 92dce5b | 2019-03-23 14:24:47 +0200 | [diff] [blame] | 52 | void subcase_start(const SubcaseSignature& /*in*/) override {} |
| onqtam | 9639cee | 2018-10-24 17:46:32 +0300 | [diff] [blame] | 53 | |
| onqtam | 92dce5b | 2019-03-23 14:24:47 +0200 | [diff] [blame] | 54 | void subcase_end() override {} |
| onqtam | 9639cee | 2018-10-24 17:46:32 +0300 | [diff] [blame] | 55 | |
| onqtam | 92dce5b | 2019-03-23 14:24:47 +0200 | [diff] [blame] | 56 | void log_assert(const AssertData& in) override { |
| 57 | // don't include successful asserts by default - this is done here |
| 58 | // instead of in the framework itself because doctest doesn't know |
| 59 | // if/when a reporter/listener cares about successful results |
| 60 | if(!in.m_failed && !opt.success) |
| 61 | return; |
| 62 | |
| 63 | // make sure there are no races - this is done here instead of in the |
| 64 | // framework itself because doctest doesn't know if reporters/listeners |
| 65 | // care about successful asserts and thus doesn't lock a mutex unnecessarily |
| 66 | std::lock_guard<std::mutex> lock(mutex); |
| 67 | |
| 68 | // ... |
| 69 | } |
| 70 | |
| 71 | void log_message(const MessageData& /*in*/) override { |
| 72 | // messages too can be used in a multi-threaded context - like asserts |
| 73 | std::lock_guard<std::mutex> lock(mutex); |
| 74 | |
| 75 | // ... |
| 76 | } |
| onqtam | 9639cee | 2018-10-24 17:46:32 +0300 | [diff] [blame] | 77 | |
| 78 | void test_case_skipped(const TestCaseData& /*in*/) override {} |
| 79 | }; |
| 80 | |
| onqtam | 92dce5b | 2019-03-23 14:24:47 +0200 | [diff] [blame] | 81 | // "1" is the priority - used for ordering when multiple reporters/listeners are used |
| 82 | REGISTER_REPORTER("my_xml", 1, MyXmlReporter); |
| onqtam | 9639cee | 2018-10-24 17:46:32 +0300 | [diff] [blame] | 83 | ``` |
| 84 | |
| onqtam | 92dce5b | 2019-03-23 14:24:47 +0200 | [diff] [blame] | 85 | Multiple reporters can be used at the same time - just specify them through the ```--reporters=...``` [**command line filtering option**](commandline.html) using commas to separate them like this: ```--reporters=myListener,xml``` and their order of execution will be based on their priority - that is the number "1" in the case of the example reporter above (lower means earlier - the default console/xml reporters from the framework have 0 as their priority and negative numbers are accepted as well). |
| onqtam | 9639cee | 2018-10-24 17:46:32 +0300 | [diff] [blame] | 86 | |
| onqtam | 92dce5b | 2019-03-23 14:24:47 +0200 | [diff] [blame] | 87 | When implementing a reporter users are advised to follow the comments from the example above and look at the few implemented reporters in the framework itself. Also check out the [**example**](../../examples/all_features/reporters_and_listeners.cpp). |
| onqtam | cb6a29f | 2018-08-23 16:24:06 +0300 | [diff] [blame] | 88 | |
| 89 | --------------- |
| 90 | |
| 91 | [Home](readme.html#reference) |
| 92 | |
| 93 | <p align="center"><img src="../../scripts/data/logo/icon_2.svg"></p> |
| 94 | |
| 95 | |
| 96 | </xmp> |
| 97 | <script src="strapdown.js/strapdown.js"></script> |
| 98 | </html> |