Requirements

Requirements are checks that stop the test case when they fail. More...

Functions
template<class Expr_T> requires extension::checkable<Expr_T>
detail::check_result &&	micro_os_plus::micro_test_plus::test_case::require (const Expr_T &expr, const reflection::source_location &sl=reflection::source_location::current(), detail::check_result &&result=detail::check_result{})
	Checks a condition and, if false, stops the test case.

Detailed Description

t.require (condition) checks a condition as expect() does, and also stops the test case when it fails. Use it when the rest of the test case depends on the condition, for example to check that a pointer is not null before using it.

A failed requirement is reported and counted like a failed expectation. What follows depends on the build:

• with exceptions, the rest of the test case is skipped, and the run continues with the next test case; this is the behaviour of the fatal assertions of most C++ test frameworks (ASSERT_* in GoogleTest, REQUIRE() in Catch2 and doctest, BOOST_REQUIRE() in Boost.Test);
• without exceptions, a test case cannot be stopped alone, so the whole test run is aborted with runner::abort(), as Catch2 does: the results of the test case are written, ending with the failed requirement (followed, with the TAP reporter, by a Bail out! line), the remaining test cases do not run, and no totals are written. The process is then terminated with ::abort(), unless the application set another handler with runner::set_abort_handler().

Example

ts.test ("Check the buffer", [] (auto& t) {
  const char* buffer = get_buffer ();
  t.require (mt::ne (buffer, nullptr)) << "buffer allocated";
  t.expect (mt::eq (buffer[0], 'a'));
});

Function Documentation

require()

template<class Expr_T>
requires extension::checkable<Expr_T>

detail::check_result && micro_os_plus::micro_test_plus::test_case::require	(	const Expr_T &	expr,
		const reflection::source_location &	sl = reflection::source_location::current (),
		detail::check_result &&	result = detail::check_result{} )

The failure is reported and counted as for expect(); then, when exceptions are enabled, the rest of the test case body is skipped, and the run continues with the next test case, as ASSERT_* in GoogleTest, REQUIRE() in Catch2 and doctest, and BOOST_REQUIRE() in Boost.Test do. Without exceptions, the test execution is aborted with runner::abort().

The test case is stopped by throwing a private exception, at the end of the statement, after the optional message was appended. It is not derived from std::exception; a catch (...) in the test case body must rethrow it, and the body must not be noexcept.

Template Parameters

Expr_T

The type of the custom expression.

Constraints

Enabled only if Expr_T is a framework expression type or is contextually convertible to bool, including by an explicit operator bool (enforced via a C++20 requires clause, with extension::checkable).

Parameters

expr	Logical expression to evaluate.
sl	Optional source location, defaulting to the current line.
result	The check result, a temporary created by the caller as the default argument, which the applications do not pass; it is destroyed at the end of the statement.

Returns

A reference to the check result, to which optional messages can be appended with operator<<; the check is reported when it is destroyed, at the end of the statement.

Warning

The result must not be named, stored, or kept in any variable. A reference such as auto&& r = t.expect (...) compiles, but dangles after the statement; the message operator and value() can be called only on a temporary, so the named result cannot be used, and forcing it with std::move() is undefined. The check must be reported at the end of the statement, and not later. Write the message in the same statement, with operator<<.

Initialises the detail::check_result received as the last argument, a temporary created by the caller, with the kind detail::check_kind::requirement, and returns a reference to it. The check result evaluates the condition when initialised, records a pass or fail when it is destroyed, and, if the condition is false, stops the test case by throwing detail::failed_requirement (caught by test_case::run()), or, without exceptions, aborts the test execution.

Definition at line 683 of file test-inlines.h.

  {
    if (is_misdirected ()) [[unlikely]]
      {
        return report_misdirected (detail::check_kind::requirement, sl,
                                   std::move (result));
      }
 
    result.init (expr, detail::check_kind::requirement, sl, *this,
                 test_reporter ().expression_,
                 test_reporter ().writes_passed_checks ());
    return std::move (result);
  }

References micro_os_plus::micro_test_plus::detail::check_result::init(), is_misdirected(), report_misdirected(), micro_os_plus::micro_test_plus::detail::requirement, and micro_os_plus::micro_test_plus::detail::runnable_base::test_reporter().

Referenced by assume().