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

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

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

276 {
277#if defined(MICRO_OS_PLUS_TRACE) \
278 && defined(MICRO_OS_PLUS_TRACE_MICRO_TEST_PLUS_CONSTRUCTORS)
279#if defined(__GNUC__)
280#pragma GCC diagnostic push
281#if defined(__clang__)
282#pragma clang diagnostic ignored "-Wunsafe-buffer-usage-in-libc-call"
283#endif
284#endif
285 trace::printf ("%s '%s'\n", __PRETTY_FUNCTION__, name_);
286#if defined(__GNUC__)
287#pragma GCC diagnostic pop
288#endif
289#endif // MICRO_OS_PLUS_TRACE_MICRO_TEST_PLUS_CONSTRUCTORS
290 }

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

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

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

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

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

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

144 {
146 }

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

156 {
158 }

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

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

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

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

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

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

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

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

Referenced by micro_os_plus::micro_test_plus::detail::runnable< subtest >::abort, assume, 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 298 of file test.cpp.

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

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

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

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

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

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

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

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

102 {
103 return totals_;
104 }

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

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

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 and micro_os_plus::micro_test_plus::detail::runnable< subtest >::totals.

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.