145 lines
4.8 KiB
Markdown
145 lines
4.8 KiB
Markdown
<a id="top"></a>
|
|
# Deprecations and incoming changes
|
|
|
|
This page documents current deprecations and upcoming planned changes
|
|
inside Catch2. The difference between these is that a deprecated feature
|
|
will be removed, while a planned change to a feature means that the
|
|
feature will behave differently, but will still be present. Obviously,
|
|
either of these is a breaking change, and thus will not happen until
|
|
at least the next major release.
|
|
|
|
|
|
## Deprecations
|
|
|
|
### `--list-*` return values
|
|
|
|
The return codes of the `--list-*` family of command line arguments
|
|
will no longer be equal to the number of tests/tags/etc found, instead
|
|
it will be 0 for success and non-zero for failure.
|
|
|
|
|
|
### `--list-test-names-only`
|
|
|
|
`--list-test-names-only` command line argument will be removed.
|
|
|
|
|
|
### `ANON_TEST_CASE`
|
|
|
|
`ANON_TEST_CASE` is scheduled for removal, as it can be fully replaced
|
|
by a `TEST_CASE` with no arguments.
|
|
|
|
|
|
### Secondary description amongst tags
|
|
|
|
Currently, the tags part of `TEST_CASE` (and others) macro can also
|
|
contain text that is not part of tags. This text is then separated into
|
|
a "description" of the test case, but the description is then never used
|
|
apart from writing it out for `--list-tests -v high`.
|
|
|
|
Because it isn't actually used nor documented, and brings complications
|
|
to Catch2's internals, description support will be removed.
|
|
|
|
### SourceLineInfo::empty()
|
|
|
|
There should be no reason to ever have an empty `SourceLineInfo`, so the
|
|
method will be removed.
|
|
|
|
|
|
### Composing lvalues of already composed matchers
|
|
|
|
Because a significant bug in this use case has persisted for 2+ years
|
|
without a bug report, and to simplify the implementation, code that
|
|
composes lvalues of composed matchers will not compile. That is,
|
|
this code will no longer work:
|
|
|
|
```cpp
|
|
auto m1 = Contains("string");
|
|
auto m2 = Contains("random");
|
|
auto composed1 = m1 || m2;
|
|
auto m3 = Contains("different");
|
|
auto composed2 = composed1 || m3;
|
|
REQUIRE_THAT(foo(), !composed1);
|
|
REQUIRE_THAT(foo(), composed2);
|
|
```
|
|
|
|
Instead you will have to write this:
|
|
|
|
```cpp
|
|
auto m1 = Contains("string");
|
|
auto m2 = Contains("random");
|
|
auto m3 = Contains("different");
|
|
REQUIRE_THAT(foo(), !(m1 || m2));
|
|
REQUIRE_THAT(foo(), m1 || m2 || m3);
|
|
```
|
|
|
|
### `ParseAndAddCatchTests.cmake`
|
|
|
|
The CMake/CTest integration using `ParseAndAddCatchTests.cmake` is deprecated,
|
|
as it can be replaced by `Catch.cmake` that provides the function
|
|
`catch_discover_tests` to get tests directly from a CMake target via the
|
|
command line interface instead of parsing C++ code with regular expressions.
|
|
|
|
|
|
## Planned changes
|
|
|
|
|
|
### Reporter verbosities
|
|
|
|
The current implementation of verbosities, where the reporter is checked
|
|
up-front whether it supports the requested verbosity, is fundamentally
|
|
misguided and will be changed. The new implementation will no longer check
|
|
whether the specified reporter supports the requested verbosity, instead
|
|
it will be up to the reporters to deal with verbosities as they see fit
|
|
(with an expectation that unsupported verbosities will be, at most,
|
|
warnings, but not errors).
|
|
|
|
|
|
### Output format of `--list-*` command line parameters
|
|
|
|
The various list operations will be piped through reporters. This means
|
|
that e.g. XML reporter will write the output as machine-parseable XML,
|
|
while the Console reporter will keep the current, human-oriented output.
|
|
|
|
|
|
### `CHECKED_IF` and `CHECKED_ELSE`
|
|
|
|
To make the `CHECKED_IF` and `CHECKED_ELSE` macros more useful, they will
|
|
be marked as "OK to fail" (`Catch::ResultDisposition::SuppressFail` flag
|
|
will be added), which means that their failure will not fail the test,
|
|
making the `else` actually useful.
|
|
|
|
|
|
### Change semantics of `[.]` and tag exclusion
|
|
|
|
Currently, given these 2 tests
|
|
```cpp
|
|
TEST_CASE("A", "[.][foo]") {}
|
|
TEST_CASE("B", "[.][bar]") {}
|
|
```
|
|
specifying `[foo]` as the testspec will run test "A" and specifying
|
|
`~[foo]` will run test "B", even though it is hidden. Also, specifying
|
|
`~[baz]` will run both tests. This behaviour is often surprising and will
|
|
be changed so that hidden tests are included in a run only if they
|
|
positively match a testspec.
|
|
|
|
|
|
### Console Colour API
|
|
|
|
The API for Catch2's console colour will be changed to take an extra
|
|
argument, the stream to which the colour code should be applied.
|
|
|
|
|
|
### Type erasure in the `PredicateMatcher`
|
|
|
|
Currently, the `PredicateMatcher` uses `std::function` for type erasure,
|
|
so that type of the matcher is always `PredicateMatcher<T>`, regardless
|
|
of the type of the predicate. Because of the high compilation overhead
|
|
of `std::function`, and the fact that the type erasure is used only rarely,
|
|
`PredicateMatcher` will no longer be type erased in the future. Instead,
|
|
the predicate type will be made part of the PredicateMatcher's type.
|
|
|
|
|
|
---
|
|
|
|
[Home](Readme.md#top)
|