Progmasoft Git

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"

This captures the intent better, as some changes are indeed plain
deprecations leading to removal, but other changes can be viewed
as minor tune-ups instead.
Commit
df019cc1138f055c30d2eb5f1cabf117fc184d6f
Author
Martin Hořeňovský ·
Parents
695e6eafc518

Files · Download .tar.gz

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.
 
 
 ---