The result of one check, reported when destroyed. More...

#include "micro-os-plus/micro-test-plus.h"

Public Member Functions
	check_result (check_result &&)=delete
	Deleted move constructor to prevent moving.
	check_result (const check_result &)=delete
	Deleted copy constructor to prevent copying.
	check_result (void)
	Constructs a result in the initial state.
	~check_result () noexcept(false)
	Destructor that reports the check.
template<class Expr_T>
void	init (const Expr_T &expr, check_kind kind, const reflection::source_location &location, test_case &test_case, expression_formatter &expression, bool writes_passed)
	Initialises the result with the check of an expression.
template<class T> requires detail::message_argument<T>
check_result &&	operator<< (const T &msg) &&
	Appends a message to the check.
check_result &	operator= (check_result &&)=delete
	Deleted move assignment operator to prevent moving.
check_result &	operator= (const check_result &)=delete
	Deleted copy assignment operator to prevent copying.
bool	value (void) const &&noexcept
	Retrieves the result value.

Private Member Functions
void	start (bool value, check_kind kind, bool has_expression, const reflection::source_location &location, test_case &test_case, bool writes_passed)
	Starts the result of a check from its parts.

Private Attributes
failure_info	info_
	The details displayed when the check fails.
bool	is_written_ = false
	Whether the outcome of the check is written.
test_case *	test_case_ = nullptr
	Pointer to the test case invoking this check.
int	uncaught_exceptions_ = 0
	The number of uncaught exceptions when the check was created.
bool	value_ = false
	Stores the result value of the check.

Detailed Description

Created by the caller of expect() and require() as a temporary, the defaulted last argument of these functions, it lives until the end of the expression statement, and the functions return a reference to it, so that a result cannot be kept in a variable (auto r = t.expect (...) does not compile). The check is reported when the result is destroyed, at the end of the statement, in the order of the statements, and not later.

Warning: The result must never be named: a reference bound to it (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 messages are appended in the same statement.

A result in the initial state, not yet initialised, reports nothing.

Its template function init() evaluates the expression and formats it, with the actual operand values, into the expression formatter of the reporter, which keeps the text for this check until it is reported, so that it can be displayed on failure. The messages passed via operator<<() are collected into a string. The destructor reports the outcome, updates the counters of the test case, and, after a failed require(), stops the test case.

A passed check whose line the reporter never writes (see reporter::writes_passed_checks()) formats neither its expression nor its messages; it is counted, and passed to reporter::pass_without_text(), which records only its test point.

Only the template function init() depends on the type of the expression; it delegates to a private non-template function, and the destructor, which does the reporting, is not a template either, so this code is compiled once, in src/check-result.cpp, not for each type of expression.

Definition at line 208 of file check-result.h.

Constructor & Destructor Documentation

◆ check_result() [1/3]

micro_os_plus::micro_test_plus::detail::check_result::check_result ( void )

default

Used for the temporary that the caller of expect() and require() creates as their defaulted argument; the result reports nothing unless it is initialised by init(). Defined in src/check-result.cpp, so that the call sites only call it.

The members have their initial values: the result is not initialised, has no test case, and its destructor reports nothing.

References init().

Referenced by check_result(), check_result(), operator<<(), operator=(), and operator=().

◆ check_result() [2/3]

micro_os_plus::micro_test_plus::detail::check_result::check_result ( const check_result & )

delete

Each instance reports exactly one check, from its destructor; a copy would report it twice.

References check_result().

◆ check_result() [3/3]

micro_os_plus::micro_test_plus::detail::check_result::check_result ( check_result && )

delete

The instance is a temporary that lives only until the end of the expression statement; the functions that fill it return a reference to it, so that a result cannot be kept in a variable.

References check_result().

◆ ~check_result()

micro_os_plus::micro_test_plus::detail::check_result::~check_result ( )

It may throw failed_requirement, after a failed require(), to stop the test case, hence noexcept (false).

The destructor reports the result of the check, at the end of the expression statement, after all the user messages were appended.

The test point number of the test case is advanced first, so that the check numbers follow the order in which the checks are reported (the first check is reported as check #1), also when a check is reported after checks that began later, such as those made by a function called in its arguments.

If the evaluated expression is true, the reporter records a successful outcome along with any accumulated message, or, if it does not write the passed checks, only the test point, with reporter::pass_without_text(), and the passed checks counter of the test case is incremented. If the expression is false, the reporter records a failure, with the failure details (the kind of the check, the message, and the source location) and the expression, and the failed checks counter is incremented.

The expression text is obtained from the expression formatter with check_text(), which returns the text of this check even if later checks used the formatter, and is released with end_check().

If the check is a require() and the test expression has failed, the test case is stopped: when exceptions are enabled, by throwing failed_requirement, caught by test_case::run(), as the fatal assertions of most C++ test frameworks do; the run then continues with the next test case. If the destructor runs during stack unwinding (caused by an exception thrown while the rest of the statement is evaluated, such as by the argument of a message), it does not throw, since the test case is already being stopped.

Without exceptions, the test execution is aborted via the runner, whose reporter writes the buffered test output, in place of the end_test_case() that is never reached (see runner::abort()).

Definition at line 139 of file check-result.cpp.

    {
#if defined(MICRO_OS_PLUS_MICRO_TEST_PLUS_TRACE_CONSTRUCTORS_ENABLED)
      trace::printf ("%s\n", __PRETTY_FUNCTION__);
#endif // MICRO_OS_PLUS_MICRO_TEST_PLUS_TRACE_CONSTRUCTORS_ENABLED
 
      // A result that was not initialised, such as a default argument
      // whose function did not run, reports nothing.
      if (test_case_ == nullptr) [[unlikely]]
        {
          return;
        }
 
      // The index starts at 0; it must be incremented before the check is
      // reported, so that the first check is reported as check #1.
      test_case_->next_test_point_number ();
 
      // The text formatted by this check, even if the formatter was used by
      // other checks in the meantime (when this result was kept).
      auto& expression = test_case_->test_reporter ().expression_;
      const std::string& expression_str = expression.check_text (this);
 
      if (value_) [[likely]]
        {
          if (is_written_)
            {
              test_case_->test_reporter ().pass (info_.message, expression_str,
                                                 *test_case_);
            }
          else
            {
              test_case_->test_reporter ().pass_without_text (*test_case_);
            }
          test_case_->totals_.increment_passed_checks ();
        }
      else
        {
          test_case_->test_reporter ().fail (info_, expression_str,
                                             *test_case_);
          test_case_->totals_.increment_failed_checks ();
        }
 
      expression.end_check (this);
 
      if (info_.kind == check_kind::requirement && !value_) [[unlikely]]
        {
#if defined(__cpp_exceptions)
          if (std::uncaught_exceptions () <= uncaught_exceptions_)
            {
              throw failed_requirement{};
            }
#else
          test_case_->abort (info_.location);
#endif // defined(__cpp_exceptions)
        }
    }

Member Function Documentation

◆ init()

template<class Expr_T>

void micro_os_plus::micro_test_plus::detail::check_result::init	(	const Expr_T &	expr,
		check_kind	kind,
		const reflection::source_location &	location,
		test_case &	test_case,
		expression_formatter &	expression,
		bool	writes_passed )

The expression is evaluated, and, if the outcome is written, formatted into the expression formatter.

Template Parameters

Expr_T The type of the expression.

Parameters

expr	The expression under evaluation.
kind	The kind of the check, check_kind::requirement for require(), whose failure stops the test case.
location	The source location of the check.
test_case	The test case that owns this check.
expression	The expression formatter to format the expression text.
writes_passed	Whether the reporter writes the passed checks; if not, a passed check is not formatted.

Returns: Nothing.

The expression is evaluated, and the result is passed, together with the kind of the check and whether the expression is a framework comparator, to the non-template start(), which also stores the source location and the test case. The kind, check_kind::requirement for require(), determines whether the test case is stopped if the check fails.

The expression formatter of the reporter, which is shared by all checks, is then assigned to this check by begin_check(), which sets aside the text of a previous check not yet reported, if any. The expression is formatted into it only when the outcome is written: on failure, or, if writes_passed, also on success. Otherwise the text of this check stays empty, and the operands, which may be application types with an expensive operator<<, are not formatted.

An expression that is only explicitly convertible to bool, such as a std::optional or a std::unique_ptr, is written as the result of the conversion, true or false, since that is what the check tested; its own value (the contents of a std::optional<bool>, for example) could contradict the outcome, and many such types cannot be formatted at all.

The decision is taken here, while the operands are alive.

Definition at line 102 of file check-result-inlines.h.

    {
      start (static_cast<bool> (expr), kind, extension::is_op<Expr_T>,
             location, test_case, writes_passed);
 
#if defined(MICRO_OS_PLUS_MICRO_TEST_PLUS_TRACE_CONSTRUCTORS_ENABLED)
      trace::printf ("%s\n", __PRETTY_FUNCTION__);
#endif // MICRO_OS_PLUS_MICRO_TEST_PLUS_TRACE_CONSTRUCTORS_ENABLED
 
      // The same address is used by the destructor, to retrieve the text,
      // even if other checks used the formatter in the meantime.
      expression.begin_check (this);
 
      if (is_written_)
        {
          if constexpr (extension::is_op<Expr_T>
                        or std::convertible_to<Expr_T, bool>)
            {
              expression << expr;
            }
          else
            {
              expression << static_cast<bool> (expr);
            }
        }
    }

References micro_os_plus::micro_test_plus::detail::expression_formatter::begin_check(), is_written_, and start().

Referenced by check_result(), micro_os_plus::micro_test_plus::test_case::expect(), micro_os_plus::micro_test_plus::test_case::report_rejected_test(), and micro_os_plus::micro_test_plus::test_case::require().

◆ operator<<()

template<class T>
requires detail::message_argument<T>

check_result && micro_os_plus::micro_test_plus::detail::check_result::operator<< ( const T & msg ) &&

Callable only on a temporary, like the result of expect() and require(), which is destroyed at the end of the statement: a result bound to a name (auto&& r = t.expect (...)) is not usable, since it would refer to a destroyed object after the statement.

Template Parameters

T	The type of the message to append: a value that the formatter can write, or a callable object that returns one (see detail::message_argument); any other argument is rejected at compile time, with a message that states what is accepted.

Parameters

msg	The message to append, or the callable object that returns it, called only if the check fails.

Returns: The current check result, as an rvalue reference, so that further messages can be appended in the same expression.

This operator overload enables the check result to accumulate expectation messages by appending the provided value to the internal message string.

The value is written by the same operator<< overloads as the operands of the expressions, so that both accept the same types, including the application types with an operator<< for the formatter. The message is moved into a local formatter in the plain mode, which writes the numbers without the type suffixes, and the strings and the char values without quotes, with only the control characters that can change the state of a terminal escaped, and is moved back after the value is appended, so that no other buffer is allocated. The formatter of the reporter is not used, since it may hold the expression of this check, or of a pending one.

When the outcome of the check is not written, the message is not needed, and the value is not formatted.

A callable object (see detail::lazy_message) is called only if the check failed, and its result is appended as a value; after a success, even if the outcome is written, it appends nothing, since its purpose is to describe a failure with values that may not be valid otherwise, like the error of a std::expected that holds a value. Being a class type, a lambda without captures is called too, although it is also printable, as a bool.

Definition at line 177 of file check-result-inlines.h.

    {
      if constexpr (detail::lazy_message<T>)
        {
          if (value_)
            {
              return std::move (*this);
            }
        }
      else
        {
          if (!is_written_)
            {
              return std::move (*this);
            }
        }
 
      expression_formatter formatter{ std::move (info_.message) };
      if constexpr (detail::lazy_message<T>)
        {
          formatter << std::invoke (msg);
        }
      else
        {
          formatter << msg;
        }
      info_.message = std::move (formatter.buffer_);
      return std::move (*this);
    }

References check_result(), micro_os_plus::micro_test_plus::detail::expression_formatter::buffer_, info_, is_written_, and value_.

◆ operator=() [1/2]

check_result & micro_os_plus::micro_test_plus::detail::check_result::operator= ( check_result && )

delete

Each instance reports exactly one check, from its destructor.

References check_result(), start(), and value().

◆ operator=() [2/2]

check_result & micro_os_plus::micro_test_plus::detail::check_result::operator= ( const check_result & )

delete

Each instance reports exactly one check, from its destructor.

References check_result().

◆ start()

void micro_os_plus::micro_test_plus::detail::check_result::start	(	bool	value,
		check_kind	kind,
		bool	has_expression,
		const reflection::source_location &	location,
		test_case &	test_case,
		bool	writes_passed )

private

The non-template part of the initialisation, shared by all the instantiations of the template function init(), which calls it. Marks the result as initialised, so that the destructor reports it.

Parameters

value	The result of the evaluated expression.
kind	The kind of the check.
has_expression	Indicates whether the expression is a framework comparator, whose text is displayed on failure.
location	The source location of the check.
test_case	The test case that owns this check.
writes_passed	Whether the reporter writes the passed checks.

Returns: Nothing.

Stores the evaluated Boolean value, and, in the failure details, the kind of the check, the has_expression flag, and the location identifying the source line of the check, with an empty message; it also stores a pointer to the owning test_case, which marks the result as initialised. The outcome is written when the check failed, or when the reporter writes the passed checks (writes_passed). The check number is assigned later, by the destructor, when the check is reported.

When exceptions are enabled, the number of uncaught exceptions is also stored, so that the destructor can tell whether it runs during stack unwinding.

Definition at line 89 of file check-result.cpp.

    {
      value_ = value;
      is_written_ = !value || writes_passed;
      info_ = failure_info{ kind, {}, has_expression, location };
      test_case_ = &test_case;
#if defined(__cpp_exceptions)
      uncaught_exceptions_ = std::uncaught_exceptions ();
#endif // defined(__cpp_exceptions)
    }

References info_, is_written_, test_case_, uncaught_exceptions_, value(), and value_.

Referenced by init(), and operator=().

◆ value()

bool micro_os_plus::micro_test_plus::detail::check_result::value ( void ) const &&

inlinenodiscardnoexcept

Callable only on a temporary, for the reason given for operator<<().

Parameters: None.

Return values

true	The checked condition was met.
false	The checked condition was not met.

Returns the result value stored in value_.

Definition at line 139 of file check-result-inlines.h.

    {
      return value_;
    }

References value_.

Referenced by operator=(), and start().

Member Data Documentation

◆ info_

failure_info micro_os_plus::micro_test_plus::detail::check_result::info_

private

The kind, the expression flag, and the location are set by start(); the message is collected via operator<<(). Passed to the reporter by the destructor; the message is also displayed when the check passes.

Definition at line 412 of file check-result.h.

Referenced by ~check_result(), operator<<(), and start().

◆ is_written_

bool micro_os_plus::micro_test_plus::detail::check_result::is_written_ = false

private

Set by start() for a failed check, and for a passed one when the reporter writes the passed checks. When not set, the expression and the messages are not formatted, and the destructor only updates the counters.

Definition at line 401 of file check-result.h.

Referenced by ~check_result(), init(), operator<<(), and start().

◆ test_case_

test_case* micro_os_plus::micro_test_plus::detail::check_result::test_case_ = nullptr

private

Provides access to the reporter and to the totals to be updated. Null in the initial state, which marks a result that was not initialised and reports nothing.

Definition at line 436 of file check-result.h.

Referenced by ~check_result(), and start().

◆ uncaught_exceptions_

int micro_os_plus::micro_test_plus::detail::check_result::uncaught_exceptions_ = 0

private

If the destructor finds more, it runs during stack unwinding (an exception was thrown while the rest of the statement was evaluated, for example by the argument of a message), and must not throw. Present only when exceptions are enabled.

Definition at line 425 of file check-result.h.

Referenced by ~check_result(), and start().

◆ value_

bool micro_os_plus::micro_test_plus::detail::check_result::value_ = false

private

The boolean value of the checked expression, computed by the template function init().

Definition at line 390 of file check-result.h.

Referenced by ~check_result(), operator<<(), start(), and value().

The documentation for this class was generated from the following files:

Public Member Functions

Private Member Functions

Private Attributes

Detailed Description

Constructor & Destructor Documentation

◆ check_result() [1/3]

◆ check_result() [2/3]

◆ check_result() [3/3]

◆ ~check_result()

Member Function Documentation

◆ init()

◆ operator<<()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ start()

◆ value()

Member Data Documentation

◆ info_

◆ is_written_

◆ test_case_

◆ uncaught_exceptions_

◆ value_