catch3
Progmasoft Catch3: an independently maintained C++17 test framework with a parallel runner, property checks, snapshots and structured results.
Clonegit clone https://git.progmasoft.com/catch3
Turn "deprecations" into "deprecations and planned changes"
- Commit
df019cc1138f055c30d2eb5f1cabf117fc184d6f- Author
- Martin Hořeňovský ·
- Parents
695e6eafc518
Changes
docs/Readme.md | 2 +- docs/deprecations.md | 97 ++++++++++++++++++++++++++++++++-------------------- 2 files changed, 61 insertions(+), 38 deletions(-) diff --git a/docs/Readme.md b/docs/Readme.md index b203845e..721880ab 100644 --- a/docs/Readme.md +++ b/docs/Readme.md @@ -36,4 +36,4 @@ Other: * [Open Source Projects using Catch](opensource-users.md#top) * [Contributing](contributing.md#top) * [Release Notes](release-notes.md#top) -* [Deprecations](deprecations.md#top) \ No newline at end of file +* [Deprecations and incoming changes](deprecations.md#top) diff --git a/docs/deprecations.md b/docs/deprecations.md index 3a4144de..b8047684 100644 --- a/docs/deprecations.md +++ b/docs/deprecations.md @@ -1,63 +1,86 @@ <a id="top"></a> # Deprecations and incoming changes -**Contents**<br> -[Verbosities](#verbosities)<br> -[`--list-*` command line parameters](#--list--command-line-parameters)<br> -[Types passed to the reporter interface](#types-passed-to-the-reporter-interface)<br> -[Generators](#generators)<br> -[`ANON_TEST_CASE`](#anon_test_case)<br> -[Secondary description amongst tags](#secondary-description-amongst-tags)<br> +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. -This page documents current deprecations and upcoming changes inside -Catch2. You can expect deprecated functionality to stick around until -the next major release, but not for longer. +## Deprecations -## Verbosities +### `--list-*` return values -The current implementation of verbosities has been misguided and will -be removed. Note that this does not mean verbosities will be gone, just -that they will no longer be checked up-front, and a reporter can handle -verbosity however it sees fit (including ignoring it). +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-*` command line parameters +### `--list-test-names-only` -There will be 3 large changes to the `--list-*` family of command line -parameters. +`--list-test-names-only` command line argument will be removed. -* Their return codes will no longer reflect the number of tests/tags/etc -that were found, instead it will be 0 for success and non-zero for failure. -* Their output will be piped through reporters, so that e.g. XML reporter -will write the output as a machine-readable XML, while the console -reporter will keep the current output. -* `--list-test-names-only` will be completely removed. +### `ANON_TEST_CASE` -## Types passed to the reporter interface +`ANON_TEST_CASE` is scheduled for removal, as it can be fully replaced +by a `TEST_CASE` with no arguments. -To allow changes in internal representation, we are planning to change -the arguments provided to functions in the reporter interface. +### Secondary description amongst tags -## Generators +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`. -The current generator interface is not intended to be stable and will be -changed. +Because it isn't actually used nor documented, and brings complications +to Catch2's internals, description support will be removed. -## `ANON_TEST_CASE` +## Planned changes -`ANON_TEST_CASE` is scheduled for removal, as it can be fully replaced -by a `TEST_CASE` with no arguments. +### Reporter verbosities -## Secondary description amongst tags +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). -Currently, the tags part of `TEST_CASE` (and others) macro can also -contain text that is not part of tags. As it is not actually documented, -or used, it will be removed. + +### 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. ---