diff options
| author | Martin Hořeňovský | 2025-09-21 11:19:18 +0200 |
|---|---|---|
| committer | Martin Hořeňovský | 2025-09-22 14:02:45 +0200 |
| commit | 8ed8c431c601c7b303dbfe7eb412a63f1641b812 (patch) | |
| tree | 4e23dd0b60bfb09b58bb5bac770965c83243c569 /docs | |
| parent | dc3a4ea41a78c643fbfa07b1cb456738c9e25ef6 (diff) | |
| download | catch3-8ed8c431c601c7b303dbfe7eb412a63f1641b812.tar.gz | |
Support Bazel's TEST_PREMATURE_EXIT_FILE and add it to CLI as well
This tells Catch2 to create an empty file at specified path before
the tests start, and delete it after the tests finish. This allows
callers to catch cases where the test binary silently exits before
finishing (e.g. via call to `exit(0)` inside the code under test),
by looking whether the file still exists.
Closes #3020
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/ci-and-misc.md | 3 | ||||
| -rw-r--r-- | docs/command-line.md | 16 |
2 files changed, 19 insertions, 0 deletions
diff --git a/docs/ci-and-misc.md b/docs/ci-and-misc.md index 49bbd989..d2ef3fd7 100644 --- a/docs/ci-and-misc.md +++ b/docs/ci-and-misc.md @@ -66,11 +66,14 @@ test execution. Specifically it understands * JUnit output path via `XML_OUTPUT_FILE` * Test filtering via `TESTBRIDGE_TEST_ONLY` * Test sharding via `TEST_SHARD_INDEX`, `TEST_TOTAL_SHARDS`, and `TEST_SHARD_STATUS_FILE` + * Creating a file to signal premature test exit via `TEST_PREMATURE_EXIT_FILE` > Support for `XML_OUTPUT_FILE` was [introduced](https://github.com/catchorg/Catch2/pull/2399) in Catch2 3.0.1 > Support for `TESTBRIDGE_TEST_ONLY` and sharding was introduced in Catch2 3.2.0 +> Support for `TEST_PREMATURE_EXIT_FILE` was introduced in Catch2 X.Y.Z + This integration is enabled via either a [compile time configuration option](configuration.md#bazel-support), or via `BAZEL_TEST` environment variable set to "1". diff --git a/docs/command-line.md b/docs/command-line.md index 73b94f6c..651efd01 100644 --- a/docs/command-line.md +++ b/docs/command-line.md @@ -32,6 +32,7 @@ [Test Sharding](#test-sharding)<br> [Allow running the binary without tests](#allow-running-the-binary-without-tests)<br> [Output verbosity](#output-verbosity)<br> +[Create file to guard against silent early termination](#create-file-to-guard-against-silent-early-termination)<br> Catch works quite nicely without any command line options at all - but for those times when you want greater control the following options are available. Click one of the following links to take you straight to that option - or scroll on to browse the available options. @@ -649,6 +650,21 @@ ignored. Verbosity defaults to _normal_. +## Create file to guard against silent early termination +<pre>--premature-exit-guard-file <path></pre> + +> Introduced in Catch2 X.Y.Z + +Tells Catch2 to create an empty file at specified path before the tests +start, and delete it after the tests finish. If the file is present after +the process stops, it can be assumed that the testing binary exited +prematurely, e.g. due to the OOM killer. + +All directories in the path must already exist. If this option is used +and Catch2 cannot create the file (e.g. the location is not writable), +the test run will fail. + + --- [Home](Readme.md#top) |