Skip to main content

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

Base class

classrunnable_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>
voidabort (const reflection::source_location &sl=reflection::source_location::current())

Aborts test execution via the owning runner. More...

template <typename Self_T>
size_tchildren_subtests_count (void) const noexcept

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

template <typename Self_T>
size_tcurrent_subtest_index () const noexcept

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

template <typename Self_T>
size_tincrement_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_town_index () const noexcept

Returns the positional index of this object within its parent. More...

template <typename Self_T>
voidown_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>
voidrun (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>
voidafter_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_tcurrent_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_town_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_totalstotals_

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 443 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
[in] name

The test name, used in reports.

[in] runner

The test runner managing this test.

[in] own_index

The test index within the runner.

[in] callable

The callable invoked when the test runs.

[in] 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 460 of file test.h, definition at line 191 of file test-inlines.h.

192 size_t own_index, Callable_T&& callable,
193 Args_T&&... arguments)
195 {
196 // When there are no extra arguments the callable already has the
197 // signature void(Self_T&), so store it directly. Only use std::bind when
198 // additional arguments must be pre-bound, to avoid triggering a GCC ARM
199 // bug in
200 // __is_nothrow_invocable<_Bind<...>, Self_T&> (GCC 15.2.1).
201 if constexpr (sizeof...(arguments) == 0)
202 {
203 callable_ = std::forward<Callable_T> (callable);
204 }
205 else
206 {
207 callable_ = std::bind (std::forward<Callable_T> (callable),
208 std::placeholders::_1,
209 std::forward<Args_T> (arguments)...);
210 }
211
212#if defined(MICRO_OS_PLUS_TRACE) \
213 && defined(MICRO_OS_PLUS_TRACE_MICRO_TEST_PLUS_CONSTRUCTORS)
214#if defined(__GNUC__)
215#pragma GCC diagnostic push
216#if defined(__clang__)
217#pragma clang diagnostic ignored "-Wunsafe-buffer-usage-in-libc-call"
218#endif
219#endif
220 trace::printf ("%s '%s' %zu\n", __PRETTY_FUNCTION__, name, own_index_);
221#if defined(__GNUC__)
222#pragma GCC diagnostic pop
223#endif
224#endif // MICRO_OS_PLUS_TRACE_MICRO_TEST_PLUS_CONSTRUCTORS
225 }

References 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 466 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 471 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_TRACE_MICRO_TEST_PLUS_CONSTRUCTORS, emits a trace message identifying the instance being destroyed.

Declaration at line 490 of file test.h, definition at line 234 of file test-inlines.h.

235 {
236#if defined(MICRO_OS_PLUS_TRACE) \
237 && defined(MICRO_OS_PLUS_TRACE_MICRO_TEST_PLUS_CONSTRUCTORS)
238#if defined(__GNUC__)
239#pragma GCC diagnostic push
240#if defined(__clang__)
241#pragma clang diagnostic ignored "-Wunsafe-buffer-usage-in-libc-call"
242#endif
243#endif
244 trace::printf ("%s '%s'\n", __PRETTY_FUNCTION__, name_);
245#if defined(__GNUC__)
246#pragma GCC diagnostic pop
247#endif
248#endif // MICRO_OS_PLUS_TRACE_MICRO_TEST_PLUS_CONSTRUCTORS
249 }

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 477 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 484 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 369 of file test.h, definition at line 199 of file test.cpp.

200 {
201 runner_.abort (sl);
202 }

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 349 of file test.h, definition at line 165 of file test-inlines.h.

166 {
167 return children_subtests_.size ();
168 }

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 329 of file test.h, definition at line 143 of file test-inlines.h.

144 {
146 }

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 339 of file test.h, definition at line 155 of file test-inlines.h.

156 {
158 }

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

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 305 of file test.h, definition at line 123 of file test-inlines.h.

123 runnable_base::own_index () const noexcept
124 {
125 return own_index_;
126 }

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 319 of file test.h, definition at line 133 of file test-inlines.h.

133 runnable_base::own_index (size_t index) noexcept
134 {
135 own_index_ = index;
136 }

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 359 of file test.h, definition at line 187 of file test.cpp.

187 runnable_base::reporter (void) const noexcept
188 {
189 return runner_.reporter ();
190 }

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 504 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 380 of file test.h, definition at line 175 of file test-inlines.h.

175 runnable_base::runner (void) const noexcept
176 {
177 return runner_;
178 }

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 215 of file test.h, definition at line 111 of file test-inlines.h.

111 test_node::totals () const noexcept
112 {
113 return totals_;
114 }

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

totals()

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 394 of file test.h, definition at line 215 of file test.cpp.

216 std::unique_ptr<class subtest> child_test, suite& suite)
217 {
218 // Transfer ownership into the vector.
219 children_subtests_.push_back (std::move (child_test));
220
221 // Run the child test case immediately.
222 class subtest& subtest = *children_subtests_.back ();
223 subtest.run ();
224
225 // This test executed one more subtest.
226#if defined(MICRO_OS_PLUS_TRACE) \
227 && defined(MICRO_OS_PLUS_TRACE_MICRO_TEST_PLUS_CONSTRUCTORS)
228#if defined(__GNUC__)
229#pragma GCC diagnostic push
230#if defined(__clang__)
231#pragma clang diagnostic ignored "-Wunsafe-buffer-usage-in-libc-call"
232#endif
233#endif
234 trace::printf ("%s subtest '%s' executed one more subtest\n",
235 __PRETTY_FUNCTION__, name ());
236#if defined(__GNUC__)
237#pragma GCC diagnostic pop
238#endif
239#endif // MICRO_OS_PLUS_TRACE_MICRO_TEST_PLUS_CONSTRUCTORS
241 // Do not accumulate the totals from the child test into the current test
242 // totals, each subtest shows only its counters.
243
244#if defined(MICRO_OS_PLUS_TRACE) \
245 && defined(MICRO_OS_PLUS_TRACE_MICRO_TEST_PLUS_CONSTRUCTORS)
246#if defined(__GNUC__)
247#pragma GCC diagnostic push
248#if defined(__clang__)
249#pragma clang diagnostic ignored "-Wunsafe-buffer-usage-in-libc-call"
250#endif
251#endif
252 trace::printf ("%s suite '%s' totals\n", __PRETTY_FUNCTION__,
253 suite.name ());
254#if defined(__GNUC__)
255#pragma GCC diagnostic pop
256#endif
257#endif // MICRO_OS_PLUS_TRACE_MICRO_TEST_PLUS_CONSTRUCTORS
258
259 // Accumulate the totals from the child test into the suite totals.
260 suite.totals () += subtest.totals ();
261 }

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 512 of file test.h.

512 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 427 of file test.h.

427 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 417 of file test.h.

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

own_index_

template <typename Self_T>
size_t micro_os_plus::micro_test_plus::detail::runnable_base::own_index_
protected

runner_

template <typename Self_T>
class runner& micro_os_plus::micro_test_plus::detail::runnable_base::runner_
protected

totals_

template <typename Self_T>
runner_totals micro_os_plus::micro_test_plus::detail::test_node::totals_
protected

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


Generated via doxygen2docusaurus 2.2.0 by Doxygen 1.17.0.