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

[in] name	The suite name or description, used in reports.
[in] runner	The test runner managing this suite.
[in] callable	A generic callable object, usually a lambda, invoked when the suite executes. Its first parameter must be suite&.
[in] 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 371 of file test-inlines.h.

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

372 Args_T&&... arguments)

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

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

375 {

376#if defined(MICRO_OS_PLUS_TRACE) \

377 && defined(MICRO_OS_PLUS_TRACE_MICRO_TEST_PLUS_CONSTRUCTORS)

378#if defined(__GNUC__)

379#pragma GCC diagnostic push

380#if defined(__clang__)

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

382#endif

383#endif

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

385#if defined(__GNUC__)

386#pragma GCC diagnostic pop

387#endif

388#endif // MICRO_OS_PLUS_TRACE_MICRO_TEST_PLUS_CONSTRUCTORS

389 }

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, micro_os_plus::micro_test_plus::top_suite::top_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 336 of file test.cpp.

336 suite::~suite ()

337 {

338#if defined(MICRO_OS_PLUS_TRACE) \

339 && defined(MICRO_OS_PLUS_TRACE_MICRO_TEST_PLUS_CONSTRUCTORS)

340#if defined(__GNUC__)

341#pragma GCC diagnostic push

342#if defined(__clang__)

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

344#endif

345#endif

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

347#if defined(__GNUC__)

348#pragma GCC diagnostic pop

349#endif

350#endif // MICRO_OS_PLUS_TRACE_MICRO_TEST_PLUS_CONSTRUCTORS

351 }

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

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

200 {

201 runner_.abort (sl);

202 }

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.

165 runnable_base::children_subtests_count (void) const noexcept

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.

143 runnable_base::current_subtest_index () const noexcept

144 {

145 return current_subtest_index_;

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.

155 runnable_base::increment_subtest_index () noexcept

156 {

157 return ++current_subtest_index_;

158 }

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

91 test_node::name (void) const noexcept

92 {

93 return name_;

94 }

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

123 runnable_base::own_index () const noexcept

124 {

125 return own_index_;

126 }

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

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

359 suite::run (void)

360 {

361#if defined(MICRO_OS_PLUS_TRACE) \

362 && defined(MICRO_OS_PLUS_TRACE_MICRO_TEST_PLUS)

363#if defined(__GNUC__)

364#pragma GCC diagnostic push

365#if defined(__clang__)

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

367#endif

368#endif

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

370#if defined(__GNUC__)

371#pragma GCC diagnostic pop

372#endif

373#endif // MICRO_OS_PLUS_TRACE_MICRO_TEST_PLUS

374

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

376

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

378 reporter.begin_suite (*this);

379

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

381 // arguments.

382 callable_ (*this);

383

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

385 reporter.end_suite (*this);

386 }

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

175 runnable_base::runner (void) const noexcept

176 {

177 return runner_;

178 }

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

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

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

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

438 {

439#if defined(MICRO_OS_PLUS_TRACE) \

440 && defined(MICRO_OS_PLUS_TRACE_MICRO_TEST_PLUS)

441#if defined(__GNUC__)

442#pragma GCC diagnostic push

443#if defined(__clang__)

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

445#endif

446#endif

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

448#if defined(__GNUC__)

449#pragma GCC diagnostic pop

450#endif

451#endif // MICRO_OS_PLUS_TRACE_MICRO_TEST_PLUS

452

453 size_t own_index = increment_subtest_index ();

454 auto child_subtest

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

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

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

458

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

460 }

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

477 suite::timings () const noexcept

478 {

479 return timings_;

480 }

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

467 suite::timings () noexcept

468 {

469 return timings_;

470 }

Reference timings_.

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

111 test_node::totals () const noexcept

112 {

113 return totals_;

114 }

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.

101 test_node::totals () noexcept

102 {

103 return totals_;

104 }

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.

215 runnable_base::after_subtest_create_ (

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

240 totals ().increment_executed_subtests ();

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 }

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 timings 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.0 by Doxygen 1.17.0.