3rd-party
/
catch2
mirror of https://github.com/catchorg/Catch2.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Reword the SKIP docs a bit

This commit is contained in:
Martin Hořeňovský 2023-01-12 18:56:02 +01:00
parent 16f48f8c7c
commit d59572f46f
No known key found for this signature in database
GPG Key ID: DE48307B8B0D381A
1 changed files with 26 additions and 11 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

37
docs/skipping-passing-failing.md
View File

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