`test_case` Class

A named, runnable test case that lives inside a suite. More...

Declaration

class micro_os_plus::micro_test_plus::test_case { ... }

Included Headers

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

Base class

class	runnable_base
	Non-template base for all runnable objects (suites and test cases). More...

Friends Index

class	detail::runnable_base
	The base of the nodes, which creates the test cases. More...

class	micro_test_plus::runner
	The runner, which reports the rejected calls as failed checks of the running test case. More...

Public Constructors Index

	test_case (const test_case &)=delete
	Deleted copy constructor to prevent copying. More...

	test_case (test_case &&)=delete
	Deleted move constructor to prevent moving. More...

Private Constructors Index

	test_case (const located_name &name, runner &test_runner, suite &parent_suite, size_t own_index, size_t nesting_depth, detail::callable_ref< test_case > body)
	Constructs a test case with a name, runner, parent suite, index, nesting depth, and body. More...

Public Destructor Index

	~test_case () override
	Virtual destructor. More...

Public Operators Index

test_case &	operator= (const test_case &)=delete
	Deleted copy assignment operator to prevent copying. More...

test_case &	operator= (test_case &&)=delete
	Deleted move assignment operator to prevent moving. More...

Public Member Functions Index

const char *	name (void) const noexcept
	Returns the node name. More...

size_t	nesting_depth (void) const noexcept
	Returns the nesting depth of this test case. More...

template <typename Callable_T, typename... Args_T>
void	test (const located_name &name, Callable_T &&callable, Args_T &&... arguments)
	Adds a nested test case to this test case, and runs it. More...

template <typename T, typename Callable_T>
void	test_each (const located_name &name, std::initializer_list< T > values, Callable_T &&callable)
	Adds a nested test case for each value of a braced list, and runs them. More...

template <typename Values_T, typename Callable_T>
void	test_each (const located_name &name, Values_T &&values, Callable_T &&callable)
	Adds a nested test case for each value of a range or a tuple, and runs them. More...

const counters &	totals (void) const noexcept
	Returns the totals of the node. More...

template <class Expr_T>
detail::check_result &&	expect (const Expr_T &expr, const reflection::source_location &sl=reflection::source_location::current(), detail::check_result &&result=detail::check_result{})
	Evaluates a condition and reports the result. More...

template <class Expr_T>
detail::check_result &&	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. More...

Protected Member Functions Index

bool	accepts_test_case (const suite &target, const located_name &name)
	Checks whether a test case can be created on a suite. More...

void	after_test_case_create (class test_case &test_case, suite &suite)
	Counts a newly constructed child test case and executes it immediately. More...

template <typename Callable_T, typename... Args_T>
void	create_test_case (const located_name &name, suite &parent_suite, size_t nesting_depth, Callable_T &&callable, Args_T &&... arguments)
	Creates a child test case, and runs it. More...

suite *	exchange_running_suite (suite *running) noexcept
	Replaces the suite whose body is running in the owning runner, and returns the previous one. More...

bool	has_running_test_case_of (const suite &target) const noexcept
	Checks whether the innermost running test case belongs to a suite. More...

bool	is_aborted (void) const noexcept
	Checks whether the test execution was aborted by the owning runner. More...

bool	is_listing (void) const noexcept
	Checks whether the owning runner lists the test cases instead of running them. More...

size_t	next_test_point_number (void) noexcept
	Advances to the next child test point, and returns its number. More...

void	reject_body_exception (void)
	Reports the exception that escaped the body of a suite while the test cases are listed, and records it. More...

class test_case *	running_test_case (void) const noexcept
	Returns the innermost test case being run by the owning runner, if any. More...

class reporter &	test_reporter (void) const noexcept
	Returns the test reporter associated with this test runnable. More...

runner &	test_runner (void) const noexcept
	Returns the test runner that owns this test runnable. More...

Private Member Functions Index

void	abort (const reflection::source_location &sl=reflection::source_location::current()) const
	Aborts test execution via the owning runner, for a failed requirement. More...

void	fail_unexpected_exception (const char *what)
	Reports an exception that escaped the test case body as a failed check. More...

bool	is_misdirected (void) const noexcept
	Tells whether another test case is running. More...

detail::check_result &&	report_misdirected (detail::check_kind kind, const reflection::source_location &sl, detail::check_result &&result)
	Reports a check on this test case as a failure of the running one. More...

void	report_misdirected_test (const located_name &name)
	Reports a nested test case started on this test case as a failure of the running one. More...

void	report_rejected_test (const std::string &message, const reflection::source_location &location)
	Reports a rejected call as a failed check of this test case. More...

void	run (void) override
	Executes the test case body by invoking the referred callable. More...

Protected Member Attributes Index

size_t	child_test_cases_count_ = 0
	The number of direct child test cases. More...

const char *	name_
	The node name. More...

size_t	own_index_
	The test index, counting from 1. More...

runner &	runner_
	Reference to the test runner that owns this object. More...

size_t	test_point_number_ = 0
	The number of the most recent child test point. More...

counters	totals_
	Totals for the node. More...

Private Member Attributes Index

detail::callable_ref< test_case >	callable_
	Reference to the test case body, with any bound arguments. More...

const located_name &	located_name_
	The name and the location of the call to test() that created this test case. More...

size_t	nesting_depth_
	The nesting depth of this test case within the suite. More...

suite &	parent_suite_
	Reference to the parent suite that owns this test case. More...

Deprecated Functions Index

template <class Expr_T>
detail::check_result &&	expect (const Expr_T &expr, const reflection::source_location &sl=reflection::source_location::current(), detail::check_result &&result=detail::check_result{})
	Deprecated expect() of a suspicious condition. More...

template <class Expr_T>
detail::check_result &&	require (const Expr_T &expr, const reflection::source_location &sl=reflection::source_location::current(), detail::check_result &&result=detail::check_result{})
	Deprecated require() of a suspicious condition. More...

template <class Expr_T>
detail::check_result &&	assume (const Expr_T &expr, const reflection::source_location &sl=reflection::source_location::current(), detail::check_result &&result=detail::check_result{})
	Deprecated name of require(). More...

Deprecated Functions of runnable_base Index

size_t	own_index (void) const noexcept
	Deprecated positional index of this node within its parent. More...

size_t	current_subtest_index (void) const noexcept
	Deprecated number of the most recent child test point. More...

size_t	children_subtests_count (void) const noexcept
	Deprecated number of direct child test cases of this node. More...

Description

A named, runnable test case that lives inside a suite.

test_case represents a single, named test case or a nested group of checks within a parent suite or test_case. It is constructed by calling suite::test() or test_case::test(), both of which create the object, immediately execute its callable body via run(), and register the result with the parent node. The object is local to the test() call, and is destroyed when it returns, together with the body and the copies of its arguments, which are also local to that call; the test case only refers to them, so no memory is allocated for them.

The body of the test case is supplied as a callable (typically a lambda) that receives a test_case& reference as its first argument. Inside the body, expect() and require() are used to evaluate conditions and record the results. Test cases may be nested to an arbitrary depth.

The constructor is private, since its parameters are set by the framework; the test cases are created only by suite::test() and test_case::test().

The class is non-copyable and non-movable to preserve unique ownership and consistent state throughout the test session.

Definition at line 1361 of file test.h.

Friends

detail::runnable_base

friend class detail::runnable_base

The base of the nodes, which creates the test cases.

It constructs the test cases, whose constructor is private, and runs them after their creation.

Definition at line 1382 of file test.h.

1382 friend class detail::runnable_base;

References micro_test_plus::runner, micro_os_plus::micro_test_plus::detail::runnable_base::name, nesting_depth, micro_os_plus::micro_test_plus::detail::runnable_base::own_index and micro_os_plus::micro_test_plus::detail::runnable_base::test_runner.

Referenced by test_case.

micro_test_plus::runner

friend class micro_test_plus::runner

The runner, which reports the rejected calls as failed checks of the running test case.

runner::reject_call() calls the private report_rejected_test(), at the location of the rejected call, if known, or otherwise at the location of the test case, which it reads from the private located_name_.

Definition at line 1373 of file test.h.

1373 friend class micro_test_plus::runner;

Referenced by test_case and detail::runnable_base.

Public Constructors

test_case()

micro_os_plus::micro_test_plus::test_case::test_case (const test_case &)

delete

Deleted copy constructor to prevent copying.

A copy would duplicate the counters.

Definition at line 1416 of file test.h.

Reference test_case.

test_case()

micro_os_plus::micro_test_plus::test_case::test_case (test_case &&)

delete

Deleted move constructor to prevent moving.

Nodes are referred to by address (e.g. by their children and by the runner), so they must not be relocated.

Definition at line 1425 of file test.h.

Reference test_case.

Private Constructors

test_case()

micro_os_plus::micro_test_plus::test_case::test_case (const located_name & name, runner & test_runner, suite & parent_suite, size_t own_index, size_t nesting_depth, detail::callable_ref< test_case > body)

inline

Constructs a test case with a name, runner, parent suite, index, nesting depth, and body.

Private, since the index, the nesting depth, and the parent suite are internal; a test case constructed elsewhere would not be registered with its parent, and would never run.

Parameters

name	The test case name or description, used in reports, and the location of the call to test() that created the test case.
test_runner	The test runner managing this test case.
parent_suite	The suite that owns this test case.
own_index	The one-based positional index within the parent.
nesting_depth	The depth of nesting; 1 for top-level test cases.
body	A reference to the body, with its arguments already bound, invoked when the test case executes; it must outlive the test case.

Stores the reference to the body, the reference to the name and the location of the call to test(), which outlive the test case, the parent suite, and the nesting depth; the node name points into the name.

Declaration at line 1405 of file test.h, definition at line 539 of file test-inlines.h.

539 inline test_case::test_case (const located_name& name, runner& test_runner,

540 suite& parent_suite, size_t own_index,

541 size_t nesting_depth,

542 detail::callable_ref<test_case> body)

543 : runnable_base{ name.name (), test_runner, own_index },

544 callable_{ body }, located_name_{ name },

545 parent_suite_{ parent_suite }, nesting_depth_{ nesting_depth }

546 {

547#if defined(MICRO_OS_PLUS_MICRO_TEST_PLUS_TRACE_CONSTRUCTORS_ENABLED)

548 trace::printf ("%s '%s' %" MICRO_OS_PLUS_MICRO_TEST_PLUS_PRI_SIZE

549 " %" MICRO_OS_PLUS_MICRO_TEST_PLUS_PRI_SIZE "\n",

550 __PRETTY_FUNCTION__, name_, own_index_, nesting_depth_);

551#endif // MICRO_OS_PLUS_MICRO_TEST_PLUS_TRACE_CONSTRUCTORS_ENABLED

552 }

References callable_, detail::runnable_base, located_name_, MICRO_OS_PLUS_MICRO_TEST_PLUS_PRI_SIZE, micro_test_plus::runner, micro_os_plus::micro_test_plus::detail::runnable_base::name, micro_os_plus::micro_test_plus::detail::runnable_base::name_, nesting_depth, nesting_depth_, micro_os_plus::micro_test_plus::detail::runnable_base::own_index, micro_os_plus::micro_test_plus::detail::runnable_base::own_index_, parent_suite_ and micro_os_plus::micro_test_plus::detail::runnable_base::test_runner.

Referenced by test_case, test_case, is_misdirected, operator=, operator=, report_misdirected and report_misdirected_test.

Public Destructor

~test_case()

micro_os_plus::micro_test_plus::test_case::~test_case ()

Virtual destructor.

Called when the test() function that created the test case returns; the nested test cases were already destroyed by then.

No resources are owned by test_case; it only refers to its body, which is destroyed after it, when the test() call that created both returns. If tracing is enabled, the name is output for diagnostic purposes.

Declaration at line 1455 of file test.h, definition at line 512 of file test.cpp.

512 test_case::~test_case ()

513 {

514#if defined(MICRO_OS_PLUS_MICRO_TEST_PLUS_TRACE_CONSTRUCTORS_ENABLED)

515 trace::printf ("%s '%s'\n", __PRETTY_FUNCTION__, name_);

516#endif // MICRO_OS_PLUS_MICRO_TEST_PLUS_TRACE_CONSTRUCTORS_ENABLED

517 }

Reference micro_os_plus::micro_test_plus::detail::runnable_base::name_.

Public Operators

operator=()

test_case & micro_os_plus::micro_test_plus::test_case::operator= (const test_case &)

delete

Deleted copy assignment operator to prevent copying.

A copy would duplicate the counters.

Definition at line 1434 of file test.h.

Reference test_case.

operator=()

test_case & micro_os_plus::micro_test_plus::test_case::operator= (test_case &&)

delete

Deleted move assignment operator to prevent moving.

Nodes are referred to by address (e.g. by their children and by the runner), so they must not be relocated.

Definition at line 1445 of file test.h.

References test_case, micro_os_plus::micro_test_plus::reflection::source_location::current, expect, micro_os_plus::micro_test_plus::detail::runnable_base::name, test and test_each.

Public Member Functions

name()

const char * micro_os_plus::micro_test_plus::detail::runnable_base::name (void)

inline nodiscard noexcept

Returns the node name.

Parameters: None.

Returns: A pointer to the null-terminated node name.

Returns a pointer to the null-terminated name stored in name_.

Declaration at line 454 of file test.h, definition at line 195 of file test-inlines.h.

195 runnable_base::name (void) const noexcept

196 {

197 return name_;

198 }

Reference micro_os_plus::micro_test_plus::detail::runnable_base::name_.

nesting_depth()

size_t micro_os_plus::micro_test_plus::test_case::nesting_depth (void)

inline nodiscard noexcept

Returns the nesting depth of this test case.

Parameters: None.

Returns: The nesting depth (1 = top-level).

Top-level test cases (direct children of a suite) have depth 1. Each additional level of nesting increments the depth by 1.

Declaration at line 1854 of file test.h, definition at line 796 of file test-inlines.h.

796 test_case::nesting_depth (void) const noexcept

797 {

798 return nesting_depth_;

799 }

Reference nesting_depth_.

test()

template <typename Callable_T, typename... Args_T>

void micro_os_plus::micro_test_plus::test_case::test (const located_name & name, Callable_T && callable, Args_T &&... arguments)

Adds a nested test case to this test case, and runs it.

Valid only while this test case is the innermost running one, for example from its body, or from the body of a nested test case that does not use the parameter of the outer one. When called on this test case while another one runs (an outer test case captured by a nested body), the nested test case would be reported inside the other one, with the numbering of this one; it is therefore not run, and a failed check is reported in the running test case.

Template Parameters

Callable_T	The type of a callable object.
Args_T	The types of the callable arguments.

Parameters

name	The test case name or description, used in reports; a string literal, a const char*, a std::string, or a std::string_view, converted implicitly to located_name, which copies it and also captures the location of the call.
callable	A generic callable object, usually a lambda, invoked to perform the test.
arguments	A possibly empty list of arguments to be passed to the callable.

Returns: Nothing.

Creates and runs the child test case with create_test_case(), in the parent suite of this test case, one level of nesting deeper than this test case. When another test case is running, the call is rejected with report_misdirected_test(), and the child is not run.

Declaration at line 1489 of file test.h, definition at line 564 of file test-inlines.h.

564 test_case::test (const located_name& name, Callable_T&& callable,

565 Args_T&&... arguments)

566 {

567#if defined(MICRO_OS_PLUS_MICRO_TEST_PLUS_TRACE_ENABLED)

568 trace::printf ("%s '%s'\n", __PRETTY_FUNCTION__, name.name ());

569#endif // MICRO_OS_PLUS_MICRO_TEST_PLUS_TRACE_ENABLED

570

571 if (is_misdirected ()) [[unlikely]]

572 {

573 report_misdirected_test (name);

574 return;

575 }

576

577 create_test_case (name, parent_suite_, nesting_depth_ + 1,

578 std::forward<Callable_T> (callable),

579 std::forward<Args_T> (arguments)...);

580 }

References micro_os_plus::micro_test_plus::detail::runnable_base::create_test_case, is_misdirected, micro_os_plus::micro_test_plus::detail::runnable_base::name, micro_os_plus::micro_test_plus::located_name::name, nesting_depth_, parent_suite_ and report_misdirected_test.

Referenced by operator=.

test_each()

template <typename T, typename Callable_T>

void micro_os_plus::micro_test_plus::test_case::test_each (const located_name & name, std::initializer_list< T > values, Callable_T && callable)

Adds a nested test case for each value of a braced list, and runs them.

As the overload for the ranges, for a list written in place, like ts.test_each ("Sizes", { 1, 16, 512 }, ...), whose type cannot be deduced otherwise.

Template Parameters

T	The type of the values.
Callable_T	The type of a callable object.

Parameters

name	The common name of the test cases.
values	The list of values.
callable	A generic callable object, usually a lambda, invoked with the test case and each value.

Returns: Nothing.

Since: 6.0.0

The list is iterated as a range.

Declaration at line 1591 of file test.h, definition at line 1107 of file test-inlines.h.

1107 test_case::test_each (const located_name& name,

1108 std::initializer_list<T> values, Callable_T&& callable)

1109 {

1110 detail::test_each_value (*this, name, values, callable);

1111 }

References micro_os_plus::micro_test_plus::detail::runnable_base::name and micro_os_plus::micro_test_plus::detail::test_each_value.

test_each()

template <typename Values_T, typename Callable_T>

void micro_os_plus::micro_test_plus::test_case::test_each (const located_name & name, Values_T && values, Callable_T && callable)

Adds a nested test case for each value of a range or a tuple, and runs them.

For each value, in order, a test case is added and run, as by test(), with the value as the argument of the callable, which is called as callable (test_case, value). The values may be a range (a container, an array, a span, or a view), or a tuple, whose values may have different types, for a generic callable:

ts.test_each ("Sizes", std::vector<int>{ 1, 16, 512 },

[] (auto& t, int size) { t.expect (mt::gt (size, 0)); });

ts.test_each ("Types", std::tuple{ 42, 1.5, "text" },

[] (auto& t, const auto& value) {

t.expect (mt::eq (value, value));

});

Each test case is named after the common name, followed by the value in parentheses, written as in the messages of the checks (Sizes (16)); a value that cannot be written (see extension::printable), such as an application type without an operator<<, is replaced by its position, starting at 1 (Records (#2)). The location of all the test cases is that of the call.

Template Parameters

Values_T	The type of the range or tuple of values.
Callable_T	The type of a callable object.

Parameters

name	The common name of the test cases; a string literal, a const char*, a std::string, or a std::string_view, converted implicitly to located_name, which also captures the location of the call.
values	The range or tuple of values.
callable	A generic callable object, usually a lambda, invoked with the test case and each value.

Returns: Nothing.

Since: 6.0.0

Forwards to detail::test_each_value(), which adds the test cases with test().

Declaration at line 1565 of file test.h, definition at line 1094 of file test-inlines.h.

1094 test_case::test_each (const located_name& name, Values_T&& values,

1095 Callable_T&& callable)

1096 {

1097 detail::test_each_value (*this, name, std::forward<Values_T> (values),

1098 callable);

1099 }

References micro_os_plus::micro_test_plus::detail::runnable_base::name, test_each and micro_os_plus::micro_test_plus::detail::test_each_value.

Referenced by operator= and test_each.

totals()

const counters & micro_os_plus::micro_test_plus::detail::runnable_base::totals (void)

inline nodiscard noexcept

Returns the totals of the node.

The reference is read-only, for the const and the non-const nodes alike, so that a test case or a suite cannot modify its own counters, which decide the exit code. The counters are updated only by the framework, which accesses the protected member directly.

Parameters: None.

Returns: A const reference to the counters instance.

Returns a const reference to the counters member.

Declaration at line 471 of file test.h, definition at line 205 of file test-inlines.h.

205 runnable_base::totals (void) const noexcept

206 {

207 return totals_;

208 }

Reference micro_os_plus::micro_test_plus::detail::runnable_base::totals_.

Protected Member Functions

accepts_test_case()

bool micro_os_plus::micro_test_plus::detail::runnable_base::accepts_test_case (const suite & target, const located_name & name)

nodiscard protected

Checks whether a test case can be created on a suite.

Protected, since it is used only by suite::test(). A test case can be created only on the suite whose body is running (the top suite, between runner::add_top_suite() and runner::run_suites(), or the suite being run). A call on any other suite, for example on the top suite from the body of another suite, on a static suite before the runner was initialised, or after runner::run_suites() returned, would run the test case where its results cannot be reported correctly. Such a call is rejected: the failure is reported as a failed check of the running test case, if one runs, otherwise in the running suite, or, when no suite runs, on stderr, and the rejection is remembered by the runner, which makes the exit code non-zero. When the session was declined (option errors, or --help), or aborted, the test cases are ignored silently, as after_test_case_create() ignores them.

Parameters

target	The suite on which the test case is created.
name	The name and the location of the test case, for the message.

Return Values

true	The test case can be created.
false	The test case must not be created.

The suite whose body runs accepts the test case. When the session was declined, or aborted, the test case is ignored, as after_test_case_create() ignores it.

Otherwise the call is rejected. If a test case runs (and the test cases are not only listed), the failure is reported as a check of that test case, so that it stays in its report. Otherwise, if a suite runs, the failure is reported as a check of that suite, with the same numbering and counting as the unexpected exceptions of the suite body. Otherwise (the runner was not initialised, has not started the suites, or has finished them, or the test cases are listed) the failure is given to runner::reject_call(), which writes the message on stderr and, where the reporter can still write it, as a comment line, for example in the list, and runner::mark_rejected() makes the exit code non-zero, as for the suites added too late.

Declaration at line 721 of file test.h, definition at line 239 of file test.cpp.

239 runnable_base::accepts_test_case (const suite& target,

240 const located_name& name)

241 {

242 if (runner_.running_suite_ == &target)

243 {

244 return true;

245 }

246

247 if (runner_.aborted_ || runner_.has_option_errors ()

248 || runner_.options_.help)

249 {

250 return false;

251 }

252

253 std::string message{ "test case '" };

254 message.append (name.name ());

255 message.append ("' started on suite '");

256 message.append (target.name ());

257 message.append ("', which is not running");

258

259 if (runner_.running_test_case_ != nullptr

260 && !runner_.options_.list_tests)

261 {

262 runner_.running_test_case_->report_rejected_test (message,

263 name.location ());

264 return false;

265 }

266

267 suite* running = runner_.running_suite_;

268 if (running != nullptr && !runner_.options_.list_tests)

269 {

270 running->next_test_point_number ();

271 running->test_reporter ().fail_suite (message, *running);

272 running->totals_.increment_failed_checks ();

273 return false;

274 }

275

276 runner_.reject_call (message, &name.location ());

277 return false;

278 }

Referenced by micro_os_plus::micro_test_plus::detail::runnable_base::run and micro_os_plus::micro_test_plus::suite::test.

after_test_case_create()

void micro_os_plus::micro_test_plus::detail::runnable_base::after_test_case_create (class test_case & test_case, suite & suite)

protected

Counts a newly constructed child test case and executes it immediately.

The child test case is a local object of create_test_case(), and is destroyed when that function returns.

Parameters

test_case	The newly created test_case.
suite	The parent suite to which execution results are reported.

Returns: Nothing.

Counts test_case, which is a local object of the calling create_test_case(), and immediately invokes test_case::run() on it. The test case is not kept; only child_test_cases_count_ is needed later, for the TAP plan.

If the filter patterns do not select the test case (its own name at its nesting level, or the name of suite at level 0, which matters only for the top suite, since the other suites run only when selected), its body is not called: the reporter is notified with skip_test_case() and the parent's skipped test cases counter is incremented. The test case keeps its index and its place among the children, so the TAP plan of the parent remains complete.

Otherwise, while the test case runs, the runner keeps it as its innermost running test case (see suite::test()). The parent's executed test cases counter is incremented after the run, and, if the child failed (a failed check, or a failed nested test case), its failed test cases counter too, so that the parent fails as well, as in node-tap. The child's check counters are intentionally not merged into the parent totals; each test case reports only its own counters. The child's totals are, however, accumulated into suite so that the suite summary reflects all checks performed by its test cases.

While the test cases are listed (see runner_options::list_tests), the selected test case is listed by the runner, and neither run nor counted, except in child_test_cases_count_.

After the test execution was aborted (possible only when the abort handler threw an exception, which the application caught), the report is complete, so the test case is neither run nor reported. The same applies when the runner refused to run the tests because of errors in the options, or because the output file could not be opened (see runner::has_option_errors()), or because the options requested the usage (--help).

Declaration at line 771 of file test.h, definition at line 350 of file test.cpp.

350 runnable_base::after_test_case_create (class test_case& test_case,

351 suite& suite)

352 {

353 if (runner_.aborted_ || runner_.has_option_errors ()

354 || runner_.options_.help)

355 {

356 return;

357 }

358

359 ++child_test_cases_count_;

360

361 // While the test cases are listed, the selected ones are listed and

362 // the others ignored; none is run.

363 if (runner_.options_.list_tests)

364 {

365 if (runner_.is_selected (suite.name (), 0)

366 && runner_.is_selected (test_case.name (),

367 test_case.nesting_depth ()))

368 {

369 runner_.list_test_case (suite, test_case);

370 }

371 return;

372 }

373

374 // Skip the test cases not selected by the filter; the outer test

375 // cases, if any, were selected, otherwise this one was not created.

376 if (!runner_.is_selected (suite.name (), 0)

377 || !runner_.is_selected (test_case.name (),

378 test_case.nesting_depth ()))

379 {

380 test_reporter ().skip_test_case (test_case);

381 totals_.increment_skipped_test_cases ();

382 return;

383 }

384

385 // Run the child test case immediately, as the innermost running test

386 // case of the runner. The outer one is restored by the guard, also

387 // when an exception leaves run() (for example thrown by an abort

388 // handler), so that the runner never keeps a destroyed test case.

389 {

390 struct running_guard

391 {

392 class test_case*& running;

393 class test_case* outer;

394

395 ~running_guard ()

396 {

397 running = outer;

398 }

399 } guard{ runner_.running_test_case_, runner_.running_test_case_ };

400

401 runner_.running_test_case_ = &test_case;

402 // A non-virtual call, so that run() is inlined here; each nested

403 // test case adds this call chain to the stack.

404 test_case.test_case::run ();

405 }

406

407 // This test executed one more test case.

408#if defined(MICRO_OS_PLUS_MICRO_TEST_PLUS_TRACE_CONSTRUCTORS_ENABLED)

409 trace::printf ("%s test case '%s' executed one more test case\n",

410 __PRETTY_FUNCTION__, name ());

411#endif // MICRO_OS_PLUS_MICRO_TEST_PLUS_TRACE_CONSTRUCTORS_ENABLED

412 totals_.increment_executed_test_cases ();

413

414 // Do not accumulate the totals from the child test into the current test

415 // totals, each test case shows only its counters. But a failed child

416 // fails this test too, as in node-tap; the failure reaches all outer

417 // tests, one level at a time, when they end.

418 if (!test_case.totals ().passed ())

419 {

420 totals_.increment_failed_test_cases ();

421 }

422

423#if defined(MICRO_OS_PLUS_MICRO_TEST_PLUS_TRACE_CONSTRUCTORS_ENABLED)

424 trace::printf ("%s suite '%s' totals\n", __PRETTY_FUNCTION__,

425 suite.name ());

426#endif // MICRO_OS_PLUS_MICRO_TEST_PLUS_TRACE_CONSTRUCTORS_ENABLED

427

428 // Accumulate the totals from the child test into the suite totals.

429 suite.totals_ += test_case.totals ();

430 }

Referenced by micro_os_plus::micro_test_plus::detail::runnable_base::create_test_case and micro_os_plus::micro_test_plus::detail::runnable_base::run.

create_test_case()

template <typename Callable_T, typename... Args_T>

void micro_os_plus::micro_test_plus::detail::runnable_base::create_test_case (const located_name & name, suite & parent_suite, size_t nesting_depth, Callable_T && callable, Args_T &&... arguments)

inline protected

Creates a child test case, and runs it.

The common body of suite::test() and test_case::test(), which differ only in the parent suite and the nesting depth of the test cases they create.

Always inlined into them, even without optimisations, since each nested test case adds one call chain to the stack, and a separate frame for this function would make it longer.

The test case runs and ends within the call, so, without additional arguments, it refers to the callable of the caller, which is neither copied nor moved, and is called in place, so a callable that cannot be copied is accepted, and an lvalue callable keeps the changes of its state. With additional arguments, the callable and the arguments are bound into a body of copies, by bind_callable().

Template Parameters

Callable_T	The type of a callable object.
Args_T	The types of the callable arguments.

Parameters

name	The test case name or description, used in reports, and the location of the call to test().
parent_suite	The suite to which the test case belongs.
nesting_depth	The depth of nesting of the test case; 1 for the direct children of a suite.
callable	A generic callable object, usually a lambda, invoked to perform the test.
arguments	A possibly empty list of arguments to be passed to the callable.

Returns: Nothing.

Without additional arguments, the child test_case is a local object that refers to the callable of the caller, which is neither copied nor moved, and is called in place (an lvalue callable keeps the changes of its state). A function is referred to through its pointer, and the callable and the additional arguments are bound into a local body, as copies, when there are arguments. The child is constructed with the next test point number of this node as its index, then passed to after_test_case_create(), which counts and runs it.

The child test case and its body, with the copies of the arguments, are destroyed when this function returns, so the memory used by a test session does not grow with the number of test cases; the stack holds one test case and one body for each level of nesting being run. Since the body is not stored in a std::function, it is never allocated, whatever the size of the lambda captures and of the arguments.

Declaration at line 810 of file test.h, definition at line 292 of file test-inlines.h.

292 runnable_base::create_test_case (const located_name& name,

293 suite& parent_suite, size_t nesting_depth,

294 Callable_T&& callable,

295 Args_T&&... arguments)

296 {

297 size_t own_index = next_test_point_number ();

298

299 if constexpr (sizeof...(arguments) == 0

300 && !std::is_function_v<

301 std::remove_reference_t<Callable_T>>)

302 {

303 // The test case runs and ends within this call, so it refers

304 // to the callable of the caller, which is not copied, and is

305 // called in place.

306 class test_case child_test_case{

307 name, runner_, parent_suite,

308 own_index, nesting_depth, callable_ref<class test_case>{ callable }

309 };

310

311 after_test_case_create (child_test_case, parent_suite);

312 }

313 else

314 {

315 auto body = bind_callable<class test_case> (

316 std::forward<Callable_T> (callable),

317 std::forward<Args_T> (arguments)...);

318 class test_case child_test_case{

319 name, runner_, parent_suite,

320 own_index, nesting_depth, callable_ref<class test_case>{ body }

321 };

322

323 after_test_case_create (child_test_case, parent_suite);

324 }

325 }

References micro_os_plus::micro_test_plus::detail::runnable_base::after_test_case_create, micro_os_plus::micro_test_plus::detail::bind_callable, micro_os_plus::micro_test_plus::detail::runnable_base::name, micro_os_plus::micro_test_plus::detail::runnable_base::next_test_point_number, micro_os_plus::micro_test_plus::detail::runnable_base::own_index and micro_os_plus::micro_test_plus::detail::runnable_base::runner_.

Referenced by micro_os_plus::micro_test_plus::detail::runnable_base::run, micro_os_plus::micro_test_plus::suite::test and test.

exchange_running_suite()

suite * micro_os_plus::micro_test_plus::detail::runnable_base::exchange_running_suite (suite * running)

noexcept protected

Replaces the suite whose body is running in the owning runner, and returns the previous one.

Protected, since it is used only by suite::run(), to mark the suite whose body is being called, and to restore the previous value when the body returns.

Parameters

running

The suite that starts to run, or the previous one, to restore it.

Returns: The suite that was marked as running before the call, or nullptr when none was.

Sets the pointer of the runner, a friend, and returns the previous value, so that the caller can restore it when the body returns.

Declaration at line 692 of file test.h, definition at line 212 of file test.cpp.

212 runnable_base::exchange_running_suite (suite* running) noexcept

213 {

214 suite* previous = runner_.running_suite_;

215 runner_.running_suite_ = running;

216 return previous;

217 }

Reference micro_os_plus::micro_test_plus::detail::runnable_base::runner_.

Referenced by micro_os_plus::micro_test_plus::detail::runnable_base::run and micro_os_plus::micro_test_plus::suite::run.

has_running_test_case_of()

bool micro_os_plus::micro_test_plus::detail::runnable_base::has_running_test_case_of (const suite & target)

nodiscard noexcept protected

Checks whether the innermost running test case belongs to a suite.

Protected, since it is used only by suite::test(), to forward a test case started on the suite to the running test case only when that is a test case of the same suite; the test cases started on another suite are rejected.

Parameters

target

The suite to check.

Return Values

true	A test case is running, and its parent suite is target.
false	No test case is running, or it belongs to another suite.

Reads the pointer of the runner, a friend, and the parent suite of the test case, which runnable_base may access.

Declaration at line 643 of file test.h, definition at line 199 of file test.cpp.

199 runnable_base::has_running_test_case_of (

200 const suite& target) const noexcept

201 {

202 const test_case* running = runner_.running_test_case_;

203 return running != nullptr && &running->parent_suite_ == &target;

204 }

References parent_suite_ and micro_os_plus::micro_test_plus::detail::runnable_base::runner_.

Referenced by micro_os_plus::micro_test_plus::detail::runnable_base::run and micro_os_plus::micro_test_plus::suite::test.

is_aborted()

bool micro_os_plus::micro_test_plus::detail::runnable_base::is_aborted (void)

nodiscard noexcept protected

Checks whether the test execution was aborted by the owning runner.

Protected, since it is used only by test_case::run() and suite::run(), to pass on an exception thrown by the abort handler, instead of reporting it as unexpected.

Parameters: None.

Returns: true once runner::abort() was called.

Returns the flag kept by the owning runner, set by runner::abort() and never cleared.

Declaration at line 659 of file test.h, definition at line 177 of file test.cpp.

177 runnable_base::is_aborted (void) const noexcept

178 {

179 return runner_.aborted_;

180 }

Reference micro_os_plus::micro_test_plus::detail::runnable_base::runner_.

Referenced by micro_os_plus::micro_test_plus::detail::runnable_base::run, micro_os_plus::micro_test_plus::suite::run and run.

is_listing()

bool micro_os_plus::micro_test_plus::detail::runnable_base::is_listing (void)

nodiscard noexcept protected

Checks whether the owning runner lists the test cases instead of running them.

Protected, since it is used only by suite::run(), which then calls the suite body without reporting the suite, so that its test cases are created, and listed instead of run.

Parameters: None.

Returns: true if runner_options::list_tests was set.

Returns runner_options::list_tests of the session options kept by the owning runner.

Declaration at line 675 of file test.h, definition at line 188 of file test.cpp.

188 runnable_base::is_listing (void) const noexcept

189 {

190 return runner_.options_.list_tests;

191 }

Reference micro_os_plus::micro_test_plus::detail::runnable_base::runner_.

Referenced by micro_os_plus::micro_test_plus::detail::runnable_base::run and micro_os_plus::micro_test_plus::suite::run.

next_test_point_number()

size_t micro_os_plus::micro_test_plus::detail::runnable_base::next_test_point_number (void)

inline noexcept protected

Advances to the next child test point, and returns its number.

Called for each check (by the check result, when the check is reported) and for each nested test case created.

Parameters: None.

Returns: The one-based number of the new test point.

Each call to test() invokes this member function before constructing the new test_case, and each check invokes it from the check result destructor, when the check is reported, so the numbers form a strictly increasing, one-based sequence of TAP test points, in output order.

Declaration at line 754 of file test.h, definition at line 255 of file test-inlines.h.

255 runnable_base::next_test_point_number (void) noexcept

256 {

257 return ++test_point_number_;

258 }

Reference micro_os_plus::micro_test_plus::detail::runnable_base::test_point_number_.

Referenced by micro_os_plus::micro_test_plus::detail::check_result::~check_result, micro_os_plus::micro_test_plus::detail::runnable_base::accepts_test_case, micro_os_plus::micro_test_plus::detail::runnable_base::create_test_case, micro_os_plus::micro_test_plus::suite::fail_unexpected_exception, fail_unexpected_exception, micro_os_plus::micro_test_plus::runner::reject_call and micro_os_plus::micro_test_plus::detail::runnable_base::run.

reject_body_exception()

void micro_os_plus::micro_test_plus::detail::runnable_base::reject_body_exception (void)

protected

Reports the exception that escaped the body of a suite while the test cases are listed, and records it.

Protected, since it is used only by suite::run(), when there is no test point to fail. It gives the message, which names the suite, to runner::reject_call(), which writes it on stderr and in the listing, and makes the exit code non-zero.

Parameters: None.

Returns: Nothing.

Builds the message here, and not in suite::run(), to keep the frame of that function, which is on the stack of every session, unchanged. Delegates to the private runner::reject_call(), which writes the message on stderr and in the listing, and marks the runner, so that the exit code of runner::run_suites() is not 0.

Declaration at line 739 of file test.h, definition at line 289 of file test.cpp.

289 runnable_base::reject_body_exception (void)

290 {

291 std::string message{ "unexpected exception in the body of suite '" };

292 message.append (name_);

293 message.append ("'");

294

295 runner_.reject_call (message);

296 }

References micro_os_plus::micro_test_plus::detail::runnable_base::name_, micro_os_plus::micro_test_plus::runner::reject_call and micro_os_plus::micro_test_plus::detail::runnable_base::runner_.

Referenced by micro_os_plus::micro_test_plus::detail::runnable_base::run and micro_os_plus::micro_test_plus::suite::run.

running_test_case()

test_case * micro_os_plus::micro_test_plus::detail::runnable_base::running_test_case (void)

nodiscard noexcept protected

Returns the innermost test case being run by the owning runner, if any.

Protected, since it is used only by suite::test(), to run a test case started on the suite from inside a running test case as a nested test case of it.

Parameters: None.

Returns: A pointer to the running test case, or nullptr when no test case is running.

Returns the pointer kept by the owning runner, set by after_test_case_create() while a test case runs.

Declaration at line 624 of file test.h, definition at line 166 of file test.cpp.

166 runnable_base::running_test_case (void) const noexcept

167 {

168 return runner_.running_test_case_;

169 }

Reference micro_os_plus::micro_test_plus::detail::runnable_base::runner_.

Referenced by is_misdirected, report_misdirected, report_misdirected_test, micro_os_plus::micro_test_plus::detail::runnable_base::run and micro_os_plus::micro_test_plus::suite::test.

test_reporter()

reporter & micro_os_plus::micro_test_plus::detail::runnable_base::test_reporter (void)

nodiscard noexcept protected

Returns the test reporter associated with this test runnable.

Protected, since the reporter is internal to the framework; it is used by the suites and the test cases, which derive from this class, and by the check result, which is a friend.

Not named reporter(), which would hide the class detail::reporter in the derived classes.

Parameters: None.

Returns: A reference to the test reporter.

Returns the reporter owned by the runner, through its reporter_ pointer, which is valid after runner::initialise().

Declaration at line 607 of file test.h, definition at line 155 of file test.cpp.

155 runnable_base::test_reporter (void) const noexcept

156 {

157 return *runner_.reporter_;

158 }

Reference micro_os_plus::micro_test_plus::detail::runnable_base::runner_.

Referenced by micro_os_plus::micro_test_plus::detail::check_result::~check_result, micro_os_plus::micro_test_plus::detail::runnable_base::accepts_test_case, micro_os_plus::micro_test_plus::detail::runnable_base::after_test_case_create, expect, micro_os_plus::micro_test_plus::suite::fail_unexpected_exception, fail_unexpected_exception, report_misdirected, report_rejected_test, require, micro_os_plus::micro_test_plus::detail::runnable_base::run, micro_os_plus::micro_test_plus::suite::run and run.

test_runner()

runner & micro_os_plus::micro_test_plus::detail::runnable_base::test_runner (void)

inline nodiscard noexcept protected

Returns the test runner that owns this test runnable.

Protected, since the runner is internal to the framework; it is used by the suites and the test cases, which derive from this class and pass it to their nested test cases, and by the runner, which is a friend and selects the static suites it runs.

Not named runner(), which would hide the class runner in the derived classes.

Parameters: None.

Returns: A reference to the test runner.

Returns a reference to the owning test runner.

Declaration at line 589 of file test.h, definition at line 265 of file test-inlines.h.

265 runnable_base::test_runner (void) const noexcept

266 {

267 return runner_;

268 }

Reference micro_os_plus::micro_test_plus::detail::runnable_base::runner_.

Private Member Functions

abort()

void micro_os_plus::micro_test_plus::detail::runnable_base::abort (const reflection::source_location & sl=reflection::source_location::current())

Aborts test execution via the owning runner, for a failed requirement.

Private, since it is used only by the check result, a friend, for a failed requirement without exceptions; the user code calls runner::abort().

Parameters

sl	The source location from which the abort is triggered.

Returns: Does not return.

Delegates to the private runner::abort(), as caused by a failed requirement, passing the supplied source location, so that the report identifies it. The runner then calls the abort handler, if any, and terminates the process via ::abort().

Declaration at line 568 of file test.h, definition at line 306 of file test.cpp.

306 runnable_base::abort (const reflection::source_location& sl) const

307 {

308 runner_.abort (sl, true);

309 }

References micro_os_plus::micro_test_plus::runner::abort and micro_os_plus::micro_test_plus::detail::runnable_base::runner_.

Referenced by micro_os_plus::micro_test_plus::detail::check_result::~check_result and micro_os_plus::micro_test_plus::detail::runnable_base::run.

fail_unexpected_exception()

void micro_os_plus::micro_test_plus::test_case::fail_unexpected_exception (const char * what)

Reports an exception that escaped the test case body as a failed check.

The failure is reported at the location of the call to test() that created the test case, since the location of the throw is not known.

Parameters

what	The explanatory string of a std::exception, or nullptr for an exception of another type.

Returns: Nothing.

The failure is reported as a check: the test point number is incremented first, as check_result does, so that the TAP output numbers it after the checks already reported, and the failed checks counter is incremented, so that the test case, and through it its parents, fail.

The message is unexpected exception: followed by what, or unexpected exception of unknown type when what is nullptr; the type of a std::exception is not shown, since its name is available only via RTTI, and only in an implementation-defined (usually mangled) form. There is no expression to display.

Declaration at line 1973 of file test.h, definition at line 535 of file test.cpp.

535 test_case::fail_unexpected_exception (const char* what)

536 {

537 next_test_point_number ();

538

539 detail::failure_info failure{ .kind = detail::check_kind::expectation,

540 .message = "unexpected exception",

541 .has_expression = false,

542 .location = located_name_.location () };

543 if (what != nullptr)

544 {

545 failure.message.append (": ");

546 failure.message.append (what);

547 }

548 else

549 {

550 failure.message.append (" of unknown type");

551 }

552

553 const std::string expression{};

554 test_reporter ().fail (failure, expression, *this);

555 totals_.increment_failed_checks ();

556 }

Referenced by run.

is_misdirected()

bool micro_os_plus::micro_test_plus::test_case::is_misdirected (void)

inline nodiscard noexcept

Tells whether another test case is running.

A check on this test case while a nested one runs, for example from a nested body that captured the outer test case by reference, would be written inside the subtest of the nested one, and break its TAP plan.

Parameters: None.

Return Values

true	Another test case is running.
false	This test case is running, or none is.

Another test case is running when this one is not the running test case recorded by the runner, and the runner has one.

Declaration at line 1872 of file test.h, definition at line 605 of file test-inlines.h.

605 test_case::is_misdirected (void) const noexcept

606 {

607 const test_case* running = running_test_case ();

608 return running != nullptr && running != this;

609 }

References test_case and micro_os_plus::micro_test_plus::detail::runnable_base::running_test_case.

Referenced by expect, require and test.

report_misdirected()

detail::check_result && micro_os_plus::micro_test_plus::test_case::report_misdirected (detail::check_kind kind, const reflection::source_location & sl, detail::check_result && result)

Reports a check on this test case as a failure of the running one.

Initialises result as a failed check of the running test case, with a message that names the two test cases; the message of the caller, if any, is appended after it. A failed requirement stops the running test case. Non-template, defined in src/test.cpp, so that the call sites of expect() and require() only call it.

Parameters

kind	The kind of the check.
sl	The source location of the check.
result	The check result, a temporary created by the caller.

Returns: A reference to the check result.

The check is attributed to the running test case, as a failure whose message names the two test cases, so that the checks stay in the subtest of the test case that runs, and its plan stays valid. The failing condition is a constant, so that the check is always reported as failed, even if the condition of the caller held.

Declaration at line 1891 of file test.h, definition at line 444 of file test.cpp.

444 test_case::report_misdirected (detail::check_kind kind,

445 const reflection::source_location& sl,

446 detail::check_result&& result)

447 {

448 test_case& running = *running_test_case ();

449

450 std::string message{ "[check on test case '" };

451 message.append (name ());

452 message.append ("' while '");

453 message.append (running.name ());

454 message.append ("' runs] ");

455

456 result.init (false, kind, sl, running,

457 running.test_reporter ().expression_,

458 running.test_reporter ().writes_passed_checks ());

459

460 return std::move (std::move (result) << message);

461 }

References test_case, micro_os_plus::micro_test_plus::detail::reporter::expression_, micro_os_plus::micro_test_plus::detail::runnable_base::name, micro_os_plus::micro_test_plus::detail::runnable_base::running_test_case, micro_os_plus::micro_test_plus::detail::runnable_base::test_reporter and micro_os_plus::micro_test_plus::detail::reporter::writes_passed_checks.

Referenced by expect and require.

report_misdirected_test()

void micro_os_plus::micro_test_plus::test_case::report_misdirected_test (const located_name & name)

Reports a nested test case started on this test case as a failure of the running one.

Called by test() when another test case is running. The nested test case is not run; a failed check, with a message that names the three test cases, is reported in the running test case, with the numbering and the counting of the other checks, by report_rejected_test(). Non-template, defined in src/test.cpp.

Parameters

name	The name and the location of the rejected test case.

Returns: Nothing.

Reports a failed check in the running test case, with a message that names the rejected test case, this one, and the running one, so that the numbering of the test points, the counting, and the plan of the running test case stay valid, at the location of the rejected test() call.

Declaration at line 1911 of file test.h, definition at line 472 of file test.cpp.

472 test_case::report_misdirected_test (const located_name& name)

473 {

474 test_case& running = *running_test_case ();

475

476 std::string message{ "[test case '" };

477 message.append (name.name ());

478 message.append ("' started on test case '");

479 message.append (this->name ());

480 message.append ("' while '");

481 message.append (running.name ());

482 message.append ("' runs]");

483

484 running.report_rejected_test (message, name.location ());

485 }

References test_case, micro_os_plus::micro_test_plus::located_name::location, micro_os_plus::micro_test_plus::detail::runnable_base::name, micro_os_plus::micro_test_plus::located_name::name, report_rejected_test and micro_os_plus::micro_test_plus::detail::runnable_base::running_test_case.

Referenced by test.

report_rejected_test()

void micro_os_plus::micro_test_plus::test_case::report_rejected_test (const std::string & message, const reflection::source_location & location)

Reports a rejected call as a failed check of this test case.

Called on the running test case, by report_misdirected_test() and by runnable_base::accepts_test_case(), when a test case is started where it cannot be reported, and by runner::reject_call(), for the other calls rejected while the test case runs. The failed check is counted and numbered as any other check of this test case, so that its plan stays valid. Non-template, defined in src/test.cpp.

Parameters

message	The message of the failure.
location	The location of the rejected call.

Returns: Nothing.

The check is built as the ones of report_misdirected(), always failed, and is reported when it goes out of scope.

Declaration at line 1932 of file test.h, definition at line 493 of file test.cpp.

493 test_case::report_rejected_test (const std::string& message,

494 const reflection::source_location& location)

495 {

496 detail::check_result result;

497 result.init (false, detail::check_kind::expectation, location, *this,

498 test_reporter ().expression_,

499 test_reporter ().writes_passed_checks ());

500 std::move (result) << message;

501 }

References micro_os_plus::micro_test_plus::detail::expectation, micro_os_plus::micro_test_plus::detail::check_result::init and micro_os_plus::micro_test_plus::detail::runnable_base::test_reporter.

Referenced by micro_os_plus::micro_test_plus::detail::runnable_base::accepts_test_case, micro_os_plus::micro_test_plus::runner::reject_call and report_misdirected_test.

run()

void micro_os_plus::micro_test_plus::test_case::run (void)

inline virtual

Executes the test case body by invoking the referred callable.

Private, since the test case is run only once, by after_test_case_create(), right after its creation.

Always inlined there, with a non-virtual call, so that, without optimisations, it adds no frame to the call chain of each nested test case; the out-of-line copy is used only through the virtual table.

Parameters: None.

Returns: Nothing.

Invokes the referred body with this test case, surrounded by reporter calls to begin and end the test case.

When exceptions are enabled, an exception that escapes the callable is caught and reported as a failed check of this test case, and the test case ends normally, so that the run continues with the next test case; the checks performed before the exception remain reported. Since the nested test cases catch their own exceptions, an exception is reported by the innermost test case whose body it escapes.

The detail::failed_requirement exception, thrown after a failed require(), only stops the body; the failure was already reported and counted.

An exception thrown by the abort handler, after the abort of the test execution was reported, is passed on, without reporting it, and without ending the test case, since the report is already complete; it reaches the application, which set the handler to return control this way.

Defined here, as inline, so that it can be always inlined into after_test_case_create().

Declaration at line 1954 of file test.h, definition at line 827 of file test-inlines.h.

827 test_case::run (void)

828 {

829#if defined(MICRO_OS_PLUS_MICRO_TEST_PLUS_TRACE_ENABLED)

830 trace::printf ("%s '%s'\n", __PRETTY_FUNCTION__, name_);

831#endif // MICRO_OS_PLUS_MICRO_TEST_PLUS_TRACE_ENABLED

832

833 detail::reporter& reporter = this->test_reporter ();

834

835 // For now, test cases do not record the time.

836 // this->stopwatch_.start ();

837 reporter.begin_test_case (*this);

838

839#if defined(__cpp_exceptions)

840 try

841 {

842 // Invoke the callable, passing the self reference; the arguments

843 // of test() are bound to it, by bind_callable().

844 callable_ (*this);

845 }

846 catch (const detail::failed_requirement&)

847 {

848 // A failed require() stopped the test case; already reported.

849 }

850 catch (const std::exception& e)

851 {

852 if (is_aborted ())

853 {

854 // Thrown by the abort handler; the report is complete.

855 throw;

856 }

857 fail_unexpected_exception (e.what ());

858 }

859 catch (...)

860 {

861 if (is_aborted ())

862 {

863 // Thrown by the abort handler; the report is complete.

864 throw;

865 }

866 fail_unexpected_exception (nullptr);

867 }

868#else

869 // Invoke the callable, passing the self reference; the arguments of

870 // test() are bound to it, by bind_callable().

871 callable_ (*this);

872#endif // defined(__cpp_exceptions)

873

874 // this->stopwatch_.stop ();

875 reporter.end_test_case (*this);

876 }

References micro_os_plus::micro_test_plus::detail::reporter::begin_test_case, callable_, micro_os_plus::micro_test_plus::detail::reporter::end_test_case, fail_unexpected_exception, micro_os_plus::micro_test_plus::detail::runnable_base::is_aborted, micro_os_plus::micro_test_plus::detail::runnable_base::name_ and micro_os_plus::micro_test_plus::detail::runnable_base::test_reporter.

Protected Member Attributes

child_test_cases_count_

size_t micro_os_plus::micro_test_plus::detail::runnable_base::child_test_cases_count_ = 0

protected

The number of direct child test cases.

Incremented for each call to test(), which creates a child test_case and runs it immediately. The child test cases are not kept after they run, so that the memory does not grow with the number of test cases; only their number is needed later, for the TAP plan.

Definition at line 883 of file test.h.

883 size_t child_test_cases_count_ = 0;

Referenced by micro_os_plus::micro_test_plus::detail::runnable_base::after_test_case_create, micro_os_plus::micro_test_plus::detail::runnable_base::children_subtests_count, micro_os_plus::micro_test_plus::detail::reporter_tap::end_suite and micro_os_plus::micro_test_plus::detail::reporter_tap::end_test_case.

name_

const char* micro_os_plus::micro_test_plus::detail::runnable_base::name_

protected

The node name.

Not owned; it points to a string whose lifetime exceeds that of the node. Derived classes may access this member directly, in addition to the public name() getter.

Definition at line 823 of file test.h.

823 const char* name_;

own_index_

size_t micro_os_plus::micro_test_plus::detail::runnable_base::own_index_

protected

The test index, counting from 1.

The position of this object within its parent, displayed by the TAP reporter in the ok/not ok lines. Set directly by the runner, which numbers the suites when it runs them, and by the top suite, which, when added, is always the first one.

Definition at line 859 of file test.h.

859 size_t own_index_;

runner_

runner& micro_os_plus::micro_test_plus::detail::runnable_base::runner_

protected

Reference to the test runner that owns this object.

Provides access to the reporter, to the filter, and to the state of the session (the running test case, and the abort and listing flags), and is used when aborting.

Definition at line 848 of file test.h.

848 runner& runner_;

test_point_number_

size_t micro_os_plus::micro_test_plus::detail::runnable_base::test_point_number_ = 0

protected

The number of the most recent child test point.

Test points are numbered from 1; the value is 0 before the first one. This number counts the checks and the nested test cases of this object, in execution order, as required by the TAP ok/not ok lines. It is incremented for each check (by the check result) and for each nested test case created.

Definition at line 871 of file test.h.

871 size_t test_point_number_ = 0;

Referenced by micro_os_plus::micro_test_plus::detail::runnable_base::current_subtest_index, micro_os_plus::micro_test_plus::detail::reporter_tap::end_suite, micro_os_plus::micro_test_plus::detail::reporter_tap::fail_suite, micro_os_plus::micro_test_plus::detail::runnable_base::next_test_point_number, micro_os_plus::micro_test_plus::detail::reporter_tap::output_fail_prefix, micro_os_plus::micro_test_plus::detail::reporter_tap::output_pass_prefix and micro_os_plus::micro_test_plus::detail::reporter_tap::pass_without_text.

totals_

counters micro_os_plus::micro_test_plus::detail::runnable_base::totals_

protected

Totals for the node.

For the suites, the totals include the checks of all their test cases; for a test case, they include only its own checks, plus the counts of its direct nested test cases.

The check counters are updated by the check result, which is a friend; the test case counters by after_test_case_create(), when a nested test case ends. For a suite, the totals of each of its test cases are also added, by the same function.

Definition at line 838 of file test.h.

838 counters totals_;

Referenced by micro_os_plus::micro_test_plus::detail::check_result::~check_result, micro_os_plus::micro_test_plus::detail::runnable_base::accepts_test_case, micro_os_plus::micro_test_plus::detail::runnable_base::after_test_case_create, micro_os_plus::micro_test_plus::suite::fail_unexpected_exception, fail_unexpected_exception, micro_os_plus::micro_test_plus::runner::reject_call and micro_os_plus::micro_test_plus::detail::runnable_base::totals.

Private Member Attributes

callable_

detail::callable_ref<test_case> micro_os_plus::micro_test_plus::test_case::callable_

Reference to the test case body, with any bound arguments.

Invoked by run() with a reference to this test case. The body is a local object of runnable_base::create_test_case(), which outlives the test case.

Definition at line 1985 of file test.h.

1985 detail::callable_ref<test_case> callable_;

Referenced by test_case and run.

located_name_

const located_name& micro_os_plus::micro_test_plus::test_case::located_name_

The name and the location of the call to test() that created this test case.

The argument of test(), which lives until the end of that call, after the test case ends. The name of the node points into it; the location is used to report the failures that are not associated with a check, such as an exception escaping the body, and the calls rejected while the test case runs.

Definition at line 1998 of file test.h.

1998 const located_name& located_name_;

Referenced by test_case, fail_unexpected_exception and micro_os_plus::micro_test_plus::runner::reject_call.

nesting_depth_

size_t micro_os_plus::micro_test_plus::test_case::nesting_depth_

The nesting depth of this test case within the suite.

1 for the direct children of a suite; used for indentation.

Definition at line 2015 of file test.h.

2015 size_t nesting_depth_;

Referenced by test_case, nesting_depth and test.

parent_suite_

suite& micro_os_plus::micro_test_plus::test_case::parent_suite_

Reference to the parent suite that owns this test case.

The suite into which the totals of the nested test cases are accumulated.

Definition at line 2007 of file test.h.

2007 suite& parent_suite_;

Referenced by test_case, micro_os_plus::micro_test_plus::detail::runnable_base::has_running_test_case_of and test.

Deprecated Functions

assume()

template <class Expr_T>

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

Deprecated name of require().

The same as require(). The name was misleading: in other frameworks (JUnit, Hypothesis), an unmet assumption skips the test, while here it fails it.

Template Parameters

Expr_T

The type of the custom expression.

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<<.

Deprecated: use require() (since 6.0.0)

Forwards to require(), with the same check result temporary, which must be passed on, since it is destroyed at the end of the statement of the caller.

Declaration at line 1834 of file test.h, definition at line 783 of file test-inlines.h.

783 test_case::assume (const Expr_T& expr, const reflection::source_location& sl,

784 detail::check_result&& result)

785 {

786 return require (expr, sl, std::move (result));

787 }

Reference require.

expect()

template <class Expr_T>

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

Deprecated expect() of a suspicious condition.

Accepts the arguments excluded from extension::checkable, such as a string literal or a function name, which are always true, so the check passes silently; usually the description was written instead of the condition, or the function was not called. Write the condition, or ne (p, nullptr) for a pointer.

Template Parameters

Expr_T

The type of the argument.

Parameters

expr	The argument.
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.

Returns: A reference to the check result.

Deprecated: the argument is always true; write the condition (since 6.0.0)

Definition at line 1772 of file test.h.

Reference micro_os_plus::micro_test_plus::reflection::source_location::current.

require()

template <class 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{})

Deprecated require() of a suspicious condition.

Accepts the arguments excluded from extension::checkable, as the deprecated overload of expect() does.

Template Parameters

Expr_T

The type of the argument.

Parameters

expr	The argument.
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.

Returns: A reference to the check result.

Deprecated: the argument is always true; write the condition (since 6.0.0)

Definition at line 1799 of file test.h.

Reference micro_os_plus::micro_test_plus::reflection::source_location::current.

Deprecated Functions of runnable_base

children_subtests_count()

size_t micro_os_plus::micro_test_plus::detail::runnable_base::children_subtests_count (void)

inline nodiscard noexcept

Deprecated number of direct child test cases of this node.

Used only for the TAP plan, by the reporters, which access it directly. The test cases skipped by the filter are included.

Parameters: None.

Returns: The number of child test cases.

Deprecated: internal to the framework (since 6.0.0)

Returns the number of direct child test cases, including those skipped by the filter.

Declaration at line 525 of file test.h, definition at line 241 of file test-inlines.h.

241 runnable_base::children_subtests_count (void) const noexcept

242 {

243 return child_test_cases_count_;

244 }

Reference micro_os_plus::micro_test_plus::detail::runnable_base::child_test_cases_count_.

Referenced by micro_os_plus::micro_test_plus::detail::runnable_base::operator=.

current_subtest_index()

size_t micro_os_plus::micro_test_plus::detail::runnable_base::current_subtest_index (void)

inline nodiscard noexcept

Deprecated number of the most recent child test point.

Used only for the TAP output, by the reporters, which access it directly.

Parameters: None.

Returns: The one-based test point number, or 0 before the first test point.

Deprecated: internal to the framework (since 6.0.0)

Returns the number of the most recent child test point.

Declaration at line 510 of file test.h, definition at line 229 of file test-inlines.h.

229 runnable_base::current_subtest_index (void) const noexcept

230 {

231 return test_point_number_;

232 }

Reference micro_os_plus::micro_test_plus::detail::runnable_base::test_point_number_.

Referenced by micro_os_plus::micro_test_plus::detail::runnable_base::operator=.

own_index()

size_t micro_os_plus::micro_test_plus::detail::runnable_base::own_index (void)

inline nodiscard noexcept

Deprecated positional index of this node within its parent.

Used only for the TAP output, by the reporters, which access it directly. The setter of v5.0.1, and increment_subtest_index(), were removed, since they allowed the application code to corrupt the numbering of the reports.

Parameters: None.

Returns: The one-based own index.

Deprecated: internal to the framework (since 6.0.0)

Returns the one-based positional index of this node within its parent.

Declaration at line 494 of file test.h, definition at line 218 of file test-inlines.h.

218 runnable_base::own_index (void) const noexcept

219 {

220 return own_index_;

221 }

Reference micro_os_plus::micro_test_plus::detail::runnable_base::own_index_.

Referenced by micro_os_plus::micro_test_plus::detail::runnable_base::runnable_base, test_case, micro_os_plus::micro_test_plus::detail::runnable_base::create_test_case, detail::runnable_base, micro_os_plus::micro_test_plus::detail::runnable_base::operator= and micro_os_plus::micro_test_plus::detail::runnable_base::reporter_tap.

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

Generated via doxygen2docusaurus 2.2.8 by Doxygen 1.18.0.

Declaration​

Included Headers​

Base class​

Friends Index​

Public Constructors Index​

Private Constructors Index​

Public Destructor Index​

Public Operators Index​

Public Member Functions Index​

Protected Member Functions Index​

Private Member Functions Index​

Protected Member Attributes Index​

Private Member Attributes Index​

Deprecated Functions Index​

Deprecated Functions of runnable_base Index​

Description​

Friends​

detail::runnable_base​

micro_test_plus::runner​

Public Constructors​

test_case()​

test_case()​

Private Constructors​

test_case()​

Public Destructor​

~test_case()​

Public Operators​

operator=()​

operator=()​

Public Member Functions​

name()​

nesting_depth()​

test()​

test_each()​

test_each()​

totals()​

Protected Member Functions​

accepts_test_case()​

after_test_case_create()​

create_test_case()​

exchange_running_suite()​

has_running_test_case_of()​

is_aborted()​

is_listing()​

next_test_point_number()​

reject_body_exception()​

running_test_case()​

test_reporter()​

test_runner()​

Private Member Functions​

abort()​

fail_unexpected_exception()​

is_misdirected()​

report_misdirected()​

report_misdirected_test()​

report_rejected_test()​

run()​

Protected Member Attributes​

child_test_cases_count_​

name_​

own_index_​

runner_​

test_point_number_​

totals_​

Private Member Attributes​

callable_​

located_name_​

nesting_depth_​

parent_suite_​

Deprecated Functions​

assume()​

expect()​

require()​

Deprecated Functions of runnable_base​

children_subtests_count()​

current_subtest_index()​

own_index()​

Declaration

Included Headers

Base class

Friends Index

Public Constructors Index

Private Constructors Index

Public Destructor Index

Public Operators Index

Public Member Functions Index

Protected Member Functions Index

Private Member Functions Index

Protected Member Attributes Index

Private Member Attributes Index

Deprecated Functions Index

Deprecated Functions of runnable_base Index

Description

Friends

detail::runnable_base

micro_test_plus::runner

Public Constructors

test_case()

test_case()

Private Constructors

test_case()

Public Destructor

~test_case()

Public Operators

operator=()

operator=()

Public Member Functions

name()

nesting_depth()

test()

test_each()

test_each()

totals()

Protected Member Functions

accepts_test_case()

after_test_case_create()

create_test_case()

exchange_running_suite()

has_running_test_case_of()

is_aborted()

is_listing()

next_test_point_number()

reject_body_exception()

running_test_case()

test_reporter()

test_runner()

Private Member Functions

abort()

fail_unexpected_exception()

is_misdirected()

report_misdirected()

report_misdirected_test()

report_rejected_test()

run()

Protected Member Attributes

child_test_cases_count_

name_

own_index_

runner_

test_point_number_

totals_

Private Member Attributes

callable_

located_name_

nesting_depth_

parent_suite_

Deprecated Functions

assume()

expect()

require()

Deprecated Functions of runnable_base

children_subtests_count()

current_subtest_index()

own_index()