From 16f48f8c7c599be81190eca7a4207eebaec740c6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Martin=20Ho=C5=99e=C5=88ovsk=C3=BD?= Date: Thu, 12 Jan 2023 16:22:56 +0100 Subject: [PATCH] Add SUCCEED and FAIL docs next to SKIP docs --- docs/Readme.md | 2 +- docs/command-line.md | 2 +- docs/deprecations.md | 2 +- ...kipping.md => skipping-passing-failing.md} | 48 +++++++++++++++++-- 4 files changed, 48 insertions(+), 6 deletions(-) rename docs/{skipping.md => skipping-passing-failing.md} (61%) diff --git a/docs/Readme.md b/docs/Readme.md index 126ee1be..d84b4bfd 100644 --- a/docs/Readme.md +++ b/docs/Readme.md @@ -11,7 +11,7 @@ Once you're up and running consider the following reference material. * [Logging macros](logging.md#top) * [Test cases and sections](test-cases-and-sections.md#top) * [Test fixtures](test-fixtures.md#top) -* [Skipping tests at runtime](skipping.md#top) +* [Explicitly skipping, passing, and failing tests at runtime](skipping-passing-failing.md#top) * [Reporters (output customization)](reporters.md#top) * [Event Listeners](event-listeners.md#top) * [Data Generators (value parameterized tests)](generators.md#top) diff --git a/docs/command-line.md b/docs/command-line.md index e7a448b1..e9a0f345 100644 --- a/docs/command-line.md +++ b/docs/command-line.md @@ -563,7 +563,7 @@ processes, as is done with the [Bazel test sharding](https://docs.bazel.build/ve By default, Catch2 test binaries return non-0 exit code if no tests were run, e.g. if the binary was compiled with no tests, the provided test spec matched no -tests, or all tests [were skipped at runtime](skipping.md#top). This flag +tests, or all tests [were skipped at runtime](skipping-passing-failing.md#top). This flag overrides that, so a test run with no tests still returns 0. ## Output verbosity diff --git a/docs/deprecations.md b/docs/deprecations.md index 5926f2c5..1fb79aaa 100644 --- a/docs/deprecations.md +++ b/docs/deprecations.md @@ -33,7 +33,7 @@ is deprecated and will be removed in the next major release. It is currently invoked for all test cases that are not going to be executed due to the test run being aborted (when using `--abort` or `--abortx`). It is however **NOT** invoked for test cases that are [explicitly skipped using the `SKIP` -macro](skipping.md#top). +macro](skipping-passing-failing.md#top). --- diff --git a/docs/skipping.md b/docs/skipping-passing-failing.md similarity index 61% rename from docs/skipping.md rename to docs/skipping-passing-failing.md index edd2a1a1..8ae52541 100644 --- a/docs/skipping.md +++ b/docs/skipping-passing-failing.md @@ -1,5 +1,7 @@ -# Skipping Test Cases at Runtime +# Explicitly skipping, passing, and failing tests at runtime + +## Skipping Test Cases at Runtime > [Introduced](https://github.com/catchorg/Catch2/pull/2360) in Catch2 X.Y.Z. @@ -7,7 +9,7 @@ In some situations it may not be possible to meaningfully execute a test case, f If the required conditions can only be determined at runtime, it often doesn't make sense to consider such a test case as either passed or failed, because it simply can not run at all. To properly express such scenarios, Catch2 allows to explicitly _skip_ test cases, using the `SKIP` macro: -**SKIP(** _message expression_ **)** +**SKIP(** [streamable expression] **)** Example usage: @@ -41,7 +43,7 @@ TEST_CASE("failing test") { } ``` -## Interaction with Sections and Generators +### Interaction with Sections and Generators Sections, nested sections as well as test cases with [generators](generators.md#top) can all be individually skipped, with the rest executing as usual: @@ -67,6 +69,46 @@ Note that as soon as one section is skipped, the entire test case will be report If all test cases in a run are skipped, Catch2 returns a non-zero exit code by default. This can be overridden using the [--allow-running-no-tests](command-line.md#no-tests-override) flag. + +## Passing and failing test cases + +Test cases can also be explicitly passed or failed, without the use of +assertions, and with a specific message. This can be useful to handle +complex preconditions/postconditions and give useful error messages +when they fail. + +* `SUCCEED( [streamable expression] )` + +`SUCCEED` is morally equivalent with `INFO( [streamable expression] ); REQUIRE( true );`. +Note that it does not stop further test execution, so it cannot be used +to guard failing assertions from being executed. + +_In practice, `SUCCEED` is usually used as a test placeholder, to avoid +[failing a test case due to missing assertions](command-line.md#warnings)._ + +```cpp +TEST_CASE( "SUCCEED showcase" ) { + int I = 1; + SUCCEED( "I is " << I ); + // ... execution continues here ... +} +``` + +* `FAIL( [streamable expression] )` + +`FAIL` is morally equivalent with `INFO( [streamable expression] ); REQUIRE( false );`. + +_In practice, `FAIL` is usually used to stop executing test that is currently +known to be broken, but has to be fixed later._ + +```cpp +TEST_CASE( "FAIL showcase" ) { + FAIL( "This test case causes segfault, which breaks CI." ); + // ... this will not be executed ... +} +``` + + --- [Home](Readme.md#top)