suite Class

A named, runnable test suite registered with the test runner. More...

Declaration

class micro_os_plus::micro_test_plus::suite { ... }

Included Headers

#include <micro-os-plus/micro-test-plus.h>

Base class

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

Derived Classes

class	static_suite
	A test suite designed for static (namespace-scope) registration with a static_runner. More...
class	top_suite
	The implicit top-level suite owned by every runner instance. More...

Public Constructors Index

template <typename Callable_T, typename... Args_T>
suite (const char *name, class runner &runner, Callable_T &&callable, Args_T &&... arguments)
	Constructs a suite with a name, runner, and callable body. More...
	suite (const suite &)=delete
	Deleted copy constructor to prevent copying. More...
	suite (suite &&)=delete
	Deleted move constructor to prevent moving. More...

Public Destructor Index

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

Public Operators Index

suite &	operator= (const suite &)=delete
	Deleted copy assignment operator to prevent copying. More...
suite &	operator= (suite &&)=delete
	Deleted move assignment operator to prevent moving. More...

Public Member Functions Index

void	abort (const reflection::source_location &sl=reflection::source_location::current())
	Aborts test execution via the owning runner. More...
size_t	children_subtests_count (void) const noexcept
	Returns the number of direct child subtests owned by this node. More...
size_t	current_subtest_index () const noexcept
	Returns the index of the most recently created child subtest. More...
size_t	increment_subtest_index () noexcept
	Increments and returns the child subtest sequential index. More...
const char *	name (void) const noexcept
	Gets the node name. More...
size_t	own_index () const noexcept
	Returns the positional index of this object within its parent. More...
void	own_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...
void	run (void) override
	Executes the suite 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>
void	test (const char *name, Callable_T &&callable, Args_T &&... arguments)
	Adds a test case to the suite. More...
const detail::timestamps &	timings () const noexcept
	Gets the timings for this suite (const overload). More...
detail::timestamps &	timings () noexcept
	Gets the timings for this 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...

Protected Member Functions Index

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

std::function< void(suite &)>	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_t	current_subtest_index_
	The subtest index, counting from 1. More...
const char *	name_
	The test node name. More...
size_t	own_index_
	The test index, counting from 1. More...
class { ... }	runner_
	Reference to the test runner that owns this object. More...
detail::timestamps	timings_
	Timing measurements for this suite's execution. More...
runner_totals	totals_
	Totals for the test node, including nested cases. More...

Description

A named, runnable test suite registered with the test runner.

suite represents a top-level named group of related test cases within the µTest++ framework. It is created by calling runner::suite(), which constructs the object, stores it in the runner's collection, and runs it immediately. Each suite records its own timing information and propagates its results to the owning runner.

The body of a suite is supplied as a callable (typically a lambda) that receives a suite& reference as its first argument. Inside the body, suite::test() is called to create and run individual subtests.

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

Definition at line 713 of file test.h.

Public Constructors

suite()

template <typename Callable_T, typename... Args_T>

micro_os_plus::micro_test_plus::suite::suite (const char * name, class runner & runner, Callable_T && callable, Args_T &&... arguments)

Constructs a suite with a name, runner, and callable body.

Template Parameters

Callable_T	The type of the callable object.
Args_T	The types of any additional callable arguments.

Parameters

name	The suite name or description, used in reports.
runner	The test runner managing this suite.
callable	A generic callable object, usually a lambda, invoked when the suite executes. Its first parameter must be suite&.
arguments	A possibly empty list of arguments forwarded to the callable after the leading suite& reference.

Delegates to runnable, which binds the callable with its arguments. After construction, the suite is registered with the static test runner.

Declaration at line 731 of file test.h, definition at line 366 of file test-inlines.h.

366 suite::suite (const char* name, class runner& runner, Callable_T&& callable,

367 Args_T&&... arguments)

368 : runnable<suite>{ name, runner, 0, std::forward<Callable_T> (callable),

369 std::forward<Args_T> (arguments)... }

370 {

371#if defined(MICRO_OS_PLUS_MICRO_TEST_PLUS_TRACE_CONSTRUCTORS_ENABLED)

372#if defined(__GNUC__)

373#pragma GCC diagnostic push

374#if defined(__clang__)

375#pragma clang diagnostic ignored "-Wunsafe-buffer-usage-in-libc-call"

376#endif

377#endif

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

379#if defined(__GNUC__)

380#pragma GCC diagnostic pop

381#endif

382#endif // MICRO_OS_PLUS_MICRO_TEST_PLUS_TRACE_CONSTRUCTORS_ENABLED

383 }

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

Referenced by micro_os_plus::micro_test_plus::static_suite::static_suite, suite, suite, suite, operator= and operator=.

suite()

micro_os_plus::micro_test_plus::suite::suite (const suite &)

delete

Deleted copy constructor to prevent copying.

Definition at line 737 of file test.h.

Reference suite.

suite()

micro_os_plus::micro_test_plus::suite::suite (suite &&)

delete

Deleted move constructor to prevent moving.

Definition at line 742 of file test.h.

Reference suite.

Public Destructor

~suite()

micro_os_plus::micro_test_plus::suite::~suite ()

virtual

Virtual destructor.

No resources are owned directly by suite; the destructor performs no explicit clean-up. If tracing is enabled, the suite name is output for diagnostic purposes.

Declaration at line 761 of file test.h, definition at line 335 of file test.cpp.

335 suite::~suite ()

336 {

337#if defined(MICRO_OS_PLUS_MICRO_TEST_PLUS_TRACE_CONSTRUCTORS_ENABLED)

338#if defined(__GNUC__)

339#pragma GCC diagnostic push

340#if defined(__clang__)

341#pragma clang diagnostic ignored "-Wunsafe-buffer-usage-in-libc-call"

342#endif

343#endif

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

345#if defined(__GNUC__)

346#pragma GCC diagnostic pop

347#endif

348#endif // MICRO_OS_PLUS_MICRO_TEST_PLUS_TRACE_CONSTRUCTORS_ENABLED

349 }

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

Public Operators

operator=()

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

delete

Deleted copy assignment operator to prevent copying.

Definition at line 748 of file test.h.

Reference suite.

operator=()

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

delete

Deleted move assignment operator to prevent moving.

Definition at line 755 of file test.h.

References suite, micro_os_plus::micro_test_plus::detail::runnable< suite >::name, run, test and timings.

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

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

203 {

204 runner_.abort (sl);

205 }

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

164 runnable_base::children_subtests_count (void) const noexcept

165 {

166 return children_subtests_.size ();

167 }

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

142 runnable_base::current_subtest_index () const noexcept

143 {

144 return current_subtest_index_;

145 }

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

154 runnable_base::increment_subtest_index () noexcept

155 {

156 return ++current_subtest_index_;

157 }

Referenced by test.

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

90 test_node::name (void) const noexcept

91 {

92 return name_;

93 }

Referenced by micro_os_plus::micro_test_plus::static_suite::static_suite, suite, operator= and test.

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

122 runnable_base::own_index () const noexcept

123 {

124 return own_index_;

125 }

Referenced by test.

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

132 runnable_base::own_index (size_t index) noexcept

133 {

134 own_index_ = index;

135 }

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

190 runnable_base::reporter (void) const noexcept

191 {

192 return runner_.reporter ();

193 }

run()

void micro_os_plus::micro_test_plus::suite::run (void)

virtual

Executes the suite 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 suite.

Declaration at line 812 of file test.h, definition at line 357 of file test.cpp.

357 suite::run (void)

358 {

359#if defined(MICRO_OS_PLUS_MICRO_TEST_PLUS_TRACE_ENABLED)

360#if defined(__GNUC__)

361#pragma GCC diagnostic push

362#if defined(__clang__)

363#pragma clang diagnostic ignored "-Wunsafe-buffer-usage-in-libc-call"

364#endif

365#endif

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

367#if defined(__GNUC__)

368#pragma GCC diagnostic pop

369#endif

370#endif // MICRO_OS_PLUS_MICRO_TEST_PLUS_TRACE_ENABLED

371

372 class reporter& reporter = this->reporter ();

373

374 this->timings ().timestamp_begin ();

375 reporter.begin_suite (*this);

376

377 // Invoke the callable, passing the self reference followed by the variadic

378 // arguments.

379 callable_ (*this);

380

381 this->timings ().timestamp_end ();

382 reporter.end_suite (*this);

383 }

Referenced by 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 174 of file test-inlines.h.

174 runnable_base::runner (void) const noexcept

175 {

176 return runner_;

177 }

Referenced by suite and test.

test()

template <typename Callable_T, typename... Args_T>

void micro_os_plus::micro_test_plus::suite::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

name	The test case name or description, used in reports.
callable	A generic callable object, usually a lambda, invoked to perform the test.
arguments	A possibly empty list of arguments to be passed to the callable.

The test function template registers and executes a test case within the µTest++ framework. It accepts a descriptive name, a callable object (such as a lambda or function pointer), and an optional list of arguments to be passed to the callable. The test case is reported using the provided name, and its execution is managed by the framework's test runner.

Each test case typically involves evaluating a logical expression, such as comparing a computed result to an expected value. For C++ projects, it is also possible to verify whether evaluating an expression throws exceptions. Each test either succeeds or fails, and for expectations, the test runner maintains counts of successful and failed checks.

This function template enables flexible and expressive test case definitions, supporting both parameterised and non-parameterised tests. It is typically invoked at global scope or within test suite definitions to ensure automatic registration and execution.

A test case is characterised by a name, a function that performs the checks, and optionally, arguments to be passed to that function. The implementation of test invokes the provided function with the given arguments and reports the results to the test runner.

Example

 namespace mt = micro_os_plus::micro_test_plus;

 

 ts.test ("Check answer with comparator", [] (auto& t) {

  t.expect (mt::eq (compute_answer (), 42)) << "answer is 42";

 });

Declaration at line 779 of file test.h, definition at line 431 of file test-inlines.h.

431 suite::test (const char* name, Callable_T&& callable, Args_T&&... arguments)

432 {

433#if defined(MICRO_OS_PLUS_MICRO_TEST_PLUS_TRACE_ENABLED)

434#if defined(__GNUC__)

435#pragma GCC diagnostic push

436#if defined(__clang__)

437#pragma clang diagnostic ignored "-Wunsafe-buffer-usage-in-libc-call"

438#endif

439#endif

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

441#if defined(__GNUC__)

442#pragma GCC diagnostic pop

443#endif

444#endif // MICRO_OS_PLUS_MICRO_TEST_PLUS_TRACE_ENABLED

445

446 size_t own_index = increment_subtest_index ();

447 auto child_subtest

448 = std::make_unique<subtest> (name, runner (), *this, own_index, 1,

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

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

451

452 after_subtest_create_ (std::move (child_subtest), *this);

453 }

References micro_os_plus::micro_test_plus::detail::runnable< suite >::after_subtest_create_, micro_os_plus::micro_test_plus::detail::runnable< suite >::increment_subtest_index, micro_os_plus::micro_test_plus::detail::runnable< suite >::name, micro_os_plus::micro_test_plus::detail::runnable< suite >::own_index and micro_os_plus::micro_test_plus::detail::runnable< suite >::runner.

Referenced by operator=.

timings()

const detail::timestamps & micro_os_plus::micro_test_plus::suite::timings ()

inline nodiscard noexcept

Gets the timings for this suite (const overload).

Parameters

None.

Returns

A const reference to the timestamps instance.

Returns a const reference to the timestamps member.

Declaration at line 801 of file test.h, definition at line 470 of file test-inlines.h.

470 suite::timings () const noexcept

471 {

472 return timings_;

473 }

Reference timings_.

timings()

detail::timestamps & micro_os_plus::micro_test_plus::suite::timings ()

inline nodiscard noexcept

Gets the timings for this suite.

Parameters

None.

Returns

A reference to the timestamps instance.

Returns a reference to the timestamps member.

Declaration at line 791 of file test.h, definition at line 460 of file test-inlines.h.

460 suite::timings () noexcept

461 {

462 return timings_;

463 }

Referenced by micro_os_plus::micro_test_plus::reporter_human::end_suite, micro_os_plus::micro_test_plus::reporter_tap::end_suite, operator= and micro_os_plus::micro_test_plus::static_suite::run.

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

110 test_node::totals () const noexcept

111 {

112 return totals_;

113 }

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

100 test_node::totals () noexcept

101 {

102 return totals_;

103 }

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

218 runnable_base::after_subtest_create_ (

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

220 {

221 // Transfer ownership into the vector.

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

223

224 // Run the child test case immediately.

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

226 subtest.run ();

227

228 // This test executed one more subtest.

229#if defined(MICRO_OS_PLUS_MICRO_TEST_PLUS_TRACE_CONSTRUCTORS_ENABLED)

230#if defined(__GNUC__)

231#pragma GCC diagnostic push

232#if defined(__clang__)

233#pragma clang diagnostic ignored "-Wunsafe-buffer-usage-in-libc-call"

234#endif

235#endif

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

237 __PRETTY_FUNCTION__, name ());

238#if defined(__GNUC__)

239#pragma GCC diagnostic pop

240#endif

241#endif // MICRO_OS_PLUS_MICRO_TEST_PLUS_TRACE_CONSTRUCTORS_ENABLED

242 totals ().increment_executed_subtests ();

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

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

245

246#if defined(MICRO_OS_PLUS_MICRO_TEST_PLUS_TRACE_CONSTRUCTORS_ENABLED)

247#if defined(__GNUC__)

248#pragma GCC diagnostic push

249#if defined(__clang__)

250#pragma clang diagnostic ignored "-Wunsafe-buffer-usage-in-libc-call"

251#endif

252#endif

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

254 suite.name ());

255#if defined(__GNUC__)

256#pragma GCC diagnostic pop

257#endif

258#endif // MICRO_OS_PLUS_MICRO_TEST_PLUS_TRACE_CONSTRUCTORS_ENABLED

259

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

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

262 }

Referenced by test.

Protected Member Attributes

callable_

std::function<void (suite&)> micro_os_plus::micro_test_plus::detail::runnable< suite >::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 micro_os_plus::micro_test_plus::top_suite::name.

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.

417 size_t current_subtest_index_ = 0;

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 micro_os_plus::micro_test_plus::static_suite::~static_suite, ~suite, micro_os_plus::micro_test_plus::top_suite::~top_suite, micro_os_plus::micro_test_plus::top_suite::name and micro_os_plus::micro_test_plus::static_suite::run.

own_index_

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

protected

The test index, counting from 1.

Definition at line 406 of file test.h.

406 size_t own_index_;

Referenced by micro_os_plus::micro_test_plus::static_suite::static_suite.

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.

401 class runner& runner_;

timings_

detail::timestamps micro_os_plus::micro_test_plus::suite::timings_

protected

Timing measurements for this suite's execution.

Definition at line 818 of file test.h.

818 detail::timestamps timings_;

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

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.

229 runner_totals totals_;

---

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

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

---

Generated via doxygen2docusaurus 2.2.1 by Doxygen 1.17.0.