Gitiles
Code Review Sign In
gerrit.cesnet.cz / github / onqtam / doctest / 8ee354591f81f0159a2cb9b2795fae9999844df5 / . / doc / html_generated / reporters.html
blob: ccacb28f70de9d9757b59f2ad84fb4e6c7b7f893 [file] [log] [blame]
onqtamcb6a29f2018-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
onqtam92dce5b2019-03-23 14:24:47 +0200[diff] [blame]8Doctest 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
onqtam50146342019-08-12 22:29:59 +0300[diff] [blame]10You can list all registered reporters/listeners with ```--list-reporters```. There are a few implemented reporters in the framework:
onqtam92dce5b2019-03-23 14:24:47 +0200[diff] [blame]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
onqtam8ee35452021-12-15 15:42:40 +0200[diff] [blame^]13- ```junit``` - buffering - writes in JUnit-compatible xml - for more information look [here](https://github.com/doctest/doctest/issues/318) and [here](https://github.com/doctest/doctest/issues/376).
onqtam92dce5b2019-03-23 14:24:47 +0200[diff] [blame]14
15Streaming means that results are delivered progressively and not at the end of the test run.
16
17The output is by default written to ```stdout``` but can be redirected with the use of the ```--out=<filename>``` [**command line option**](commandline.html).
onqtam9639cee2018-10-24 17:46:32 +0300[diff] [blame]18
19Example how to define your own reporter:
20
21```
onqtam92dce5b2019-03-23 14:24:47 +0200[diff] [blame]22#include <doctest/doctest.h>
23
24#include <mutex>
25
onqtam9639cee2018-10-24 17:46:32 +0300[diff] [blame]26using namespace doctest;
27
onqtam92dce5b2019-03-23 14:24:47 +0200[diff] [blame]28struct MyXmlReporter : public IReporter
onqtam9639cee2018-10-24 17:46:32 +0300[diff] [blame]29{
onqtam92dce5b2019-03-23 14:24:47 +0200[diff] [blame]30 // caching pointers/references to objects of these types - safe to do
31 std::ostream& stdout_stream;
32 const ContextOptions& opt;
onqtam9639cee2018-10-24 17:46:32 +0300[diff] [blame]33 const TestCaseData* tc;
onqtam92dce5b2019-03-23 14:24:47 +0200[diff] [blame]34 std::mutex mutex;
onqtam9639cee2018-10-24 17:46:32 +0300[diff] [blame]35
onqtam92dce5b2019-03-23 14:24:47 +0200[diff] [blame]36 // constructor has to accept the ContextOptions by ref as a single argument
37 MyXmlReporter(const ContextOptions& in)
38 : stdout_stream(*in.cout)
39 , opt(in) {}
onqtam9639cee2018-10-24 17:46:32 +0300[diff] [blame]40
onqtam92dce5b2019-03-23 14:24:47 +0200[diff] [blame]41 void report_query(const QueryData& /*in*/) override {}
onqtam9639cee2018-10-24 17:46:32 +0300[diff] [blame]42
onqtam92dce5b2019-03-23 14:24:47 +0200[diff] [blame]43 void test_run_start() override {}
44
45 void test_run_end(const TestRunStats& /*in*/) override {}
onqtam9639cee2018-10-24 17:46:32 +0300[diff] [blame]46
47 void test_case_start(const TestCaseData& in) override { tc = &in; }
48
onqtam77af2002019-09-22 21:17:20 +0300[diff] [blame]49 // called when a test case is reentered because of unfinished subcases
50 void test_case_reenter(const TestCaseData& /*in*/) override {}
51
onqtam92dce5b2019-03-23 14:24:47 +0200[diff] [blame]52 void test_case_end(const CurrentTestCaseStats& /*in*/) override {}
onqtam9639cee2018-10-24 17:46:32 +0300[diff] [blame]53
onqtam92dce5b2019-03-23 14:24:47 +0200[diff] [blame]54 void test_case_exception(const TestCaseException& /*in*/) override {}
onqtam9639cee2018-10-24 17:46:32 +0300[diff] [blame]55
onqtam505b05c2019-05-06 11:39:02 +0300[diff] [blame]56 void subcase_start(const SubcaseSignature& /*in*/) override {
57 std::lock_guard<std::mutex> lock(mutex);
58 }
onqtam9639cee2018-10-24 17:46:32 +0300[diff] [blame]59
onqtam505b05c2019-05-06 11:39:02 +0300[diff] [blame]60 void subcase_end() override {
61 std::lock_guard<std::mutex> lock(mutex);
62 }
onqtam9639cee2018-10-24 17:46:32 +0300[diff] [blame]63
onqtam92dce5b2019-03-23 14:24:47 +0200[diff] [blame]64 void log_assert(const AssertData& in) override {
65 // don't include successful asserts by default - this is done here
66 // instead of in the framework itself because doctest doesn't know
67 // if/when a reporter/listener cares about successful results
68 if(!in.m_failed && !opt.success)
69 return;
70
71 // make sure there are no races - this is done here instead of in the
72 // framework itself because doctest doesn't know if reporters/listeners
73 // care about successful asserts and thus doesn't lock a mutex unnecessarily
74 std::lock_guard<std::mutex> lock(mutex);
75
76 // ...
77 }
78
79 void log_message(const MessageData& /*in*/) override {
80 // messages too can be used in a multi-threaded context - like asserts
81 std::lock_guard<std::mutex> lock(mutex);
82
83 // ...
84 }
onqtam9639cee2018-10-24 17:46:32 +0300[diff] [blame]85
86 void test_case_skipped(const TestCaseData& /*in*/) override {}
87};
88
onqtam50146342019-08-12 22:29:59 +0300[diff] [blame]89// "1" is the priority - used for ordering when multiple reporters are used
onqtam92dce5b2019-03-23 14:24:47 +0200[diff] [blame]90REGISTER_REPORTER("my_xml", 1, MyXmlReporter);
onqtam50146342019-08-12 22:29:59 +0300[diff] [blame]91
92// registering the same class as a reporter and as a listener is nonsense but it's possible
93REGISTER_LISTENER("my_listener", 1, MyXmlReporter);
onqtam9639cee2018-10-24 17:46:32 +0300[diff] [blame]94```
95
onqtam50146342019-08-12 22:29:59 +0300[diff] [blame]96Custom `IReporter` implementations must be registered with one of:
97
98* `REGISTER_REPORTER`, for when the new reporter is an option that users may choose at run-time.
99* `REGISTER_LISTENER`, for when the reporter is actually a listener and must always be executed, regardless of which reporters have been chosen at run-time.
100
101Multiple 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=myReporter,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).
102
103All registered listeners (```REGISTER_LISTENER```) will be executed before any reporter - they do not need to be specified and cannot be filtered through the command line.
onqtam9639cee2018-10-24 17:46:32 +0300[diff] [blame]104
onqtam92dce5b2019-03-23 14:24:47 +0200[diff] [blame]105When 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).
onqtamcb6a29f2018-08-23 16:24:06 +0300[diff] [blame]106
107---------------
108
109[Home](readme.html#reference)
110
111<p align="center"><img src="../../scripts/data/logo/icon_2.svg"></p>
112
113
114</xmp>
115<script src="strapdown.js/strapdown.js"></script>
116</html>