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