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

summaryrefslogtreecommitdiffhomepage
path: root/docs/command-line.md
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/command-line.md
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/command-line.md')
-rw-r--r--docs/command-line.md28
1 files changed, 19 insertions, 9 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