iox-#1613 Extend error handling design document and add example code

Author: elBoberido

doc/design/error-handling.md

@@ -264,6 +264,23 @@ auto errorFunc = [](Error& error) {
 func(arg).and_then(successFunc).or_else(errorFunc);
 ```
 
+### Testing fatal error
+
+For fatal errors the error handler will terminate the execution of the binary. In order to test these paths the
+`iox::testing::IOX_EXPECT_FATAL_FAILURE` function should be used instead of the `EXPECT_DEATH` gTest macro.
+The `EXPECT_DEATH` gTest macro forks the process which slows down the test execution (especially with the ThreadSanitizer enabled)
+and causes issues with running thread. The `IOX_EXPECT_FATAL_FAILURE` registers a temporary error handler and runs the provided
+function in a separate thread. When the error handler is called `longjmp` is used to prevent the termination and instead ensures
+to gracefully shutdown the thread.
+
+```cpp
+#include "iceoryx_hoofs/testing/fatal_failure.hpp"
+TEST(MyTest, valueOnNulloptIsFatal) {
+    iox::optional<bool> sut;
+    IOX_EXPECT_FATAL_FAILURE<iox::HoofsError>([&] { sut.value(); }, iox::HoofsError::EXPECTS_ENSURES_FAILED);
+}
+```
+
 ## Open points
 
 ### Centralized error handling

iceoryx_hoofs/testing/include/iceoryx_hoofs/testing/fatal_failure.hpp

@@ -84,6 +84,12 @@ bool FATAL_FAILURE_TEST(const std::function<void()>& testFunction,
 
 /// @brief This function is used in cases a fatal failure is expected. The function only works in combination with the
 /// iceoryx error handler.
+/// @code
+/// TEST(MyTest, valueOnNulloptIsFatal) {
+///     iox::optional<bool> sut;
+///     IOX_EXPECT_FATAL_FAILURE<iox::HoofsError>([&] { sut.value(); }, iox::HoofsError::EXPECTS_ENSURES_FAILED));
+/// }
+/// @endcode
 /// @tparam[in] ErrorType The error type which is expected, e.g. 'iox::HoofsError'
 /// @param[in] testFunction This function will be executed as SUT and is not expected to call the error handler
 /// @param[in] expectedError The error value which triggered the fatal failure
@@ -102,6 +108,12 @@ bool IOX_EXPECT_FATAL_FAILURE(const std::function<void()>& testFunction, const E
 
 /// @brief This function is used in cases no fatal failure is expected but could potentially occur. The function only
 /// works in combination with the iceoryx error handler.
+/// @code
+/// TEST(MyTest, valueIsNotFatal) {
+///     iox::optional<bool> sut{false};
+///     IOX_EXPECT_NO_FATAL_FAILURE<iox::HoofsError>([&] { sut.value(); });
+/// }
+/// @endcode
 /// @tparam[in] ErrorType The error type which is expected if the test fails, e.g. 'iox::HoofsError'
 /// @param[in] testFunction This function will be executed as SUT and is not expected to call the error handler
 /// @return true if no fatal failure occurs, false otherwise
@@ -111,8 +123,8 @@ bool IOX_EXPECT_NO_FATAL_FAILURE(const std::function<void()>& testFunction)
     return !detail::FATAL_FAILURE_TEST<ErrorType>(
         testFunction,
         [&](const auto error, const auto errorLevel) {
-            GTEST_FAIL() << "Expected no fatal failure but execution failed! Error code: " << error
-                         << "; Error level: " << errorLevel;
+            GTEST_FAIL() << "Expected no fatal failure but execution failed! Error code: "
+                         << static_cast<uint64_t>(error) << "; Error level: " << static_cast<uint64_t>(errorLevel);
         },
         [&] {});
     return false;