runnable Class Template

CRTP base class factoring out callable storage, rule-of-five, and run() logic shared by subtest and suite. More...

Declaration

template <typename Self_T>
class micro_os_plus::micro_test_plus::detail::runnable<Self_T> { ... }

Included Headers

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

Base class

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

Public Constructors Index

template <typename Callable_T, typename... Args_T>
runnable (const char *name, class runner &runner, size_t own_index, Callable_T &&callable, Args_T &&... arguments)
	Class template constructor. More...
template <typename Self_T>
runnable (const runnable &)=delete
	Deleted copy constructor to prevent copying. More...
template <typename Self_T>
runnable (runnable &&)=delete
	Deleted move constructor to prevent moving. More...

Public Destructor Index

template <typename Self_T>
~runnable () override
	Virtual destructor. More...

Public Operators Index

template <typename Self_T>
runnable &	operator= (const runnable &)=delete
	Deleted copy assignment operator to prevent copying. More...
template <typename Self_T>
runnable &	operator= (runnable &&)=delete
	Deleted move assignment operator to prevent moving. More...

Public Member Functions Index

template <typename Self_T>
void	abort (const reflection::source_location &sl=reflection::source_location::current())
	Aborts test execution via the owning runner. More...
template <typename Self_T>
size_t	children_subtests_count (void) const noexcept
	Returns the number of direct child subtests owned by this node. More...
template <typename Self_T>
size_t	current_subtest_index () const noexcept
	Returns the index of the most recently created child subtest. More...
template <typename Self_T>
size_t	increment_subtest_index () noexcept
	Increments and returns the child subtest sequential index. More...
template <typename Self_T>
const char *	name (void) const noexcept
	Gets the node name. More...
template <typename Self_T>
size_t	own_index () const noexcept
	Returns the positional index of this object within its parent. More...
template <typename Self_T>
void	own_index (size_t index) noexcept
	Sets the positional index of this object within its parent. More...
template <typename Self_T>
class reporter &	reporter (void) const noexcept
	Gets the test reporter associated with this test runnable. More...
template <typename Self_T>
void	run (void)=0
	Runs the test function by invoking the stored callable with the derived self instance. More...
template <typename Self_T>
class runner &	runner (void) const noexcept
	Gets the test runner associated with this test runnable. More...
template <typename Self_T>
const runner_totals &	totals () const noexcept
	Gets the totals for the test (const overload). More...
template <typename Self_T>
runner_totals &	totals () noexcept
	Gets the totals for the test. More...

Protected Member Functions Index

template <typename Self_T>
void	after_subtest_create_ (std::unique_ptr< subtest > child_test, suite &suite)
	Registers a newly constructed child subtest and executes it immediately. More...

Protected Member Attributes Index

template <typename Self_T>
std::function< void(Self_T &)>	callable_
	Callable storing the test body and any bound arguments. Invoked with a reference to the derived Self_T instance. More...
template <typename Self_T>
std::vector< std::unique_ptr< subtest > >	children_subtests_
	Owning collection of direct child subtests. More...
template <typename Self_T>
size_t	current_subtest_index_ = 0
	The subtest index, counting from 1. More...
template <typename Self_T>
const char *	name_
	The test node name. More...
template <typename Self_T>
size_t	own_index_
	The test index, counting from 1. More...
template <typename Self_T>
class { ... }	runner_
	Reference to the test runner that owns this object. More...
template <typename Self_T>
runner_totals	totals_
	Totals for the test node, including nested cases. More...

Description

CRTP base class factoring out callable storage, rule-of-five, and run() logic shared by subtest and suite.

Template Parameters

Self_T

The concrete derived class type (CRTP pattern). The stored callable receives a Self_T& reference when the test is executed.

Definition at line 452 of file test.h.

Public Constructors

runnable()

template <typename Callable_T, typename... Args_T>

micro_os_plus::micro_test_plus::detail::runnable< Self_T >::runnable (const char * name, class runner & runner, size_t own_index, Callable_T && callable, Args_T &&... arguments)

Class template constructor.

Template Parameters

Callable_T	The callable type.
Args_T	The additional argument types.

Parameters

name	The test name, used in reports.
runner	The test runner managing this test.
own_index	The test index within the runner.
callable	The callable invoked when the test runs.
arguments	Additional arguments forwarded to the callable after the leading Self_T& reference.

Binds the callable and its arguments into the stored callable_ function object. When run() is called, the stored function is invoked with a reference to the derived Self_T instance as its first argument, followed by the bound arguments.

Declaration at line 469 of file test.h, definition at line 194 of file test-inlines.h.

194 runnable<Self_T>::runnable (const char* name, class runner& runner,

195 size_t own_index, Callable_T&& callable,

196 Args_T&&... arguments)

197 : runnable_base{ name, runner, own_index }

198 {

199 // When there are no extra arguments the callable already has the

200 // signature void(Self_T&), so store it directly. Only use std::bind when

201 // additional arguments must be pre-bound, to avoid triggering a GCC ARM

202 // bug in

203 // __is_nothrow_invocable<_Bind<...>, Self_T&> (GCC 15.2.1).

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

205 {

206 callable_ = std::forward<Callable_T> (callable);

207 }

208 else

209 {

210 callable_ = std::bind (std::forward<Callable_T> (callable),

211 std::placeholders::_1,

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

213 }

214

215#if defined(MICRO_OS_PLUS_MICRO_TEST_PLUS_TRACE_CONSTRUCTORS_ENABLED)

216 trace::printf ("%s '%s' %zu\n", __PRETTY_FUNCTION__, name, own_index_);

217#endif // MICRO_OS_PLUS_MICRO_TEST_PLUS_TRACE_CONSTRUCTORS_ENABLED

218 }

References micro_os_plus::micro_test_plus::detail::runnable_base::runnable_base, micro_os_plus::micro_test_plus::detail::test_node::name, 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< Self_T >::runnable, micro_os_plus::micro_test_plus::detail::runnable< Self_T >::runnable, micro_os_plus::micro_test_plus::detail::runnable< Self_T >::operator= and micro_os_plus::micro_test_plus::detail::runnable< Self_T >::operator=.

runnable()

template <typename Self_T>

micro_os_plus::micro_test_plus::detail::runnable< Self_T >::runnable (const runnable &)

delete

Deleted copy constructor to prevent copying.

Definition at line 475 of file test.h.

Reference micro_os_plus::micro_test_plus::detail::runnable< Self_T >::runnable.

runnable()

template <typename Self_T>

micro_os_plus::micro_test_plus::detail::runnable< Self_T >::runnable (runnable &&)

delete

Deleted move constructor to prevent moving.

Definition at line 480 of file test.h.

Reference micro_os_plus::micro_test_plus::detail::runnable< Self_T >::runnable.

Public Destructor

~runnable()

template <typename Self_T>

micro_os_plus::micro_test_plus::detail::runnable< Self_T >::~runnable ()

virtual

Virtual destructor.

No-op in production builds. When tracing is enabled via MICRO_OS_PLUS_MICRO_TEST_PLUS_TRACE_CONSTRUCTORS_ENABLED, emits a trace message identifying the instance being destroyed.

Declaration at line 499 of file test.h, definition at line 227 of file test-inlines.h.

227 runnable<Self_T>::~runnable ()

228 {

229#if defined(MICRO_OS_PLUS_MICRO_TEST_PLUS_TRACE_CONSTRUCTORS_ENABLED)

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

231#endif // MICRO_OS_PLUS_MICRO_TEST_PLUS_TRACE_CONSTRUCTORS_ENABLED

232 }

Reference micro_os_plus::micro_test_plus::detail::test_node::name_.

Public Operators

operator=()

template <typename Self_T>

runnable & micro_os_plus::micro_test_plus::detail::runnable< Self_T >::operator= (const runnable &)

delete

Deleted copy assignment operator to prevent copying.

Definition at line 486 of file test.h.

Reference micro_os_plus::micro_test_plus::detail::runnable< Self_T >::runnable.

operator=()

template <typename Self_T>

runnable & micro_os_plus::micro_test_plus::detail::runnable< Self_T >::operator= (runnable &&)

delete

Deleted move assignment operator to prevent moving.

Definition at line 493 of file test.h.

Reference micro_os_plus::micro_test_plus::detail::runnable< Self_T >::runnable.

Public Member Functions

abort()

template <typename Self_T>

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.

Parameters

sl	The source location from which the abort is triggered.

Returns

Does not return.

Delegates immediately to runner_.abort(), passing the supplied source location so that the error message identifies the call site before the process is terminated via ::abort().

Declaration at line 378 of file test.h, definition at line 161 of file test.cpp.

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

162 {

163 runner_.abort (sl);

164 }

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

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

children_subtests_count()

template <typename Self_T>

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

inline nodiscard noexcept

Returns the number of direct child subtests owned by this node.

Parameters

None.

Returns

The number of child subtests.

Returns the number of child subtests owned by this node.

Declaration at line 358 of file test.h, definition at line 168 of file test-inlines.h.

168 runnable_base::children_subtests_count (void) const noexcept

169 {

170 return children_subtests_.size ();

171 }

Reference micro_os_plus::micro_test_plus::detail::runnable_base::children_subtests_.

Referenced by micro_os_plus::micro_test_plus::reporter_tap::end_subtest, micro_os_plus::micro_test_plus::reporter_tap::end_suite and micro_os_plus::micro_test_plus::detail::runnable_base::operator=.

current_subtest_index()

template <typename Self_T>

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

inline nodiscard noexcept

Returns the index of the most recently created child subtest.

Parameters

None.

Returns

The current child subtest sequential index.

Returns the sequential index of the most recently created child subtest.

Declaration at line 338 of file test.h, definition at line 146 of file test-inlines.h.

146 runnable_base::current_subtest_index () const noexcept

147 {

148 return current_subtest_index_;

149 }

Reference micro_os_plus::micro_test_plus::detail::runnable_base::current_subtest_index_.

Referenced by micro_os_plus::micro_test_plus::detail::runnable_base::operator=, micro_os_plus::micro_test_plus::reporter_tap::output_fail_prefix_ and micro_os_plus::micro_test_plus::reporter_tap::output_pass_prefix_.

increment_subtest_index()

template <typename Self_T>

size_t micro_os_plus::micro_test_plus::detail::runnable_base::increment_subtest_index ()

inline noexcept

Increments and returns the child subtest sequential index.

Parameters

None.

Returns

The new index value after incrementing.

Each call to test() invokes this method before constructing the new subtest, so the index values form a strictly increasing, one-based sequence.

Declaration at line 348 of file test.h, definition at line 158 of file test-inlines.h.

158 runnable_base::increment_subtest_index () noexcept

159 {

160 return ++current_subtest_index_;

161 }

Reference micro_os_plus::micro_test_plus::detail::runnable_base::current_subtest_index_.

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

name()

template <typename Self_T>

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

inline nodiscard noexcept

Gets the node name.

Parameters

None.

Returns

A pointer to the null-terminated test node name.

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

Declaration at line 203 of file test.h, definition at line 94 of file test-inlines.h.

94 test_node::name (void) const noexcept

95 {

96 return name_;

97 }

Reference micro_os_plus::micro_test_plus::detail::test_node::name_.

Referenced by micro_os_plus::micro_test_plus::detail::runnable< Self_T >::runnable, micro_os_plus::micro_test_plus::detail::runnable_base::runnable_base, micro_os_plus::micro_test_plus::runner::runner, micro_os_plus::micro_test_plus::runner::runner, micro_os_plus::micro_test_plus::static_runner::static_runner, micro_os_plus::micro_test_plus::static_runner::static_runner, micro_os_plus::micro_test_plus::detail::test_node::test_node, micro_os_plus::micro_test_plus::detail::runnable_base::after_subtest_create_, micro_os_plus::micro_test_plus::reporter_human::begin_subtest, micro_os_plus::micro_test_plus::reporter_tap::begin_subtest, micro_os_plus::micro_test_plus::reporter_human::begin_suite, micro_os_plus::micro_test_plus::reporter_tap::begin_suite, micro_os_plus::micro_test_plus::reporter_human::end_subtest, micro_os_plus::micro_test_plus::reporter_tap::end_subtest, micro_os_plus::micro_test_plus::reporter_human::end_suite, micro_os_plus::micro_test_plus::reporter_tap::end_suite, micro_os_plus::micro_test_plus::runner::operator= and micro_os_plus::micro_test_plus::runner::suite.

own_index()

template <typename Self_T>

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

inline nodiscard noexcept

Returns the positional index of this object within its parent.

Parameters

None.

Returns

The one-based own index.

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

Declaration at line 314 of file test.h, definition at line 126 of file test-inlines.h.

126 runnable_base::own_index () const noexcept

127 {

128 return own_index_;

129 }

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

Referenced by micro_os_plus::micro_test_plus::detail::runnable< Self_T >::runnable, micro_os_plus::micro_test_plus::detail::runnable_base::runnable_base, micro_os_plus::micro_test_plus::reporter_tap::end_subtest, micro_os_plus::micro_test_plus::reporter_tap::end_suite and micro_os_plus::micro_test_plus::detail::runnable_base::operator=.

own_index()

template <typename Self_T>

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

inline noexcept

Sets the positional index of this object within its parent.

info

This overload follows the same-name getter/setter pattern used throughout the framework: the getter is the const overload and the setter is the non-const single-argument overload.

Parameters

index

The new index value.

Returns

Nothing.

Sets the positional index of this object within its parent.

Declaration at line 328 of file test.h, definition at line 136 of file test-inlines.h.

136 runnable_base::own_index (size_t index) noexcept

137 {

138 own_index_ = index;

139 }

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

reporter()

template <typename Self_T>

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

nodiscard noexcept

Gets the test reporter associated with this test runnable.

Parameters

None.

Returns

A reference to the test reporter.

Delegates immediately to runner_.reporter(), returning the reporter associated with the owning runner instance.

Declaration at line 368 of file test.h, definition at line 149 of file test.cpp.

149 runnable_base::reporter (void) const noexcept

150 {

151 return runner_.reporter ();

152 }

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

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

run()

template <typename Self_T>

virtual void micro_os_plus::micro_test_plus::detail::runnable< Self_T >::run (void)

Runs the test function by invoking the stored callable with the derived self instance.

Parameters

None.

Returns

Nothing.

Definition at line 513 of file test.h.

runner()

template <typename Self_T>

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

inline nodiscard noexcept

Gets the test runner associated with this test runnable.

Parameters

None.

Returns

A reference to the test runner.

Returns a reference to the owning test runner.

Declaration at line 389 of file test.h, definition at line 178 of file test-inlines.h.

178 runnable_base::runner (void) const noexcept

179 {

180 return runner_;

181 }

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

Referenced by micro_os_plus::micro_test_plus::detail::runnable< Self_T >::runnable, micro_os_plus::micro_test_plus::detail::runnable_base::runnable_base and micro_os_plus::micro_test_plus::detail::runnable_base::operator=.

totals()

template <typename Self_T>

const runner_totals & micro_os_plus::micro_test_plus::detail::test_node::totals ()

inline nodiscard noexcept

Gets the totals for the test (const overload).

Parameters

None.

Returns

A const reference to the runner_totals instance.

Returns a const reference to the runner_totals member.

Declaration at line 224 of file test.h, definition at line 114 of file test-inlines.h.

114 test_node::totals () const noexcept

115 {

116 return totals_;

117 }

Reference micro_os_plus::micro_test_plus::detail::test_node::totals_.

totals()

template <typename Self_T>

runner_totals & micro_os_plus::micro_test_plus::detail::test_node::totals ()

inline nodiscard noexcept

Gets the totals for the test.

Parameters

None.

Returns

A reference to the runner_totals instance.

Returns a reference to the runner_totals member.

Declaration at line 214 of file test.h, definition at line 104 of file test-inlines.h.

104 test_node::totals () noexcept

105 {

106 return totals_;

107 }

Reference micro_os_plus::micro_test_plus::detail::test_node::totals_.

Referenced by micro_os_plus::micro_test_plus::detail::runnable_base::after_subtest_create_, micro_os_plus::micro_test_plus::reporter_human::end_session, micro_os_plus::micro_test_plus::reporter_tap::end_session, micro_os_plus::micro_test_plus::reporter_human::end_subtest, micro_os_plus::micro_test_plus::reporter_tap::end_subtest, micro_os_plus::micro_test_plus::reporter_human::end_suite, micro_os_plus::micro_test_plus::reporter_tap::end_suite and micro_os_plus::micro_test_plus::detail::test_node::operator=.

Protected Member Functions

after_subtest_create_()

template <typename Self_T>

void micro_os_plus::micro_test_plus::detail::runnable_base::after_subtest_create_ (std::unique_ptr< subtest > child_test, suite & suite)

protected

Registers a newly constructed child subtest and executes it immediately.

Parameters

child_test	Owning pointer to the newly created subtest.
suite	The parent suite to which execution results are reported.

Returns

Nothing.

Transfers ownership of child_test into children_subtests_ and immediately invokes subtest::run() on the newly stored subtest. The parent's executed-subtest counter is then incremented. The child's check counters are intentionally not merged into the parent totals; each subtest 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 subtests.

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

177 runnable_base::after_subtest_create_ (

178 std::unique_ptr<class subtest> child_test, suite& suite)

179 {

180 // Transfer ownership into the vector.

181 children_subtests_.push_back (std::move (child_test));

182

183 // Run the child test case immediately.

184 class subtest& subtest = *children_subtests_.back ();

185 subtest.run ();

186

187 // This test executed one more subtest.

188#if defined(MICRO_OS_PLUS_MICRO_TEST_PLUS_TRACE_CONSTRUCTORS_ENABLED)

189 trace::printf ("%s subtest '%s' executed one more subtest\n",

190 __PRETTY_FUNCTION__, name ());

191#endif // MICRO_OS_PLUS_MICRO_TEST_PLUS_TRACE_CONSTRUCTORS_ENABLED

192 totals ().increment_executed_subtests ();

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

194 // totals, each subtest shows only its counters.

195

196#if defined(MICRO_OS_PLUS_MICRO_TEST_PLUS_TRACE_CONSTRUCTORS_ENABLED)

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

198 suite.name ());

199#endif // MICRO_OS_PLUS_MICRO_TEST_PLUS_TRACE_CONSTRUCTORS_ENABLED

200

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

202 suite.totals () += subtest.totals ();

203 }

References micro_os_plus::micro_test_plus::detail::runnable_base::children_subtests_, micro_os_plus::micro_test_plus::detail::runner_totals::increment_executed_subtests, micro_os_plus::micro_test_plus::detail::test_node::name, micro_os_plus::micro_test_plus::subtest::run and micro_os_plus::micro_test_plus::detail::test_node::totals.

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

Protected Member Attributes

callable_

template <typename Self_T>

std::function<void (Self_T&)> micro_os_plus::micro_test_plus::detail::runnable< Self_T >::callable_

protected

Callable storing the test body and any bound arguments. Invoked with a reference to the derived Self_T instance.

Definition at line 521 of file test.h.

521 std::function<void (Self_T&)> callable_;

children_subtests_

template <typename Self_T>

std::vector<std::unique_ptr<subtest> > micro_os_plus::micro_test_plus::detail::runnable_base::children_subtests_

protected

Owning collection of direct child subtests.

Each call to test() appends a new subtest to this vector and runs it immediately. The vector retains ownership for the lifetime of the parent runnable.

Definition at line 436 of file test.h.

436 std::vector<std::unique_ptr<subtest>> children_subtests_;

Referenced by micro_os_plus::micro_test_plus::detail::runnable_base::after_subtest_create_ and micro_os_plus::micro_test_plus::detail::runnable_base::children_subtests_count.

current_subtest_index_

template <typename Self_T>

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

protected

The subtest index, counting from 1.

This index is used for reporting and tracking the execution order of subtests within a suite, especially when nested subtests are involved. It is incremented for each subtest created, allowing for clear identification of subtests in reports and diagnostics.

Definition at line 426 of file test.h.

426 size_t current_subtest_index_ = 0;

Referenced by micro_os_plus::micro_test_plus::detail::runnable_base::current_subtest_index and micro_os_plus::micro_test_plus::detail::runnable_base::increment_subtest_index.

name_

template <typename Self_T>

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

protected

The test node name.

info

Derived classes may access this member directly in addition to the public name() getter.

Definition at line 233 of file test.h.

233 const char* name_;

Referenced by micro_os_plus::micro_test_plus::detail::test_node::test_node, micro_os_plus::micro_test_plus::detail::runnable< Self_T >::~runnable, micro_os_plus::micro_test_plus::detail::runnable_base::~runnable_base, micro_os_plus::micro_test_plus::detail::test_node::~test_node and micro_os_plus::micro_test_plus::detail::test_node::name.

own_index_

template <typename Self_T>

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

protected

The test index, counting from 1.

Definition at line 415 of file test.h.

415 size_t own_index_;

Referenced by micro_os_plus::micro_test_plus::detail::runnable_base::runnable_base, micro_os_plus::micro_test_plus::detail::runnable_base::own_index and micro_os_plus::micro_test_plus::detail::runnable_base::own_index.

runner_

template <typename Self_T>

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

protected

Reference to the test runner that owns this object.

Definition at line 410 of file test.h.

410 class runner& runner_;

Referenced by micro_os_plus::micro_test_plus::detail::runnable_base::runnable_base, micro_os_plus::micro_test_plus::detail::runnable_base::abort, micro_os_plus::micro_test_plus::detail::runnable_base::reporter and micro_os_plus::micro_test_plus::detail::runnable_base::runner.

totals_

template <typename Self_T>

runner_totals micro_os_plus::micro_test_plus::detail::test_node::totals_

protected

Totals for the test node, including nested cases.

Definition at line 238 of file test.h.

238 runner_totals totals_;

Referenced by micro_os_plus::micro_test_plus::runner::exit_code, micro_os_plus::micro_test_plus::runner::run_suites_, micro_os_plus::micro_test_plus::static_runner::run_suites_, micro_os_plus::micro_test_plus::detail::test_node::totals and micro_os_plus::micro_test_plus::detail::test_node::totals.

---

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

• test-inlines.h
• test.h
• test.cpp

---

Generated via doxygen2docusaurus 2.2.2 by Doxygen 1.17.0.