top_suite Class
The implicit top-level suite owned by every runner instance. More...
Declaration
Included Headers
Base class
| class | suite |
|
A named, runnable test suite registered with the test runner. More... | |
Public Constructors Index
| top_suite (const char *name, class runner &runner) | |
|
Constructs the top-level suite with a name and runner reference. More... | |
| top_suite (const top_suite &)=delete | |
|
Deleted copy constructor to prevent copying. More... | |
| top_suite (top_suite &&)=delete | |
|
Deleted move constructor to prevent moving. More... | |
Public Destructor Index
| ~top_suite () override | |
|
Virtual destructor. More... | |
Public Operators Index
| top_suite & | operator= (const top_suite &)=delete |
|
Deleted copy assignment operator to prevent copying. More... | |
| top_suite & | operator= (top_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... | |
| void | name (const char *new_name) noexcept |
|
Sets the name of the top-level suite. 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
The implicit top-level suite owned by every runner instance.
top_suite is a thin specialisation of suite used as the implicit root context for the runner. It is created by the runner constructor and is available to user code via runner::initialise(), which returns a reference to it. Unlike regular suite objects, top_suite is not stored in the runner's child-suite vector; instead it is a direct member of runner.
Users do not normally construct top_suite directly.
Definition at line 838 of file test.h.
Public Constructors
top_suite()
|
Constructs the top-level suite with a name and runner reference.
- Parameters
-
name The suite name used in reports.
runner The test runner that owns this suite.
Initialises the base suite with name, the given runner, and a no-op callable. Sets own_index to 1, reserving index 0 for the runner itself. If tracing is enabled, the name is output for diagnostic purposes.
Declaration at line 852 of file test.h, definition at line 394 of file test.cpp.
Referenced by top_suite, top_suite, operator= and operator=.
top_suite()
| delete |
top_suite()
Public Destructor
~top_suite()
| virtual |
Virtual destructor.
No resources are owned directly by top_suite; the destructor performs no explicit clean-up. If tracing is enabled, the suite name is output for diagnostic purposes.
Declaration at line 881 of file test.h, definition at line 419 of file test.cpp.
Reference micro_os_plus::micro_test_plus::detail::runnable< suite >::name_.
Public Operators
operator=()
| delete |
operator=()
Public Member Functions
abort()
|
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.
children_subtests_count()
| 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.
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.
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.
Referenced by micro_os_plus::micro_test_plus::suite::test.
name()
| inline noexcept |
Sets the name of the top-level suite.
- Parameters
-
new_name The new name for the top-level suite.
Sets the name of the top-level suite.
Used internally by the runner to set the name of the top suite after initialisation.
Declaration at line 889 of file test.h, definition at line 485 of file test-inlines.h.
Reference micro_os_plus::micro_test_plus::detail::runnable< suite >::name_.
Referenced by operator=.
name()
| 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 844 of file test.h, definition at line 90 of file test-inlines.h.
Reference micro_os_plus::micro_test_plus::detail::runnable< suite >::callable_.
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.
Referenced by micro_os_plus::micro_test_plus::suite::test.
own_index()
| inline noexcept |
Sets the positional index of this object within its parent.
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.
reporter()
| 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.
run()
| 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.
Referenced by micro_os_plus::micro_test_plus::suite::operator=.
runner()
| 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.
Referenced by micro_os_plus::micro_test_plus::suite::suite and micro_os_plus::micro_test_plus::suite::test.
test()
|
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
Declaration at line 779 of file test.h, definition at line 431 of file test-inlines.h.
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 micro_os_plus::micro_test_plus::suite::operator=.
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.
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.
Referenced by micro_os_plus::micro_test_plus::reporter_human::end_suite, micro_os_plus::micro_test_plus::reporter_tap::end_suite, micro_os_plus::micro_test_plus::suite::operator= and micro_os_plus::micro_test_plus::static_suite::run.
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.
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.
Protected Member Functions
after_subtest_create_()
| 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.
Referenced by micro_os_plus::micro_test_plus::suite::test.
Protected Member Attributes
callable_
| protected |
children_subtests_
| protected |
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_
| protected |
The test node name.
Derived classes may access this member directly in addition to the public name() getter.
Definition at line 224 of file test.h.
Referenced by micro_os_plus::micro_test_plus::static_suite::~static_suite, micro_os_plus::micro_test_plus::suite::~suite, ~top_suite, name and micro_os_plus::micro_test_plus::static_suite::run.
own_index_
| protected |
The test index, counting from 1.
Definition at line 406 of file test.h.
Referenced by micro_os_plus::micro_test_plus::static_suite::static_suite.
runner_
| protected |
timings_
| protected |
Timing measurements for this suite's execution.
Definition at line 818 of file test.h.
Referenced by micro_os_plus::micro_test_plus::detail::runnable< subtest >::runnable and micro_os_plus::micro_test_plus::suite::timings.
totals_
| protected |
Totals for the test node, including nested cases.
The documentation for this class was generated from the following files:
Generated via doxygen2docusaurus 2.2.1 by Doxygen 1.17.0.