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### SourceLineInfo::empty() 43 44There should be no reason to ever have an empty `SourceLineInfo`, so the 45method will be removed. 46 47 48### Composing lvalues of already composed matchers 49 50Because a significant bug in this use case has persisted for 2+ years 51without a bug report, and to simplify the implementation, code that 52composes lvalues of composed matchers will not compile. That is, 53this code will no longer work: 54 55```cpp 56 auto m1 = Contains("string"); 57 auto m2 = Contains("random"); 58 auto composed1 = m1 || m2; 59 auto m3 = Contains("different"); 60 auto composed2 = composed1 || m3; 61 REQUIRE_THAT(foo(), !composed1); 62 REQUIRE_THAT(foo(), composed2); 63``` 64 65Instead you will have to write this: 66 67```cpp 68 auto m1 = Contains("string"); 69 auto m2 = Contains("random"); 70 auto m3 = Contains("different"); 71 REQUIRE_THAT(foo(), !(m1 || m2)); 72 REQUIRE_THAT(foo(), m1 || m2 || m3); 73``` 74 75 76## Planned changes 77 78 79### Reporter verbosities 80 81The current implementation of verbosities, where the reporter is checked 82up-front whether it supports the requested verbosity, is fundamentally 83misguided and will be changed. The new implementation will no longer check 84whether the specified reporter supports the requested verbosity, instead 85it will be up to the reporters to deal with verbosities as they see fit 86(with an expectation that unsupported verbosities will be, at most, 87warnings, but not errors). 88 89 90### Output format of `--list-*` command line parameters 91 92The various list operations will be piped through reporters. This means 93that e.g. XML reporter will write the output as machine-parseable XML, 94while the Console reporter will keep the current, human-oriented output. 95 96 97### `CHECKED_IF` and `CHECKED_ELSE` 98 99To make the `CHECKED_IF` and `CHECKED_ELSE` macros more useful, they will 100be marked as "OK to fail" (`Catch::ResultDisposition::SuppressFail` flag 101will be added), which means that their failure will not fail the test, 102making the `else` actually useful. 103 104 105### Change semantics of `[.]` and tag exclusion 106 107Currently, given these 2 tests 108```cpp 109TEST_CASE("A", "[.][foo]") {} 110TEST_CASE("B", "[.][bar]") {} 111``` 112specifying `[foo]` as the testspec will run test "A" and specifying 113`~[foo]` will run test "B", even though it is hidden. Also, specifying 114`~[baz]` will run both tests. This behaviour is often surprising and will 115be changed so that hidden tests are included in a run only if they 116positively match a testspec. 117 118 119### Console Colour API 120 121The API for Catch2's console colour will be changed to take an extra 122argument, the stream to which the colour code should be applied. 123 124 125### Type erasure in the `PredicateMatcher` 126 127Currently, the `PredicateMatcher` uses `std::function` for type erasure, 128so that type of the matcher is always `PredicateMatcher<T>`, regardless 129of the type of the predicate. Because of the high compilation overhead 130of `std::function`, and the fact that the type erasure is used only rarely, 131`PredicateMatcher` will no longer be type erased in the future. Instead, 132the predicate type will be made part of the PredicateMatcher's type. 133 134 135--- 136 137[Home](Readme.md#top) 138