From d59572f46fb4b9cbd720dd4298bf97931fc33c3b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Martin=20Ho=C5=99e=C5=88ovsk=C3=BD?= Date: Thu, 12 Jan 2023 18:56:02 +0100 Subject: [PATCH] Reword the SKIP docs a bit --- docs/skipping-passing-failing.md | 37 ++++++++++++++++++++++---------- 1 file changed, 26 insertions(+), 11 deletions(-) diff --git a/docs/skipping-passing-failing.md b/docs/skipping-passing-failing.md index 8ae52541..72c9f775 100644 --- a/docs/skipping-passing-failing.md +++ b/docs/skipping-passing-failing.md @@ -5,11 +5,18 @@ > [Introduced](https://github.com/catchorg/Catch2/pull/2360) in Catch2 X.Y.Z. -In some situations it may not be possible to meaningfully execute a test case, for example when the system under test is missing certain hardware capabilities. -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: +In some situations it may not be possible to meaningfully execute a test case, +for example when the system under test is missing certain hardware capabilities. +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. -**SKIP(** [streamable expression] **)** +To properly express such scenarios, Catch2 provides a way to explicitly +_skip_ test cases, using the `SKIP` macro: + +``` +SKIP( [streamable expression] ) +``` Example usage: @@ -24,7 +31,8 @@ TEST_CASE("copy files between drives") { This test case is then reported as _skipped_ instead of _passed_ or _failed_. -The `SKIP` macro behaves similarly to an explicit [`FAIL`](logging.md#top), in that it is the last expression that will be executed: +The `SKIP` macro behaves similarly to an explicit [`FAIL`](#passing-and-failing-test-cases), +in that it is the last expression that will be executed: ```c++ TEST_CASE("my test") { @@ -34,7 +42,8 @@ TEST_CASE("my test") { } ``` -However a failed assertion _before_ a `SKIP` still causes the entire test case to fail: +However a failed assertion _before_ a `SKIP` still causes the entire +test case to fail: ```c++ TEST_CASE("failing test") { @@ -45,7 +54,8 @@ TEST_CASE("failing test") { ### 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: +Sections, nested sections as well as specific outputs from [generators](generators.md#top) +can all be individually skipped, with the rest executing as usual: ```c++ TEST_CASE("complex test case") { @@ -62,12 +72,17 @@ TEST_CASE("complex test case") { } ``` -This test case will report 5 passing assertions; one for each of the three values in section `a1`, as well as one for each in `a2`, except for when `value == 4`. +This test case will report 5 passing assertions; one for each of the three +values in section `a1`, and then two in section `a2`, from values 2 and 4. -Note that as soon as one section is skipped, the entire test case will be reported as _skipped_ (unless there is a failing assertion, in which case it will be reported as _failed_ instead). +Note that as soon as one section is skipped, the entire test case will +be reported as _skipped_ (unless there is a failing assertion, in which +case the test is handled as _failed_ instead). -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. +Note that if all test cases in a run are skipped, Catch2 returns a non-zero +exit code, same as it does if no test cases have run. This behaviour can +be overridden using the [--allow-running-no-tests](command-line.md#no-tests-override) +flag. ## Passing and failing test cases