Skip to main content

subtest Class

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

Declaration

class micro_os_plus::micro_test_plus::subtest { ... }

Included Headers

Base class

classrunnable<Self_T>

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

Public Constructors Index

template <typename Callable_T, typename... Args_T>
subtest (const char *name, class runner &runner, suite &parent_suite, size_t own_index, size_t nesting_depth, Callable_T &&callable, Args_T &&... arguments)

Constructs a subtest with a name, runner, parent suite, index, nesting depth, and callable. More...

subtest (const subtest &)=delete

Deleted copy constructor to prevent copying. More...

subtest (subtest &&)=delete

Deleted move constructor to prevent moving. More...

Public Destructor Index

~subtest () override

Virtual destructor. More...

Public Operators Index

subtest &operator= (const subtest &)=delete

Deleted copy assignment operator to prevent copying. More...

subtest &operator= (subtest &&)=delete

Deleted move assignment operator to prevent moving. More...

Public Member Functions Index

voidabort (const reflection::source_location &sl=reflection::source_location::current())

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

size_tchildren_subtests_count (void) const noexcept

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

size_tcurrent_subtest_index () const noexcept

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

size_tincrement_subtest_index () noexcept

Increments and returns the child subtest sequential index. More...

const char *name (void) const noexcept

Gets the node name. More...

size_tnesting_depth () const noexcept

Returns the nesting depth of this subtest. More...

size_town_index () const noexcept

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

voidown_index (size_t index) noexcept

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

class reporter &reporter (void) const noexcept

Gets the test reporter associated with this test runnable. More...

voidrun (void) override

Executes the subtest body by invoking the stored callable. More...

class runner &runner (void) const noexcept

Gets the test runner associated with this test runnable. More...

template <typename Callable_T, typename... Args_T>
voidtest (const char *name, Callable_T &&callable, Args_T &&... arguments)

Adds a test case to the suite. More...

const runner_totals &totals () const noexcept

Gets the totals for the test (const overload). More...

runner_totals &totals () noexcept

Gets the totals for the test. More...

template <class Expr_T>
autoassume (const Expr_T &expr, const reflection::source_location &sl=reflection::source_location::current())

Check a condition and, if false, abort test execution. More...

template <class Expr_T>
autoexpect (const Expr_T &expr, const reflection::source_location &sl=reflection::source_location::current())

Evaluate a generic condition and report the results. More...

Protected Member Functions Index

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

std::function< void(subtest &)>callable_

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

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

Owning collection of direct child subtests. More...

size_tcurrent_subtest_index_

The subtest index, counting from 1. More...

const char *name_

The test node name. More...

size_tnesting_depth_

The nesting depth of this subtest within the suite. More...

size_town_index_

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

suite &parent_suite_

Reference to the parent suite that owns this subtest. More...

class { ... }runner_

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

runner_totalstotals_

Totals for the test node, including nested cases. More...

Description

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

subtest represents a single, named test case or a nested group of checks within a parent suite or subtest. It is constructed by calling suite::test() or subtest::test(), both of which create the object, immediately execute its callable body via run(), and register the result with the parent node.

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

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

Definition at line 541 of file test.h.

Public Constructors

subtest()

template <typename Callable_T, typename... Args_T>
micro_os_plus::micro_test_plus::subtest::subtest (const char * name, class runner & runner, suite & parent_suite, size_t own_index, size_t nesting_depth, Callable_T && callable, Args_T &&... arguments)

Constructs a subtest with a name, runner, parent suite, index, nesting depth, and callable.

Template Parameters
Callable_T

The type of a callable object.

Args_T

The types of the callable arguments.

Parameters
[in] name

The subtest name or description, used in reports.

[in] runner

The test runner managing this subtest.

[in] parent_suite

The suite that owns this subtest.

[in] own_index

The one-based positional index within the parent.

[in] nesting_depth

The depth of nesting; 1 for top-level subtests.

[in] callable

A generic callable object, usually a lambda, invoked when the subtest executes.

[in] arguments

A possibly empty list of arguments forwarded to the callable after the leading subtest& reference.

Delegates to runnable, which binds the callable with its arguments.

Declaration at line 563 of file test.h, definition at line 263 of file test-inlines.h.

263 subtest::subtest (const char* name, class runner& runner,
264 suite& parent_suite, size_t own_index,
265 size_t nesting_depth, Callable_T&& callable,
266 Args_T&&... arguments)
268 std::forward<Callable_T> (callable),
269 std::forward<Args_T> (arguments)... },
270 parent_suite_{ parent_suite }, nesting_depth_{ nesting_depth }
271 {
272#if defined(MICRO_OS_PLUS_TRACE) \
273 && defined(MICRO_OS_PLUS_MICRO_TEST_PLUS_TRACE_CONSTRUCTORS_ENABLED)
274#if defined(__GNUC__)
275#pragma GCC diagnostic push
276#if defined(__clang__)
277#pragma clang diagnostic ignored "-Wunsafe-buffer-usage-in-libc-call"
278#endif
279#endif
280 trace::printf ("%s '%s' %zu %zu\n", __PRETTY_FUNCTION__, name, own_index_,
281 nesting_depth_);
282#if defined(__GNUC__)
283#pragma GCC diagnostic pop
284#endif
285#endif // MICRO_OS_PLUS_MICRO_TEST_PLUS_TRACE_CONSTRUCTORS_ENABLED
286 }

References micro_os_plus::micro_test_plus::detail::runnable< subtest >::runnable, subtest, micro_os_plus::micro_test_plus::detail::runnable< subtest >::name, nesting_depth, micro_os_plus::micro_test_plus::detail::runnable< subtest >::own_index and micro_os_plus::micro_test_plus::detail::runnable< subtest >::runner.

Referenced by subtest, subtest, subtest, operator= and operator=.

subtest()

micro_os_plus::micro_test_plus::subtest::subtest (const subtest &)
delete

Deleted copy constructor to prevent copying.

Definition at line 570 of file test.h.

Reference subtest.

subtest()

micro_os_plus::micro_test_plus::subtest::subtest (subtest &&)
delete

Deleted move constructor to prevent moving.

Definition at line 575 of file test.h.

Reference subtest.

Public Destructor

~subtest()

micro_os_plus::micro_test_plus::subtest::~subtest ()
virtual

Virtual destructor.

The destructor releases any resources associated with the subtest instance. If tracing is enabled, it outputs the function signature for diagnostic purposes. This ensures that the test suite is properly cleaned up after execution, supporting robust and reliable test management across all files and folders within the µTest++ framework.

Declaration at line 594 of file test.h, definition at line 284 of file test.cpp.

285 {
286#if defined(MICRO_OS_PLUS_TRACE) \
287 && defined(MICRO_OS_PLUS_MICRO_TEST_PLUS_TRACE_CONSTRUCTORS_ENABLED)
288#if defined(__GNUC__)
289#pragma GCC diagnostic push
290#if defined(__clang__)
291#pragma clang diagnostic ignored "-Wunsafe-buffer-usage-in-libc-call"
292#endif
293#endif
294 trace::printf ("%s '%s'\n", __PRETTY_FUNCTION__, name_);
295#if defined(__GNUC__)
296#pragma GCC diagnostic pop
297#endif
298#endif // MICRO_OS_PLUS_MICRO_TEST_PLUS_TRACE_CONSTRUCTORS_ENABLED
299 }

Reference micro_os_plus::micro_test_plus::detail::runnable< subtest >::name_.

Public Operators

operator=()

subtest & micro_os_plus::micro_test_plus::subtest::operator= (const subtest &)
delete

Deleted copy assignment operator to prevent copying.

Definition at line 581 of file test.h.

Reference subtest.

operator=()

subtest & micro_os_plus::micro_test_plus::subtest::operator= (subtest &&)
delete

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

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 208 of file test.cpp.

209 {
210 runner_.abort (sl);
211 }

References micro_os_plus::micro_test_plus::reporter::begin_suite, micro_os_plus::micro_test_plus::detail::runnable< suite >::callable_, micro_os_plus::micro_test_plus::detail::runnable< subtest >::name_, micro_os_plus::micro_test_plus::detail::runnable< subtest >::reporter, micro_os_plus::micro_test_plus::detail::runnable< suite >::reporter, micro_os_plus::micro_test_plus::detail::timestamps::timestamp_begin, micro_os_plus::micro_test_plus::detail::timestamps::timestamp_end and micro_os_plus::micro_test_plus::suite::timings.

children_subtests_count()

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

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

current_subtest_index()

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

145 {
147 }

increment_subtest_index()

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

157 {
159 }

name()

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

92 test_node::name (void) const noexcept
93 {
94 return name_;
95 }

Referenced by subtest, operator=, micro_os_plus::micro_test_plus::detail::runnable< subtest >::own_index, micro_os_plus::micro_test_plus::detail::runnable< subtest >::runner, test and micro_os_plus::micro_test_plus::detail::runnable< subtest >::totals.

nesting_depth()

size_t micro_os_plus::micro_test_plus::subtest::nesting_depth ()
inline nodiscard noexcept

own_index()

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

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

References micro_os_plus::micro_test_plus::detail::runnable< subtest >::name, micro_os_plus::micro_test_plus::detail::runnable< subtest >::own_index and micro_os_plus::micro_test_plus::detail::runnable< subtest >::runner.

Referenced by subtest and micro_os_plus::micro_test_plus::detail::runnable< subtest >::own_index.

own_index()

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

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

reporter()

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 196 of file test.cpp.

196 runnable_base::reporter (void) const noexcept
197 {
198 return runner_.reporter ();
199 }

Referenced by micro_os_plus::micro_test_plus::detail::runnable< subtest >::abort, expect and run.

run()

void micro_os_plus::micro_test_plus::subtest::run (void)
virtual

Executes the subtest body by invoking the stored callable.

Parameters

None.

Returns

Nothing.

Invokes the stored callable with the Self_T instance, surrounded by reporter calls to begin and end the subtest.

Declaration at line 667 of file test.h, definition at line 307 of file test.cpp.

308 {
309#if defined(MICRO_OS_PLUS_TRACE) \
310 && defined(MICRO_OS_PLUS_MICRO_TEST_PLUS_TRACE_ENABLED)
311#if defined(__GNUC__)
312#pragma GCC diagnostic push
313#if defined(__clang__)
314#pragma clang diagnostic ignored "-Wunsafe-buffer-usage-in-libc-call"
315#endif
316#endif
317 trace::printf ("%s '%s'\n", __PRETTY_FUNCTION__, name_);
318#if defined(__GNUC__)
319#pragma GCC diagnostic pop
320#endif
321#endif // MICRO_OS_PLUS_MICRO_TEST_PLUS_TRACE_ENABLED
322
323 class reporter& reporter = this->reporter ();
324
325 // For now, subtests do not record the time.
326 // this->timings.timestamp_begin ();
327 reporter.begin_subtest (*this);
328
329 // Invoke the callable, passing the self reference followed by the variadic
330 // arguments.
331 callable_ (*this);
332
333 // this->timings.timestamp_end ();
334 reporter.end_subtest (*this);
335 }

References micro_os_plus::micro_test_plus::reporter::begin_subtest, micro_os_plus::micro_test_plus::detail::runnable< subtest >::callable_, micro_os_plus::micro_test_plus::detail::runnable< subtest >::name_ and micro_os_plus::micro_test_plus::detail::runnable< subtest >::reporter.

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

runner()

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

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

References micro_os_plus::micro_test_plus::detail::runnable< subtest >::name and micro_os_plus::micro_test_plus::detail::runnable< subtest >::own_index_.

Referenced by subtest and micro_os_plus::micro_test_plus::detail::runnable< subtest >::own_index.

test()

template <typename Callable_T, typename... Args_T>
void micro_os_plus::micro_test_plus::subtest::test (const char * name, Callable_T && callable, Args_T &&... arguments)

Adds a test case to the suite.

Template Parameters
Callable_T

The type of a callable object.

Args_T

The types of the callable arguments.

Parameters
[in] name

The test case name or description, used in reports.

[in] callable

A generic callable object, usually a lambda, invoked to perform the test.

[in] arguments

A possibly empty list of arguments to be passed to the callable.

Allocates a child subtest on the heap, incrementing the subtest index and deepening the nesting level by one relative to this subtest's depth, then transfers ownership to the framework via after_subtest_create_().

Declaration at line 612 of file test.h, definition at line 296 of file test-inlines.h.

296 subtest::test (const char* name, Callable_T&& callable,
297 Args_T&&... arguments)
298 {
299#if defined(MICRO_OS_PLUS_TRACE) \
300 && defined(MICRO_OS_PLUS_MICRO_TEST_PLUS_TRACE_ENABLED)
301#if defined(__GNUC__)
302#pragma GCC diagnostic push
303#if defined(__clang__)
304#pragma clang diagnostic ignored "-Wunsafe-buffer-usage-in-libc-call"
305#endif
306#endif
307 trace::printf ("%s '%s'\n", __PRETTY_FUNCTION__, name);
308#if defined(__GNUC__)
309#pragma GCC diagnostic pop
310#endif
311#endif // MICRO_OS_PLUS_MICRO_TEST_PLUS_TRACE_ENABLED
312
314 auto child_subtest = std::make_unique<subtest> (
316 std::forward<Callable_T> (callable),
317 std::forward<Args_T> (arguments)...);
318
319 after_subtest_create_ (std::move (child_subtest), parent_suite_);
320 }

Reference micro_os_plus::micro_test_plus::detail::runnable< subtest >::name.

Referenced by operator=.

totals()

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

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

References micro_os_plus::micro_test_plus::detail::runnable< subtest >::name and micro_os_plus::micro_test_plus::detail::runnable< subtest >::own_index_.

totals()

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

103 {
104 return totals_;
105 }

Protected Member Functions

after_subtest_create_()

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 224 of file test.cpp.

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

Protected Member Attributes

callable_

std::function<void (subtest&)> micro_os_plus::micro_test_plus::detail::runnable< subtest >::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_;

Referenced by run.

children_subtests_

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_;

current_subtest_index_

size_t micro_os_plus::micro_test_plus::detail::runnable_base::current_subtest_index_
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.

name_

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

224 const char* name_;

Referenced by ~subtest, micro_os_plus::micro_test_plus::detail::runnable< subtest >::abort and run.

nesting_depth_

size_t micro_os_plus::micro_test_plus::subtest::nesting_depth_
protected

The nesting depth of this subtest within the suite.

Definition at line 688 of file test.h.

Referenced by nesting_depth.

own_index_

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

parent_suite_

suite& micro_os_plus::micro_test_plus::subtest::parent_suite_
protected

Reference to the parent suite that owns this subtest.

Definition at line 683 of file test.h.

runner_

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

totals_

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

Totals for the test node, including nested cases.

Definition at line 229 of file test.h.


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


Generated via doxygen2docusaurus 2.2.0 by Doxygen 1.17.0.