Read-only mirrors. Development, issues and pull requests are on GitHub.

summaryrefslogtreecommitdiffhomepage
path: root/docs
diff options
context:
space:
mode:
authorMartin Hořeňovský2022-04-04 21:07:04 +0200
committerMartin Hořeňovský2022-04-07 12:50:08 +0200
commit423e1d2ebbd75bb92cb486f83f2c5800b4b9689e (patch)
tree3cfff7f75517b1771ab43c7439ba195a77dcec31 /docs
parent3c06bcb374aaebf91ad1d63aba655dee66cf7b91 (diff)
downloadcatch3-423e1d2ebbd75bb92cb486f83f2c5800b4b9689e.tar.gz
Integrate the new reporter specs into Catch2
This means that the CLI interface now uses the new key-value oriented reporter spec, the common reporter base creates the colour implementation based on the reporter-specific configuration, and it also stores the custom configuration options for each reporter instance. Closes #339 as it allows per-reporter forcing of ansi colour codes.
Diffstat (limited to 'docs')
-rw-r--r--docs/command-line.md28
-rw-r--r--docs/reporters.md27
2 files changed, 45 insertions, 10 deletions
diff --git a/docs/command-line.md b/docs/command-line.md
index 29e6a365..829c156d 100644
--- a/docs/command-line.md
+++ b/docs/command-line.md
@@ -123,22 +123,33 @@ Test names containing special characters, such as `,` or `[` can specify them on
<a id="choosing-a-reporter-to-use"></a>
## Choosing a reporter to use
-<pre>-r, --reporter &lt;reporter[::output-file]&gt;</pre>
-
-> Support for providing output-file through the `-r`, `--reporter` flag was [introduced](https://github.com/catchorg/Catch2/pull/2183) in Catch2 X.Y.Z
+<pre>-r, --reporter &lt;reporter[::key=value]*&gt;</pre>
Reporters are how the output from Catch2 (results of assertions, tests,
benchmarks and so on) is formatted and written out. The default reporter
is called the "Console" reporter and is intended to provide relatively
verbose and human-friendly output.
+Reporters are also individually configurable. To pass configuration options
+to the reporter, you append `::key=value` to the reporter specification
+as many times as you want, e.g. `--reporter xml::out=someFile.xml`.
+
+The keys must either be prefixed by "X", in which case they are not parsed
+by Catch2 and are only passed down to the reporter, or one of options
+hardcoded into Catch2. Currently there are only 2,
+["out"](#sending-output-to-a-file), and ["colour-mode"](#colour-mode).
+
+_Note that the reporter might still check the X-prefixed options for
+validity, and throw an error if they are wrong._
+
+> Support for passing arguments to reporters through the `-r`, `--reporter` flag was introduced in Catch2 X.Y.Z
+
There are multiple built-in reporters, you can see what they do by using the
[`--list-reporter`](command-line.md#listing-available-tests-tags-or-reporters)
flag. If you need a reporter providing custom format outside of the already
provided ones, look at the ["write your own reporter" part of the reporter
documentation](reporters.md#writing-your-own-reporter).
-
This option may be passed multiple times to use multiple (different)
reporters at the same time. See the [reporter documentation](reporters.md#multiple-reporters)
for details on what the resulting behaviour is. Also note that at most one
@@ -148,13 +159,12 @@ the [`-o`, `--out`](#sending-output-to-a-file) option.
> Support for using multiple different reporters at the same time was [introduced](https://github.com/catchorg/Catch2/pull/2183) in Catch2 X.Y.Z
-As with the `--out` option, using `-` for the output file name sends the
-output to stdout.
_Note: There is currently no way to escape `::` in the reporter spec,
-and thus reporter/file names with `::` in them will not work properly.
-As `::` in paths is relatively obscure (unlike `:`), we do not consider
-this an issue._
+and thus the reporter names, or configuration keys and values, cannot
+contain `::`. As `::` in paths is relatively obscure (unlike ':'), we do
+not consider this an issue._
+
<a id="breaking-into-the-debugger"></a>
## Breaking into the debugger
diff --git a/docs/reporters.md b/docs/reporters.md
index ab6f6453..5f86b02e 100644
--- a/docs/reporters.md
+++ b/docs/reporters.md
@@ -43,9 +43,14 @@ them write into different destinations. The two main uses of this are
Specifying multiple reporter looks like this:
```
---reporter console::- --reporter JUnit::result-junit.xml
+--reporter JUnit::out=result-junit.xml --reporter console::out=-::colour-mode=ansi
```
+This tells Catch2 to use two reporters, `JUnit` reporter that writes
+its machine-readable XML output to file `result-junit.xml`, and the
+`console` reporter that writes its user-friendly output to stdout and
+uses ANSI colour codes for colouring the output.
+
Using multiple reporters (or one reporter and one-or-more [event
listeners](event-listener.md#top)) can have surprisingly complex semantics
when using customization points provided to reporters by Catch2, namely
@@ -162,6 +167,26 @@ Currently there are two customization options:
format includes passing assertions even without the `-s` flag.
+### Per-reporter configuration
+
+> Per-reporter configuration was introduced in Catch2 X.Y.Z
+
+Catch2 supports some configuration to happen per reporter. The configuration
+options fall into one of two categories:
+
+* Catch2-recognized options
+* Reporter-specific options
+
+The former is a small set of universal options that Catch2 handles for
+the reporters, e.g. output file or console colour mode. The latter are
+options that the reporters have to handle themselves, but the keys and
+values can be arbitrary strings, as long as they don't contain `::`. This
+allows writing reporters that can be significantly customized at runtime.
+
+Reporter-specific options always have to be prefixed with "X" (large
+letter X).
+
+
### Other expected functionality of a reporter
When writing a custom reporter, there are few more things that you should