1<a id="top"></a>
2# Deprecations and incoming changes
3
4This page documents current deprecations and upcoming planned changes
5inside Catch2. The difference between these is that a deprecated feature
6will be removed, while a planned change to a feature means that the
7feature will behave differently, but will still be present. Obviously,
8either of these is a breaking change, and thus will not happen until
9at least the next major release.
10
11
12## Deprecations
13
14### `--list-*` return values
15
16The return codes of the `--list-*` family of command line arguments
17will no longer be equal to the number of tests/tags/etc found, instead
18it will be 0 for success and non-zero for failure.
19
20
21### `--list-test-names-only`
22
23`--list-test-names-only` command line argument will be removed.
24
25
26### `ANON_TEST_CASE`
27
28`ANON_TEST_CASE` is scheduled for removal, as it can be fully replaced
29by a `TEST_CASE` with no arguments.
30
31
32### Secondary description amongst tags
33
34Currently, the tags part of `TEST_CASE` (and others) macro can also
35contain text that is not part of tags. This text is then separated into
36a "description" of the test case, but the description is then never used
37apart from writing it out for `--list-tests -v high`.
38
39Because it isn't actually used nor documented, and brings complications
40to Catch2's internals, description support will be removed.
41
42
43## Planned changes
44
45
46### Reporter verbosities
47
48The current implementation of verbosities, where the reporter is checked
49up-front whether it supports the requested verbosity, is fundamentally
50misguided and will be changed. The new implementation will no longer check
51whether the specified reporter supports the requested verbosity, instead
52it will be up to the reporters to deal with verbosities as they see fit
53(with an expectation that unsupported verbosities will be, at most,
54warnings, but not errors).
55
56
57### Output format of `--list-*` command line parameters
58
59The various list operations will be piped through reporters. This means
60that e.g. XML reporter will write the output as machine-parseable XML,
61while the Console reporter will keep the current, human-oriented output.
62
63
64### `CHECKED_IF` and `CHECKED_ELSE`
65
66To make the `CHECKED_IF` and `CHECKED_ELSE` macros more useful, they will
67be marked as "OK to fail" (`Catch::ResultDisposition::SuppressFail` flag
68will be added), which means that their failure will not fail the test,
69making the `else` actually useful.
70
71
72### Change semantics of `[.]` and tag exclusion
73
74Currently, given these 2 tests
75```cpp
76TEST_CASE("A", "[.][foo]") {}
77TEST_CASE("B", "[.][bar]") {}
78```
79specifying `[foo]` as the testspec will run test "A" and specifying
80`~[foo]` will run test "B", even though it is hidden. Also, specifying
81`~[baz]` will run both tests. This behaviour is often surprising and will
82be changed so that hidden tests are included in a run only if they
83positively match a testspec.
84
85
86### Console Colour API
87
88The API for Catch2's console colour will be changed to take an extra
89argument, the stream to which the colour code should be applied.
90
91---
92
93[Home](Readme.md#top)
94