Checking exceptions

Functions for verifying exceptions in test cases. More...

Functions
template<class Callable_T> requires std::invocable<Callable_T&>
auto	micro_os_plus::micro_test_plus::nothrow (Callable_T &&func)
	Checks whether a callable does not throw any exception, for expect() or require().
template<class Callable_T> requires std::invocable<Callable_T&>
auto	micro_os_plus::micro_test_plus::throws (Callable_T &&func)
	Checks whether a callable throws any exception, for expect() or require().
template<class Exception_T, class Callable_T> requires std::invocable<Callable_T&>
auto	micro_os_plus::micro_test_plus::throws (Callable_T &&func)
	Checks whether a callable throws a specific exception, for expect() or require().

Detailed Description

Three functions check what a callable throws, and are used as the conditions of expect() or require():

• mt::throws (callable) is true when the callable throws any exception;
• mt::throws<E> (callable) is true when it throws an exception of type E, or of a type derived from it;
• mt::nothrow (callable) is true when it throws nothing.

The exception is caught by the check, so it does not leave the test case. When the check fails, the report states why, for example:

• throws<std::runtime_error>, but nothing was thrown;
• throws<std::runtime_error>, but a std::exception was thrown: "what", with the text returned by its what();
• nothrow, but an exception of unknown type was thrown.

A failed require() inside the callable is not an exception of the callable: it stops the test case, as it does elsewhere, and does not satisfy throws() or fail nothrow().

Example

ts.test ("Check if exceptions are thrown", [] (auto& t) {
  t.expect (mt::throws ([] { exercise_throw (true); }))
      << "exception thrown";
 
  t.expect (mt::throws<std::runtime_error> ([]
    { throw std::runtime_error{ "" }; }))
      << "std::runtime_error thrown";
 
  t.expect (mt::nothrow ([] { exercise_throw (false); }))
      << "exception not thrown";
});

Availability

The functions are declared only when the compiler defines __cpp_exceptions. In a build without exceptions (for example with -fno-exceptions), the code under test cannot throw, the functions do not exist, and a test case that calls them does not compile; guard such test cases with #if defined(__cpp_exceptions).

Several exception types

To accept one of several exception types, use a try block with a catch for each type, and report each outcome with expect (true) or expect (false). Check the normal path too, after the call in the try block; otherwise a call that throws nothing passes with no check:

ts.test ("Check exceptions explicitly", [] (auto& t) {
  try
    {
      compute_answer ();
      t.expect (false) << "no exception thrown";
    }
  catch (const std::overflow_error& e)
    {
      t.expect (true) << "std::overflow_error thrown";
    }
  catch (const std::runtime_error& e)
    {
      t.expect (true) << "std::runtime_error thrown";
    }
  catch (...)
    {
      t.expect (false) << "unknown exception thrown";
    }
});

Function Documentation

nothrow()

template<class Callable_T>
requires std::invocable<Callable_T&>

auto micro_os_plus::micro_test_plus::nothrow ( Callable_T && func )

nodiscard

Template Parameters

Callable_T

The type of the callable object to be invoked; it must be invocable without arguments, as an lvalue, so a mutable lambda is accepted.

Parameters

func	The callable object to check.

Returns

An object of an unspecified type, holding the result, to be passed to expect() or require().

The nothrow function template checks whether invoking the provided callable object does not result in the throwing of any exception. This is useful for ensuring that code under test does not unexpectedly signal error conditions.

The callable is invoked immediately, when the comparator is constructed; the result is reported when the comparator is passed to expect() or require(), which also accept optional messages.

Definition at line 116 of file exceptions-inlines.h.

  {
    return detail::nothrow_op{ func };
  }

References nothrow().

Referenced by nothrow().

throws() [1/2]

template<class Callable_T>
requires std::invocable<Callable_T&>

auto micro_os_plus::micro_test_plus::throws ( Callable_T && func )

nodiscard

The callable is invoked once, immediately. The check passes if it throws an exception of any type.

Template Parameters

Callable_T

The type of the callable object to be invoked; it must be invocable without arguments, as an lvalue, so a mutable lambda is accepted.

Parameters

func	The callable object to check for exception throwing behaviour.

Returns

An object of an unspecified type, holding the result, to be passed to expect() or require().

The throws function template checks whether invoking the provided callable object results in the throwing of any exception. This is useful for ensuring that code under test properly signals error conditions.

The callable is invoked immediately, when the comparator is constructed; the result is reported when the comparator is passed to expect() or require(), which also accept optional messages.

Definition at line 97 of file exceptions-inlines.h.

  {
    return detail::throws_op<>{ func };
  }

throws() [2/2]

template<class Exception_T, class Callable_T>
requires std::invocable<Callable_T&>

auto micro_os_plus::micro_test_plus::throws ( Callable_T && func )

nodiscard

The callable is invoked once, immediately. The check passes if it throws an exception of type Exception_T or of a type derived from it, so throws<std::exception>() passes for any standard exception. An exception of another type, or no exception, fails the check, and the report states what was thrown.

Template Parameters

Exception_T	The type of the exception expected to be thrown.
Callable_T	The type of the callable object to be invoked; it must be invocable without arguments, as an lvalue, so a mutable lambda is accepted.

Parameters

func	The callable object to check for exception throwing behaviour.

Returns

An object of an unspecified type, holding the result, to be passed to expect() or require().

The throws function template checks whether invoking the provided callable object results in the throwing of a specific exception type. This is useful for testing error handling in code under test. Exceptions of other types are reported as failures.

The callable is invoked immediately, when the comparator is constructed; the result is reported when the comparator is passed to expect() or require(), which also accept optional messages.

Definition at line 78 of file exceptions-inlines.h.

  {
    return detail::throws_op<Exception_T>{ func };
  }