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

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

Inheritance diagram for micro_os_plus::micro_test_plus::subtest:

Public Member Functions
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.
	subtest (const subtest &)=delete
	Deleted copy constructor to prevent copying.
	subtest (subtest &&)=delete
	Deleted move constructor to prevent moving.
virtual	~subtest () override
	Virtual destructor.
void	abort (const reflection::source_location &sl=reflection::source_location::current())
	Aborts test execution via the owning runner.
template<class Expr_T> requires type_traits::checkable<Expr_T>
auto	assume (const Expr_T &expr, const reflection::source_location &sl=reflection::source_location::current())
	Check a condition and, if false, abort test execution.
size_t	children_subtests_count (void) const noexcept
	Returns the number of direct child subtests owned by this node.
size_t	current_subtest_index () const noexcept
	Returns the index of the most recently created child subtest.
template<class Expr_T> requires type_traits::checkable<Expr_T>
auto	expect (const Expr_T &expr, const reflection::source_location &sl=reflection::source_location::current())
	Evaluate a generic condition and report the results.
size_t	increment_subtest_index () noexcept
	Increments and returns the child subtest sequential index.
const char *	name (void) const noexcept
	Gets the node name.
size_t	nesting_depth () const noexcept
	Returns the nesting depth of this subtest.
subtest &	operator= (const subtest &)=delete
	Deleted copy assignment operator to prevent copying.
subtest &	operator= (subtest &&)=delete
	Deleted move assignment operator to prevent moving.
size_t	own_index () const noexcept
	Returns the positional index of this object within its parent.
void	own_index (size_t index) noexcept
	Sets the positional index of this object within its parent.
class reporter &	reporter (void) const noexcept
	Gets the test reporter associated with this test runnable.
virtual void	run (void) override
	Executes the subtest body by invoking the stored callable.
class runner &	runner (void) const noexcept
	Gets the test runner associated with this test runnable.
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.
const runner_totals &	totals () const noexcept
	Gets the totals for the test (const overload).
runner_totals &	totals () noexcept
	Gets the totals for the test.

Protected Member Functions
void	after_subtest_create_ (std::unique_ptr< subtest > child_test, suite &suite)
	Registers a newly constructed child subtest and executes it immediately.

Protected Attributes
std::function< void(subtest &)>	callable_
	Callable storing the test body and any bound arguments. Invoked with a reference to the derived Self_T instance.
std::vector< std::unique_ptr< subtest > >	children_subtests_
	Owning collection of direct child subtests.
size_t	current_subtest_index_
	The subtest index, counting from 1.
const char *	name_
	The test node name.
size_t	nesting_depth_
	The nesting depth of this subtest within the suite.
size_t	own_index_
	The test index, counting from 1.
suite &	parent_suite_
	Reference to the parent suite that owns this subtest.
class runner &	runner_
	Reference to the test runner that owns this object.
runner_totals	totals_
	Totals for the test node, including nested cases.

Detailed Description

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.

Constructor & Destructor Documentation

◆ subtest() [1/3]

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 )

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.

Definition at line 262 of file test-inlines.h.

      : runnable<subtest>{ name, runner, own_index,
                           std::forward<Callable_T> (callable),
                           std::forward<Args_T> (arguments)... },
        parent_suite_{ parent_suite }, nesting_depth_{ nesting_depth }
  {
#if defined(MICRO_OS_PLUS_TRACE) \
    && defined(MICRO_OS_PLUS_TRACE_MICRO_TEST_PLUS_CONSTRUCTORS)
#if defined(__GNUC__)
#pragma GCC diagnostic push
#if defined(__clang__)
#pragma clang diagnostic ignored "-Wunsafe-buffer-usage-in-libc-call"
#endif
#endif
    trace::printf ("%s '%s' %zu %zu\n", __PRETTY_FUNCTION__, name, own_index_,
                   nesting_depth_);
#if defined(__GNUC__)
#pragma GCC diagnostic pop
#endif
#endif // MICRO_OS_PLUS_TRACE_MICRO_TEST_PLUS_CONSTRUCTORS
  }

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() [2/3]

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

delete

References subtest().

◆ subtest() [3/3]

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

delete

References subtest().

◆ ~subtest()

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

overridevirtual

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.

Definition at line 275 of file test.cpp.

  {
#if defined(MICRO_OS_PLUS_TRACE) \
    && defined(MICRO_OS_PLUS_TRACE_MICRO_TEST_PLUS_CONSTRUCTORS)
#if defined(__GNUC__)
#pragma GCC diagnostic push
#if defined(__clang__)
#pragma clang diagnostic ignored "-Wunsafe-buffer-usage-in-libc-call"
#endif
#endif
    trace::printf ("%s '%s'\n", __PRETTY_FUNCTION__, name_);
#if defined(__GNUC__)
#pragma GCC diagnostic pop
#endif
#endif // MICRO_OS_PLUS_TRACE_MICRO_TEST_PLUS_CONSTRUCTORS
  }

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

Member Function Documentation

◆ abort()

void micro_os_plus::micro_test_plus::detail::runnable_base::abort ( const reflection::source_location & sl = reflection::source_location::current () )

inherited

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().

Definition at line 369 of file test.cpp.

    {
      runner_.abort (sl);
    }

References name_, and reporter().

◆ after_subtest_create_()

void micro_os_plus::micro_test_plus::detail::runnable_base::after_subtest_create_	(	std::unique_ptr< subtest >	child_test,
		suite &	suite )

protectedinherited

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.

Definition at line 394 of file test.cpp.

    {
      // Transfer ownership into the vector.
      children_subtests_.push_back (std::move (child_test));
 
      // Run the child test case immediately.
      class subtest& subtest = *children_subtests_.back ();
      subtest.run ();
 
      // This test executed one more subtest.
#if defined(MICRO_OS_PLUS_TRACE) \
    && defined(MICRO_OS_PLUS_TRACE_MICRO_TEST_PLUS_CONSTRUCTORS)
#if defined(__GNUC__)
#pragma GCC diagnostic push
#if defined(__clang__)
#pragma clang diagnostic ignored "-Wunsafe-buffer-usage-in-libc-call"
#endif
#endif
      trace::printf ("%s subtest '%s' executed one more subtest\n",
                     __PRETTY_FUNCTION__, name ());
#if defined(__GNUC__)
#pragma GCC diagnostic pop
#endif
#endif // MICRO_OS_PLUS_TRACE_MICRO_TEST_PLUS_CONSTRUCTORS
      totals ().increment_executed_subtests ();
      // Do not accumulate the totals from the child test into the current test
      // totals, each subtest shows only its counters.
 
#if defined(MICRO_OS_PLUS_TRACE) \
    && defined(MICRO_OS_PLUS_TRACE_MICRO_TEST_PLUS_CONSTRUCTORS)
#if defined(__GNUC__)
#pragma GCC diagnostic push
#if defined(__clang__)
#pragma clang diagnostic ignored "-Wunsafe-buffer-usage-in-libc-call"
#endif
#endif
      trace::printf ("%s suite '%s' totals\n", __PRETTY_FUNCTION__,
                     suite.name ());
#if defined(__GNUC__)
#pragma GCC diagnostic pop
#endif
#endif // MICRO_OS_PLUS_TRACE_MICRO_TEST_PLUS_CONSTRUCTORS
 
      // Accumulate the totals from the child test into the suite totals.
      suite.totals () += subtest.totals ();
    }

◆ children_subtests_count()

size_t micro_os_plus::micro_test_plus::detail::runnable_base::children_subtests_count ( void ) const

inlinenodiscardnoexceptinherited

Parameters: None.

Returns: The number of child subtests.

Returns the number of child subtests owned by this node.

Definition at line 349 of file test-inlines.h.

    {
      return children_subtests_.size ();
    }

◆ current_subtest_index()

size_t micro_os_plus::micro_test_plus::detail::runnable_base::current_subtest_index ( ) const

inlinenodiscardnoexceptinherited

Parameters: None.

Returns: The current child subtest sequential index.

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

Definition at line 329 of file test-inlines.h.

    {
      return current_subtest_index_;
    }

◆ increment_subtest_index()

size_t micro_os_plus::micro_test_plus::detail::runnable_base::increment_subtest_index ( )

inlinenoexceptinherited

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.

Definition at line 339 of file test-inlines.h.

    {
      return ++current_subtest_index_;
    }

◆ name()

const char * micro_os_plus::micro_test_plus::detail::test_node::name ( void ) const

inlinenodiscardnoexceptinherited

Parameters: None.

Returns: A pointer to the null-terminated test node name.

Returns a pointer to the null-terminated name stored in name_.

Definition at line 194 of file test-inlines.h.

    {
      return name_;
    }

Referenced by micro_os_plus::micro_test_plus::subtest::subtest(), micro_os_plus::micro_test_plus::subtest::operator=(), own_index(), runner(), micro_os_plus::micro_test_plus::subtest::test(), and totals().

◆ nesting_depth()

size_t micro_os_plus::micro_test_plus::subtest::nesting_depth ( ) const

inlinenodiscardnoexcept

Parameters: None.

Returns: The nesting depth (1 = top-level).

Top-level subtests (direct children of a suite) have depth 1. Each additional level of nesting increments the depth by 1.

Definition at line 357 of file test-inlines.h.

  {
    return nesting_depth_;
  }

References nesting_depth_.

◆ operator=() [1/2]

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

delete

References subtest().

◆ operator=() [2/2]

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

delete

References subtest(), assume(), micro_os_plus::micro_test_plus::reflection::source_location::current(), expect(), micro_os_plus::micro_test_plus::detail::runnable< subtest >::name(), nesting_depth(), run(), and test().

◆ own_index() [1/2]

size_t micro_os_plus::micro_test_plus::detail::runnable_base::own_index ( ) const

inlinenodiscardnoexceptinherited

Parameters: None.

Returns: The one-based own index.

Returns the one-based positional index of this object within its parent.

Definition at line 305 of file test-inlines.h.

    {
      return own_index_;
    }

References name(), own_index(), and runner().

Referenced by micro_os_plus::micro_test_plus::subtest::subtest(), and own_index().

◆ own_index() [2/2]

void micro_os_plus::micro_test_plus::detail::runnable_base::own_index ( size_t index )

inlinenoexceptinherited

Note: 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.

Definition at line 319 of file test-inlines.h.

    {
      own_index_ = index;
    }

◆ reporter()

reporter & micro_os_plus::micro_test_plus::detail::runnable_base::reporter ( void ) const

nodiscardnoexceptinherited

Parameters: None.

Returns: A reference to the test reporter.

Delegates immediately to runner_.reporter(), returning the reporter associated with the owning runner instance.

Definition at line 359 of file test.cpp.

    {
      return runner_.reporter ();
    }

Referenced by abort(), micro_os_plus::micro_test_plus::subtest::assume(), micro_os_plus::micro_test_plus::subtest::expect(), and micro_os_plus::micro_test_plus::subtest::run().

◆ run()

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

overridevirtual

Parameters: None.

Returns: Nothing.

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

Implements micro_os_plus::micro_test_plus::detail::runnable< subtest >.

Definition at line 298 of file test.cpp.

  {
#if defined(MICRO_OS_PLUS_TRACE) \
    && defined(MICRO_OS_PLUS_TRACE_MICRO_TEST_PLUS)
#if defined(__GNUC__)
#pragma GCC diagnostic push
#if defined(__clang__)
#pragma clang diagnostic ignored "-Wunsafe-buffer-usage-in-libc-call"
#endif
#endif
    trace::printf ("%s '%s'\n", __PRETTY_FUNCTION__, name_);
#if defined(__GNUC__)
#pragma GCC diagnostic pop
#endif
#endif // MICRO_OS_PLUS_TRACE_MICRO_TEST_PLUS
 
    class reporter& reporter = this->reporter ();
 
    // For now, subtests do not record the time.
    // this->timings.timestamp_begin ();
    reporter.begin_subtest (*this);
 
    // Invoke the callable, passing the self reference followed by the variadic
    // arguments.
    callable_ (*this);
 
    // this->timings.timestamp_end ();
    reporter.end_subtest (*this);
  }

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 ) const

inlinenodiscardnoexceptinherited

Parameters: None.

Returns: A reference to the test runner.

Returns a reference to the owning test runner.

Definition at line 380 of file test-inlines.h.

    {
      return runner_;
    }

References name(), and own_index_.

Referenced by micro_os_plus::micro_test_plus::subtest::subtest(), and 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 )

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_().

Definition at line 295 of file test-inlines.h.

  {
#if defined(MICRO_OS_PLUS_TRACE) \
    && defined(MICRO_OS_PLUS_TRACE_MICRO_TEST_PLUS)
#if defined(__GNUC__)
#pragma GCC diagnostic push
#if defined(__clang__)
#pragma clang diagnostic ignored "-Wunsafe-buffer-usage-in-libc-call"
#endif
#endif
    trace::printf ("%s '%s'\n", __PRETTY_FUNCTION__, name);
#if defined(__GNUC__)
#pragma GCC diagnostic pop
#endif
#endif // MICRO_OS_PLUS_TRACE_MICRO_TEST_PLUS
 
    size_t own_index = increment_subtest_index ();
    auto child_subtest = std::make_unique<subtest> (
        name, runner (), parent_suite_, own_index, nesting_depth_ + 1,
        std::forward<Callable_T> (callable),
        std::forward<Args_T> (arguments)...);
 
    after_subtest_create_ (std::move (child_subtest), parent_suite_);
  }

References micro_os_plus::micro_test_plus::detail::runnable< subtest >::name().

Referenced by operator=().

◆ totals() [1/2]

const runner_totals & micro_os_plus::micro_test_plus::detail::test_node::totals ( ) const

inlinenodiscardnoexceptinherited

Parameters: None.

Returns: A const reference to the runner_totals instance.

Returns a const reference to the runner_totals member.

Definition at line 215 of file test-inlines.h.

    {
      return totals_;
    }

References name(), and own_index_.

◆ totals() [2/2]

runner_totals & micro_os_plus::micro_test_plus::detail::test_node::totals ( )

inlinenodiscardnoexceptinherited

Parameters: None.

Returns: A reference to the runner_totals instance.

Returns a reference to the runner_totals member.

Definition at line 205 of file test-inlines.h.

    {
      return totals_;
    }

References callable_.

Member Data Documentation

◆ callable_

std::function<void (subtest&)> micro_os_plus::micro_test_plus::detail::runnable< subtest >::callable_

protectedinherited

Definition at line 512 of file test.h.

Referenced by micro_os_plus::micro_test_plus::subtest::run(), and totals().

◆ children_subtests_

std::vector<std::unique_ptr<subtest> > micro_os_plus::micro_test_plus::detail::runnable_base::children_subtests_

protectedinherited

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.

◆ current_subtest_index_

size_t micro_os_plus::micro_test_plus::detail::runnable_base::current_subtest_index_

protectedinherited

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_

protectedinherited

Note: 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::subtest::~subtest(), abort(), and micro_os_plus::micro_test_plus::subtest::run().

◆ nesting_depth_

size_t micro_os_plus::micro_test_plus::subtest::nesting_depth_

protected

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_

protectedinherited

Definition at line 406 of file test.h.

Referenced by runner(), and totals().

◆ parent_suite_

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

protected

Definition at line 683 of file test.h.

◆ runner_

class runner& micro_os_plus::micro_test_plus::detail::runnable_base::runner_

protectedinherited

Definition at line 401 of file test.h.

◆ totals_

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

protectedinherited

Definition at line 229 of file test.h.

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

Public Member Functions

Protected Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ subtest() [1/3]

◆ subtest() [2/3]

◆ subtest() [3/3]

◆ ~subtest()

Member Function Documentation

◆ abort()

◆ after_subtest_create_()

◆ children_subtests_count()

◆ current_subtest_index()

◆ increment_subtest_index()

◆ name()

◆ nesting_depth()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ own_index() [1/2]

◆ own_index() [2/2]

◆ reporter()

◆ run()

◆ runner()

◆ test()

◆ totals() [1/2]

◆ totals() [2/2]

Member Data Documentation

◆ callable_

◆ children_subtests_

◆ current_subtest_index_

◆ name_

◆ nesting_depth_

◆ own_index_

◆ parent_suite_

◆ runner_

◆ totals_