micro_os_plus::micro_test_plus::runner Class Reference

The test runner for the µTest++ framework. More...

#include "micro-os-plus/micro-test-plus.h"

Public Types
using	abort_handler_t = void (*) (const reflection::source_location& sl)
	The type of the function called when test execution is aborted.

Public Member Functions
	runner (const runner &)=delete
	Deleted copy constructor to prevent copying.
	runner (runner &&)=delete
	Deleted move constructor to prevent moving.
	runner (void)
	Constructor for the runner class.
	~runner ()
	Destructor for the runner class.
void	abort (const reflection::source_location &sl=reflection::source_location::current())
	Aborts test execution immediately.
template<typename Callable_T, typename... Args_T> requires detail::suite_body<Callable_T, Args_T...>
void	add_suite (located_name name, Callable_T &&callable, Args_T &&... arguments)
	Adds a test suite to the runner, to be run by run_suites().
class suite &	add_top_suite (const located_name &top_suite_name)
	Adds the top suite and returns it.
class suite &	add_top_suite (void)
	Adds the top suite, without a name, and returns it.
size_t	added_suites_count (void) const noexcept
	Returns the count of the test suites added with add_suite().
std::span< const std::string >	application_arguments (void) const noexcept
	Returns the command-line arguments left to the application.
void	initialise (int argc, char *argv[])
	Initialises the test runner with the command-line arguments.
void	initialise (runner_options options)
	Initialises the test runner with the given options.
bool	is_listing (void) const noexcept
	Checks whether the test cases are listed instead of run.
runner &	operator= (const runner &)=delete
	Deleted copy assignment operator to prevent copying.
runner &	operator= (runner &&)=delete
	Deleted move assignment operator to prevent moving.
int	run_suites (void)
	Runs the registered suites, ends the session, and returns the exit code.
abort_handler_t	set_abort_handler (abort_handler_t handler) noexcept
	Sets the function called when test execution is aborted.
size_t	skipped_suites_count (void) const noexcept
	Returns the count of the test suites skipped by the filter.
size_t	static_suites_count (void) const noexcept
	Returns the count of static test suites.
size_t	total_suites_count (void) const noexcept
	Returns the count of all the test suites.
const counters &	totals (void) const noexcept
	Returns the totals of the test session.
auto	verbosity_level (void) const noexcept -> micro_test_plus::verbosity
	Returns the verbosity level of the console output.
Deprecated Functions
	runner (const char *top_suite_name)
	Deprecated constructor for the runner class.
class suite &	initialise (int argc, char *argv[], const char *top_suite_name)
	Deprecated initialisation with the command-line arguments, which also adds the top suite.
int	exit_code (void)
	Deprecated name of run_suites().
template<typename Callable_T, typename... Args_T>
void	suite (std::string_view name, Callable_T &&callable, Args_T &&... arguments)
	Deprecated name of add_suite().
auto	verbosity (void) const noexcept -> micro_test_plus::verbosity
	Deprecated name of verbosity_level().
const char *	name (void) const noexcept
	Deprecated name of the runner.
size_t	suites_count (void) const noexcept
	Deprecated count of the test suites added with add_suite(), plus the top suite.
const detail::stopwatch &	timings (void) const noexcept
	Deprecated access to the timings of the test session.
detail::stopwatch &	timings (void) noexcept
	Deprecated access to the timings of the test session, as a non-const reference.
detail::reporter &	reporter (void) const noexcept
	Deprecated access to the reporter of the test session.

Private Types
enum class	session_state {   created ,   initialised ,   declined ,   running ,   finished }
	The states of a test session. More...

Private Member Functions
void	abort (const reflection::source_location &sl, bool is_requirement)
	Aborts test execution, telling the reporter why.
bool	has_option_errors (void) const noexcept
	Checks whether an option error was found by initialise().
bool	is_selected (const char *name, size_t level) const
	Checks whether a suite or a test case is selected by the filter pattern of its nesting level.
void	list_test_case (const class suite &suite, const class test_case &test_case)
	Lists a test case, instead of running it.
void	mark_rejected (void) noexcept
	Records that a call was rejected.
void	register_suite (std::unique_ptr< class suite > suite)
	Registers a test suite with the runner.
void	reject_call (const std::string &message, const reflection::source_location *location=nullptr)
	Reports a rejected call, and records it.
void	reject_suite (const char *name, const reflection::source_location &location)
	Rejects a suite constructed after run_suites() has started.
void	run_child_suites (void)
	Runs all registered test suites.

Static Private Member Functions
static void	link_static_suite (runner &test_runner, class suite &suite) noexcept
	Inserts a static suite into the list of suites, or reject it.

Private Attributes
abort_handler_t	abort_handler_ = nullptr
	The function called by abort(), if not null.
bool	aborted_ = false
	Whether the test execution was aborted.
std::vector< std::unique_ptr< class suite > >	children_suites_
	Owning collection of dynamically registered child suites.
int	exit_code_ = 1
	The exit code computed by run_suites().
bool	has_rejected_calls_ = false
	Whether a call was rejected.
bool	has_top_suite_ = false
	Whether the top suite was added to the session.
const class suite *	listed_suite_ = nullptr
	The suite whose name was listed last, if any.
size_t	listed_suites_count_ = 0
	The number of suites with listed test cases.
size_t	listed_test_cases_count_ = 0
	The number of listed test cases.
runner_options	options_ {}
	The options of the test session.
std::unique_ptr< detail::reporter >	reporter_
	Owning pointer to the test reporter used for outputting test results.
class suite *	running_suite_ = nullptr
	The suite whose body is running, if any.
test_case *	running_test_case_ = nullptr
	The innermost test case being run, if any.
session_state	session_state_ = session_state::created
	The current state of the test session.
size_t	skipped_suites_count_ = 0
	The number of suites skipped by the filter.
runner *	started_next_ = nullptr
	The next runner in the list of the started runners.
detail::stopwatch	stopwatch_
	Stopwatch of this runner.
class top_suite	top_suite_
	The top suite, whose body is the code of main().
counters	totals_
	Totals of the test session.

Static Private Attributes
static runner *	started_first_ = nullptr
	The head of the list of the runners that have started.

Friends
class	detail::reporter_human
	The human-readable reporter, which displays the session.
class	detail::reporter_tap
	The TAP reporter, which displays the session.
class	detail::runnable_base
	The base of the nodes, which shares the state of the session.
class	static_suite
	The static suites link themselves through the runner.

Detailed Description

The runner class is responsible for managing the registration and execution of test suites within the µTest++ framework. It owns the optional top suite, returned by add_top_suite(), whose test cases run immediately, in main(), and a collection of test suites added with add_suite(), which are run later, by run_suites(). These suites and the static_suite objects that refer to the runner are kept in a single list, sorted by name, independent of the runner object, so the static suites may be constructed before it. run_suites() runs the suites added with add_suite() and the static suites together, in a single order, sorted by name; for equal names, in the order of their creation, so the static suites constructed before main() run first. The names are compared byte by byte, as by std::strcmp(), not in the order of addition: the comparison is case-sensitive ("Zeta" before "alpha") and does not compare numbers by value ("Suite 10" before "Suite 2"); zero-padded numeric prefixes ("01 - Init") give an explicit order.

Several runners may coexist, global or local, each with its own static suites and suites added with add_suite(). The list of suites is shared by all the runners; each suite refers to its runner, and run_suites() runs only the suites that refer to this runner, skipping those of the other runners, so the runners do not interfere. The list is not protected by a lock: the runners must not run, and the suites must not be created or destroyed, concurrently from different threads.

The test runner provides member functions for initialising the test environment (including the creation of the reporter selected by the runner_options passed to initialise()), registering test suites, and determining the overall test result via an exit code. It also offers an abort mechanism for terminating test execution in exceptional circumstances.

Both initialise() and add_top_suite() are optional:

mt::runner tr;
 
int
main (int argc, char* argv[])
{
  tr.initialise (argc, argv);
 
  auto& ts = tr.add_top_suite ("Main");
  ts.test ("Check something", [] (auto& t) { t.expect (true); });
 
  return tr.run_suites ();
}

Without initialise(), the default options are used; without add_top_suite(), there is no top suite, and run_suites() runs only the suites added with add_suite() and the static suites.

The runner is not a node of the test tree: it has no name of its own (the names shown in the reports belong to the suites), and it owns the session totals, which accumulate the totals of all the suites.

All members are defined within the micro_os_plus::micro_test_plus namespace.

Definition at line 186 of file runner.h.

Member Typedef Documentation

abort_handler_t

using micro_os_plus::micro_test_plus::runner::abort_handler_t = void (*) (const reflection::source_location& sl)

The handler receives the source location from which the abort was triggered. It is not expected to return; it may, for example, reset an embedded target, or signal the test result to a debugger. If it returns, the process is terminated with ::abort().

When exceptions are enabled, it may also throw an exception, to return control to the application without terminating the process. The test cases and the suites do not catch it, so it leaves the test() call that started a test case of the top suite, or run_suites(), and reaches the application; their remaining code is not run. The report is complete, but the runner cannot be used afterwards (see abort()).

Since

6.0.0

Definition at line 670 of file runner.h.

Member Enumeration Documentation

session_state

enum class micro_os_plus::micro_test_plus::runner::session_state

strongprivate

The session moves only forwards, from created to initialised (by initialise()), to running, and to finished (both by run_suites()); the calls made in another state are reported or ignored. When initialise() declines to run the session (--help, option errors, or an output file that cannot be opened), the state is declined, in which the suites are discarded silently.

Enumerator
created	Constructed; initialise() not yet called.
initialised	Initialised; test cases may be added and run.
declined	Nothing runs (help or option errors); calls ignored.
running	run_suites() runs the suites; no suite may be added.
finished	All suites run and the session ended.

Definition at line 1328 of file runner.h.

    {
      created, 
      initialised, 
      declined, 
      running, 
      finished 
    };

Constructor & Destructor Documentation

runner() [1/4]

micro_os_plus::micro_test_plus::runner::runner

(

void

)

The session is configured later, by initialise(), and the top suite, if any, is added by add_top_suite().

Parameters

None.

The constructor initialises a new runner instance together with its top suite (top_suite_). If tracing is enabled, it outputs the function signature for diagnostic purposes.

Definition at line 120 of file runner.cpp.

                      : top_suite_{ "", *this }
  {
#if defined(MICRO_OS_PLUS_MICRO_TEST_PLUS_TRACE_CONSTRUCTORS_ENABLED)
    trace::printf ("%s '%s'\n", __PRETTY_FUNCTION__, top_suite_.name ());
#endif // MICRO_OS_PLUS_MICRO_TEST_PLUS_TRACE_CONSTRUCTORS_ENABLED
  }

References micro_os_plus::micro_test_plus::detail::runnable_base::name(), and top_suite_.

Referenced by runner(), runner(), ~runner(), link_static_suite(), operator=(), and operator=().

runner() [2/4]

micro_os_plus::micro_test_plus::runner::runner

(

const char *

top_suite_name

)

Use the anonymous constructor, and pass the name to add_top_suite(), which can also override the name given here.

Parameters

top_suite_name

The name given to the top suite.

Deprecated

use runner() and add_top_suite() (since 4.1.0)

The constructor initialises a new runner instance together with its top suite (top_suite_). If tracing is enabled, it outputs the function signature for diagnostic purposes.

Definition at line 135 of file runner.cpp.

      : top_suite_{ top_suite_name, *this }
  {
#if defined(MICRO_OS_PLUS_MICRO_TEST_PLUS_TRACE_CONSTRUCTORS_ENABLED)
    trace::printf ("%s '%s'\n", __PRETTY_FUNCTION__, top_suite_.name ());
#endif // MICRO_OS_PLUS_MICRO_TEST_PLUS_TRACE_CONSTRUCTORS_ENABLED
  }

References micro_os_plus::micro_test_plus::detail::runnable_base::name(), and top_suite_.

runner() [3/4]

micro_os_plus::micro_test_plus::runner::runner ( const runner & )

delete

The runner owns the suites, the reporter, and the session totals, which must not be duplicated.

References runner().

runner() [4/4]

micro_os_plus::micro_test_plus::runner::runner ( runner && )

delete

The suites keep a reference to the runner, so it must not be relocated.

References runner().

~runner()

micro_os_plus::micro_test_plus::runner::~runner

(

)

Destroys the registered suites and the reporter, which closes the output file, if any. The static suites are not owned by the runner.

The reporter_ unique pointer is released automatically. If tracing is enabled, the function signature is output for diagnostic purposes.

Definition at line 149 of file runner.cpp.

  {
#if defined(MICRO_OS_PLUS_MICRO_TEST_PLUS_TRACE_CONSTRUCTORS_ENABLED)
    trace::printf ("%s\n", __PRETTY_FUNCTION__);
#endif // MICRO_OS_PLUS_MICRO_TEST_PLUS_TRACE_CONSTRUCTORS_ENABLED
 
    for (runner** slot = &started_first_; *slot != nullptr;
         slot = &(*slot)->started_next_)
      {
        if (*slot == this)
          {
            *slot = started_next_;
            break;
          }
      }
 
    // reporter_ is a unique_ptr; destroyed automatically.
  }

References runner(), started_first_, and started_next_.

Member Function Documentation

abort() [1/2]

void micro_os_plus::micro_test_plus::runner::abort ( const reflection::source_location & sl, bool is_requirement )

private

Implements abort(), which calls it for an explicit abort; also called by detail::runnable_base, a friend, for a failed requirement without exceptions, so that the reporter names the cause.

Parameters

sl	The source location from which the abort is triggered.
is_requirement	true if the abort is caused by a failed requirement.

Returns

Does not return.

While the report is open, from initialise(), which begins it (the test cases of the top suite run from then on), to the end of run_suites(), the reporter writes the buffered results and the location of the abort, with abort_session(), to the console and to the output file, since the totals are never reached. Otherwise, there is no report to complete, and the location is written to stderr. The standard streams are then flushed, and the handler set by set_abort_handler() is called, if any. If there is no handler, or if it returns, the process is terminated via ::abort().

The aborted_ flag is set first, and never cleared, so that, if the handler throws an exception, the test cases and the suites pass it on (see test_case::run()), and the runner refuses to run again. An abort after another one, for example from the code that caught the exception, is not reported again, since the report is already complete; the handler is still called.

Definition at line 1029 of file runner.cpp.

  {
#if defined(MICRO_OS_PLUS_MICRO_TEST_PLUS_TRACE_ENABLED)
    trace::printf ("%s\n", __PRETTY_FUNCTION__);
#endif // MICRO_OS_PLUS_MICRO_TEST_PLUS_TRACE_ENABLED
 
    if (!aborted_)
      {
        aborted_ = true;
 
        if (session_state_ == session_state::initialised
            || session_state_ == session_state::running)
          {
            reporter_->abort_session (sl, is_requirement);
          }
        else
          {
            // The type of `line()` depends on the toolchain
            // (`uint_least32_t` for `std::source_location`); widen it
            // implicitly, without a cast that would be useless on some
            // platforms.
            const unsigned long line = sl.line ();
            fprintf (stderr, "error: test execution aborted at %s:%lu\n",
                     utility::extract_file_name (sl.file_name ()), line);
          }
      }
 
    fflush (stdout);
    fflush (stderr);
 
    if (abort_handler_ != nullptr)
      {
        abort_handler_ (sl);
      }
 
    ::abort ();
  }

References abort(), abort_handler_, aborted_, micro_os_plus::micro_test_plus::utility::extract_file_name(), micro_os_plus::micro_test_plus::reflection::source_location::file_name(), initialised, micro_os_plus::micro_test_plus::reflection::source_location::line(), reporter_, running, and session_state_.

abort() [2/2]

void micro_os_plus::micro_test_plus::runner::abort

(

const reflection::source_location &

sl = reflection::source_location::current ()

)

Between initialise() and the end of run_suites(), the reporter completes the report, on the console and in the output file: it writes the results of the running test case, if any, followed by a line with the source location (a Bail out! line with the TAP reporter), in place of the totals. Before initialise() or after run_suites(), when there is no report to complete, the source location is written to stderr.

The handler set by set_abort_handler() is then called, if any. If there is no handler, or if it returns, the process is terminated with ::abort().

The abort is final, also when the handler throws an exception: no test case runs afterwards, initialise() and run_suites() report an error on stderr (run_suites() returns 1), and a later abort is not reported again.

Parameters

sl	The source location from which the abort is triggered.

Returns

Does not return.

Delegates to abort(), as an explicit abort, not caused by a failed requirement.

Definition at line 1004 of file runner.cpp.

  {
    abort (sl, false);
  }

References abort().

Referenced by micro_os_plus::micro_test_plus::detail::runnable_base::abort(), abort(), and abort().

add_suite()

template<typename Callable_T, typename... Args_T>
requires detail::suite_body<Callable_T, Args_T...>

void micro_os_plus::micro_test_plus::runner::add_suite	(	located_name	name,
		Callable_T &&	callable,
		Args_T &&...	arguments )

Unlike the test cases added to the top suite (see add_top_suite()), which run immediately, the suite is only stored; run_suites() runs it later, together with the static suites that refer to this runner, sorted by name.

The suites must be added before run_suites() is called. A suite added while run_suites() runs (for example from the body of another suite), or after it returned, would never run; it is rejected, the error is reported on stderr and in the report, and the exit code is not 0, so that the omission cannot pass unnoticed.

Template Parameters

Callable_T	The type of a callable object.
Args_T	The types of the callable arguments.

Parameters

name	The test suite name or description, used in reports; a string literal, a const char*, a std::string, or a std::string_view, converted implicitly to located_name, which copies it, so the string need not outlive the call, and also captures the location of the call; the suite keeps it. A null pointer is an empty name.
callable	A generic callable object, usually a lambda, invoked to perform the test suite.
arguments	A possibly empty list of arguments to be passed to the callable.

Returns

Nothing.

Since

6.0.0

Constructs a suite object on the heap, moving the name into it and binding the callable and any additional arguments, then transfers ownership to the runner via register_suite(). The suite is not run here; all registered suites are run later by run_suites(), together with the static suites, sorted by name. A suite added once run_suites() has started is rejected by register_suite().

Definition at line 191 of file runner-inlines.h.

  {
#if defined(MICRO_OS_PLUS_MICRO_TEST_PLUS_TRACE_ENABLED)
    trace::printf ("%s '%s'\n", __PRETTY_FUNCTION__, name.name ());
#endif // MICRO_OS_PLUS_MICRO_TEST_PLUS_TRACE_ENABLED
 
    // Not std::make_unique(), which cannot access the private constructor.
    std::unique_ptr<class suite> child_suite{ new class suite (
        std::move (name), *this, std::forward<Callable_T> (callable),
        std::forward<Args_T> (arguments)...) };
 
    register_suite (std::move (child_suite));
  }

References add_suite(), micro_os_plus::micro_test_plus::located_name::name(), name(), register_suite(), micro_os_plus::micro_test_plus::detail::reject_suite_body(), and suite().

Referenced by add_suite(), operator=(), and suite().

add_top_suite() [1/2]

suite & micro_os_plus::micro_test_plus::runner::add_top_suite

(

const located_name &

top_suite_name

)

The top suite is the suite whose body is the code of main(): its test cases run immediately, when test() is called, before the suites added with add_suite() and the static suites, which run later, by run_suites(). It is always the first suite in the report.

The call is optional; without it, there is no top suite, and only the other suites are run and reported. If the runner is not yet initialised, it is initialised with the default options.

If no name is given, here or by the deprecated constructor, the top suite is named after the file name of runner_options::arguments()[0], without the extension, when available, or "default suite".

The top suite can be added only once, and before run_suites(); a second call, or a call made once run_suites() has started, is reported on stderr and in the report, and rejected, so that run_suites() returns 1, and the existing top suite is returned. With errors in the options, the top suite is returned, but no test is run.

Parameters

top_suite_name

The name of the top suite, used in reports; a string literal, a const char*, a std::string, or a std::string_view, converted implicitly to located_name, which copies it, so the string need not outlive the call. An empty name, or a null pointer, is the same as no name.

Returns

Reference to the top suite.

Since

6.0.0

Initialises the runner with the default options, if not yet done, names the top suite, marks it as part of the session, starts its timing, and emits the reporter notification for its beginning; while the test cases are listed, the top suite is not reported.

A non-empty name is copied, with its location, into the top suite. If the name is empty, the name given to the deprecated constructor is kept; if there is none, the name is derived from the file name of arguments()[0] (usually argv[0]), without the extension, or defaults to "default suite", with the location of this call.

After the test execution was aborted, the error is reported on stderr. With errors in the options or in the output file, the session has already finished, and the top suite is returned without other effects. A second call, or a call once run_suites() has started, is reported with reject_call(), on stderr and in the report, and rejected, so that the exit code is not 0.

Definition at line 420 of file runner.cpp.

  {
    const std::string_view requested_name{ top_suite_name.name () };
 
#if defined(MICRO_OS_PLUS_MICRO_TEST_PLUS_TRACE_ENABLED)
    trace::printf ("%s\n", __PRETTY_FUNCTION__);
#endif // MICRO_OS_PLUS_MICRO_TEST_PLUS_TRACE_ENABLED
 
    if (aborted_)
      {
        fprintf (stderr, "error: test execution aborted\n");
        return top_suite_;
      }
 
    if (session_state_ == session_state::created)
      {
        initialise (runner_options{});
      }
 
    if (has_option_errors () || options_.help)
      {
        return top_suite_;
      }
 
    if (has_top_suite_)
      {
        reject_call ("top suite already added", &top_suite_name.location ());
        return top_suite_;
      }
 
    if (!requested_name.empty ())
      {
        // If provided by this call, use it, possibly override the
        // deprecated constructor.
        top_suite_.located_name_ = top_suite_name;
        top_suite_.name_ = top_suite_.located_name_.name ();
      }
    else if (strlen (top_suite_.name ()) == 0)
      {
        // If not provided by the constructor or by this call, try to extract a
        // name from argv[0], which is commonly the executable name. If that
        // fails, use a default name.
        if (!options_.arguments ().empty ())
          {
            std::string_view top_suite_name_view{ utility::extract_file_name (
                options_.arguments ()[0].c_str ()) };
 
            const auto dot_pos = top_suite_name_view.rfind ('.');
            if (dot_pos != std::string_view::npos)
              {
                top_suite_name_view = top_suite_name_view.substr (0, dot_pos);
              }
 
            top_suite_.located_name_
                = located_name{ top_suite_name_view,
                                top_suite_name.location () };
          }
        else
          {
            top_suite_.located_name_
                = located_name{ "default suite", top_suite_name.location () };
          }
        top_suite_.name_ = top_suite_.located_name_.name ();
      }
 
    // Named first, so that the rejection names it.
    if (session_state_ != session_state::initialised)
      {
        reject_suite (top_suite_.name (), top_suite_name.location ());
        return top_suite_;
      }
 
    has_top_suite_ = true;
 
    // The top suite runs until run_suites() is called; its test cases
    // are accepted only meanwhile.
    running_suite_ = &top_suite_;
 
    // When listing, the top suite is not reported; its test cases are
    // listed as they are created.
    if (!options_.list_tests)
      {
        top_suite_.stopwatch_.start ();
        reporter_->begin_suite (top_suite_);
      }
 
    return top_suite_;
  }

References aborted_, micro_os_plus::micro_test_plus::runner_options::arguments(), created, micro_os_plus::micro_test_plus::utility::extract_file_name(), has_option_errors(), has_top_suite_, micro_os_plus::micro_test_plus::runner_options::help, initialise(), initialised, micro_os_plus::micro_test_plus::runner_options::list_tests, micro_os_plus::micro_test_plus::suite::located_name_, micro_os_plus::micro_test_plus::located_name::location(), micro_os_plus::micro_test_plus::detail::runnable_base::name(), micro_os_plus::micro_test_plus::located_name::name(), micro_os_plus::micro_test_plus::detail::runnable_base::name_, options_, reject_call(), reject_suite(), reporter_, running_suite_, session_state_, micro_os_plus::micro_test_plus::detail::stopwatch::start(), micro_os_plus::micro_test_plus::suite::stopwatch_, and top_suite_.

Referenced by add_top_suite(), initialise(), and operator=().

add_top_suite() [2/2]

suite & micro_os_plus::micro_test_plus::runner::add_top_suite

(

void

)

The same as add_top_suite (const located_name&) with an empty name: the top suite keeps the name given to the deprecated constructor, or is named after the program.

Parameters

None.

Returns

Reference to the top suite.

Since

6.0.0

Forwards an empty name to the overload for const located_name&.

Definition at line 514 of file runner.cpp.

  {
    return add_top_suite (located_name{ "" });
  }

References add_top_suite().

added_suites_count()

size_t micro_os_plus::micro_test_plus::runner::added_suites_count ( void ) const

nodiscardnoexcept

The count includes neither the top suite nor the static suites, which are counted by static_suites_count(); add one for the top suite, if added, or use total_suites_count(), which counts all of them. The suites that add_suite() rejects, once run_suites() has started, are not counted.

Parameters

None.

Returns

The number of test suites added with add_suite().

Since

6.0.0

Returns the number of suites stored by register_suite(); the top suite and the static suites are not in children_suites_.

Definition at line 1073 of file runner.cpp.

  {
    return children_suites_.size ();
  }

References children_suites_.

Referenced by suites_count(), and total_suites_count().

application_arguments()

std::span< const std::string > micro_os_plus::micro_test_plus::runner::application_arguments ( void ) const

inlinenodiscardnoexcept

The arguments that follow the µTest++ options: the first argument that does not start with a dash and all the following ones, or, if the µTest++ options were ended by a -- alone, the arguments after it, which may start with --; see runner_options::application_arguments(). The -- itself and argv[0] are not included. The arguments are not interpreted by the runner.

The span refers to the options kept by the runner, so it is valid as long as the runner exists. It is empty before initialise(), or if the options were not parsed from a command line.

Parameters

None.

Returns

A span of the application arguments.

Since

6.0.0

Returns the application arguments of the options kept by the runner.

Definition at line 135 of file runner-inlines.h.

  {
    return options_.application_arguments ();
  }

References options_.

exit_code()

int micro_os_plus::micro_test_plus::runner::exit_code

(

void

)

Calls run_suites(); once the session has ended, it only returns the exit code.

Parameters

None.

Returns

The value returned by run_suites().

Deprecated

use run_suites() (since 6.0.0)

Kept for compatibility; it calls run_suites(), so the first call runs the session and the later ones return the stored exit code.

Definition at line 979 of file runner.cpp.

  {
    return run_suites ();
  }

References run_suites().

Referenced by operator=().

has_option_errors()

bool micro_os_plus::micro_test_plus::runner::has_option_errors ( void ) const

inlinenodiscardprivatenoexcept

Called by run_suites(), which then returns 2. The errors are those found while parsing the options (see runner_options::has_errors()), and the output file that cannot be opened. The filters that select no test case are checked by run_suites() itself.

Before initialise() created the reporter, there is no output file, and the result is false.

Parameters

None.

Returns

true if an option error was found.

Combines the results kept by the options and by the reporter, so that the runner needs no flag of its own. The reporter is created by initialise(); until then there is no output file, hence no error of it.

Definition at line 100 of file runner-inlines.h.

  {
    return options_.has_errors ()
           || (reporter_ != nullptr && reporter_->has_output_file_error ());
  }

References options_, and reporter_.

Referenced by micro_os_plus::micro_test_plus::detail::runnable_base::accepts_test_case(), add_top_suite(), micro_os_plus::micro_test_plus::detail::runnable_base::after_test_case_create(), and run_suites().

initialise() [1/3]

void micro_os_plus::micro_test_plus::runner::initialise	(	int	argc,
		char *	argv[] )

Parses the command-line options and initialises the runner with them; equivalent to initialise (runner_options{ argc, argv }).

The call is optional; without it, the runner is initialised with the default options by the first call of add_top_suite() or run_suites(). If used, it must therefore precede them; a later call reports an error on stderr and in the report, and is rejected, so that run_suites() returns 1; a call after the test execution was aborted reports an error on stderr, without other effects. In both cases the options are not parsed, so their errors do not change the exit code.

Parameters

argc	The argument count from main().
argv	The argument vector from main().

Returns

Nothing.

Since

6.0.0

Parses the command-line options with the runner_options constructor, and initialises the runner with them.

The options are not parsed if the runner is already initialised, or the test execution was aborted, since an option error would change the exit code of the session; the error is reported by the overload taking the options.

If tracing is enabled, the command-line arguments are also logged for diagnostic purposes.

Definition at line 216 of file runner.cpp.

  {
#if defined(MICRO_OS_PLUS_MICRO_TEST_PLUS_TRACE_ENABLED)
    trace::printf ("%s\n", __PRETTY_FUNCTION__);
 
#if !(defined(MICRO_OS_PLUS_STARTUP_ENABLED) \
      && defined(MICRO_OS_PLUS_DIAG_TRACE_ENABLED))
#if defined(MICRO_OS_PLUS_DEBUG_ENABLED)
    trace::printf ("argv[");
    for (int i = 0; i < argc; ++i)
      {
        if (i > 0)
          {
            trace::printf (", ");
          }
        trace::printf ("'%s'", argv[i]);
      }
    trace::puts ("]");
#endif // defined(MICRO_OS_PLUS_DEBUG_ENABLED)
#endif // !defined(MICRO_OS_PLUS_STARTUP_ENABLED)
#endif // MICRO_OS_PLUS_MICRO_TEST_PLUS_TRACE_ENABLED
 
    if (aborted_ || session_state_ != session_state::created)
      {
        initialise (runner_options{});
        return;
      }
 
    initialise (runner_options{ argc, argv });
  }

References aborted_, created, initialise(), and session_state_.

initialise() [2/3]

suite & micro_os_plus::micro_test_plus::runner::initialise	(	int	argc,
		char *	argv[],
		const char *	top_suite_name )

Equivalent to initialise (argc, argv) followed by add_top_suite (top_suite_name). Use the two calls; the top suite is now optional, and initialise() no longer returns it.

The name no longer has a default value, so that the call with two arguments selects the current initialise (argc, argv), which returns nothing and does not add the top suite.

If the runner is already initialised, or the test execution was aborted, the error is reported on stderr, as by initialise(), and the top suite is returned without other effects.

Parameters

argc	The argument count from main().
argv	The argument vector from main().
top_suite_name	The name given to the top suite; if empty, the name is chosen as by add_top_suite().

Returns

Reference to the top suite.

Deprecated

use initialise (argc, argv) and add_top_suite() (since 6.0.0)

Initialises the runner with the command-line options, as initialise (argc, argv) does, and adds the top suite.

If the runner is already initialised, or the test execution was aborted, the top suite is returned without other effects, as in the earlier versions; the call is not rejected.

Definition at line 189 of file runner.cpp.

  {
    if (aborted_ || session_state_ != session_state::created)
      {
        return top_suite_;
      }
 
    initialise (argc, argv);
 
    return add_top_suite (top_suite_name != nullptr ? top_suite_name : "");
  }

References aborted_, add_top_suite(), created, initialise(), session_state_, and top_suite_.

Referenced by add_top_suite(), initialise(), initialise(), operator=(), and run_suites().

initialise() [3/3]

void micro_os_plus::micro_test_plus::runner::initialise

(

runner_options

options

)

Creates the reporter selected by the options and starts the session. The options may be parsed from the command line, adjusted, and passed here:

mt::runner_options options{ argc, argv };
options.selected_reporter = mt::reporter_kind::human;
tr.initialise (std::move (options));

The call is optional; without it, the runner is initialised with the default options by the first call of add_top_suite() or run_suites(). If used, it must therefore precede them; a later call reports an error on stderr and in the report, and is rejected, so that run_suites() returns 1; a call after the test execution was aborted reports an error on stderr, without other effects.

If the options have errors (see runner_options::has_errors()), or if the output file cannot be opened, the errors are written on the console and on stderr, no test is run, and run_suites() returns 2; the errors in the options are also written in the output file, if one is given and can be opened, which is truncated, so that it never keeps the results of an earlier run.

The options are taken by value and moved into the runner, which keeps them for the whole session; pass a temporary, or use std::move(), to avoid a copy.

Parameters

options

The session options.

Returns

Nothing.

Since

6.0.0

Moves the options into the runner, which keeps them for the whole session, creates the reporter selected by them, starts the session timing, and emits the initial reporter notification for the session. While the test cases are listed, only the header of the list is written; the session is not reported.

If the options have errors, nothing else is done: the errors are written on stderr, on the console, and in the output file, if any, which is truncated, so that it never keeps the results of an earlier run; the session is marked as declined, so that no test is run, and run_suites() returns 2. With --help, and no errors, the usage is written only on the console, no output file is created, the session is declined, and run_suites() returns 0. If the output file cannot be opened, the error is written on stderr (by the reporter) and on the console, the session is declined, and run_suites() returns 2.

The runner is initialised only once; a later call reports an error with reject_call(), on stderr and in the report, and is rejected, so that run_suites() returns 1 (or 2, if the options have errors); a call after the test execution was aborted reports an error on stderr, without other effects.

Definition at line 273 of file runner.cpp.

  {
#if defined(MICRO_OS_PLUS_MICRO_TEST_PLUS_TRACE_ENABLED)
    trace::printf ("%s\n", __PRETTY_FUNCTION__);
#endif // MICRO_OS_PLUS_MICRO_TEST_PLUS_TRACE_ENABLED
 
    if (aborted_)
      {
        fprintf (stderr, "error: test execution aborted\n");
        return;
      }
 
    if (session_state_ != session_state::created)
      {
        reject_call ("test runner already initialised");
        return;
      }
 
    // Move the vectors, since their copy assignment uses std::copy, which
    // triggers -Waggregate-return in the standard library headers on some
    // targets.
    options_ = std::move (options);
 
    // With errors in the options, do not proceed: the errors are written on
    // the console and in the output file, if any, which is truncated, so
    // that it never keeps the results of an earlier run; no test is run, and
    // `run_suites()` returns 2. The same for `--help`, which writes the
    // usage instead of the errors, only on the console, and `run_suites()`
    // returns 0. A reporter is still created, since the suites and the test
    // cases refer to it.
    if (options_.has_errors () || options_.help)
      {
        runner_options console_options{ options_ };
        if (!options_.has_errors ())
          {
            console_options.output_file_path.clear ();
          }
        if (console_options.selected_reporter == reporter_kind::human)
          {
            reporter_
                = std::make_unique<detail::reporter_human> (console_options);
          }
        else
          {
            reporter_
                = std::make_unique<detail::reporter_tap> (console_options);
          }
 
        for (const std::string& error : options_.errors ())
          {
            fprintf (stderr, "error: %s\n", error.c_str ());
            reporter_->write_line (
                options_.verbosity_level != verbosity::silent, "%s%s\n",
                reporter_->error_prefix (), error.c_str ());
          }
        if (options_.has_unknown_option ())
          {
            reporter_->write_line (options_.verbosity_level
                                       != verbosity::silent,
                                   "%sUse --help to list the options.\n",
                                   reporter_->comment_prefix ());
          }
        if (options_.help && !options_.has_errors ())
          {
            // Requested, so written also with the silent verbosity.
            const char* program = options_.arguments ().empty ()
                                      ? "<program>"
                                      : utility::extract_file_name (
                                            options_.arguments ()[0].c_str ());
            reporter_->write_line (true,
                                   "Usage: %s [options] [--] "
                                   "[arguments]\n%s",
                                   program, help_options);
          }
        reporter_->flush_streams ();
 
        exit_code_ = options_.has_errors () ? 2 : 0;
        session_state_ = session_state::declined;
        return;
      }
 
    // Initialise and configure the reporter; it keeps its own copy of the
    // verbosity, taken from the same options.
    if (options_.selected_reporter == reporter_kind::human)
      {
        reporter_ = std::make_unique<detail::reporter_human> (options_);
      }
    else
      {
        reporter_ = std::make_unique<detail::reporter_tap> (options_);
      }
 
    // If the output file cannot be opened, do not run the tests either.
    if (reporter_->has_output_file_error ())
      {
        reporter_->write_line (options_.verbosity_level != verbosity::silent,
                               "%sfailed to open output file '%s'\n",
                               reporter_->error_prefix (),
                               options_.output_file_path.c_str ());
        reporter_->flush_streams ();
 
        exit_code_ = 2;
        session_state_ = session_state::declined;
        return;
      }
 
    // ------------------------------------------------------------------------
 
    // When listing, the session is not reported; only the header of the
    // list is written, and the test cases are listed as they are created.
    if (options_.list_tests)
      {
        reporter_->write_line (true, "%s\n",
                               options_.filter_patterns.empty ()
                                   ? "All available test cases:"
                                   : "Matching test cases:");
        session_state_ = session_state::initialised;
        return;
      }
 
    stopwatch_.start ();
    reporter_->begin_session (*this);
 
    session_state_ = session_state::initialised;
  }

References aborted_, micro_os_plus::micro_test_plus::runner_options::arguments(), created, declined, micro_os_plus::micro_test_plus::runner_options::errors(), exit_code_, micro_os_plus::micro_test_plus::utility::extract_file_name(), micro_os_plus::micro_test_plus::runner_options::filter_patterns, micro_os_plus::micro_test_plus::runner_options::has_errors(), micro_os_plus::micro_test_plus::runner_options::has_unknown_option(), micro_os_plus::micro_test_plus::runner_options::help, micro_os_plus::micro_test_plus::human, initialised, micro_os_plus::micro_test_plus::runner_options::list_tests, options_, micro_os_plus::micro_test_plus::runner_options::output_file_path, reject_call(), reporter_, micro_os_plus::micro_test_plus::runner_options::selected_reporter, session_state_, micro_os_plus::micro_test_plus::silent, micro_os_plus::micro_test_plus::detail::stopwatch::start(), stopwatch_, and micro_os_plus::micro_test_plus::runner_options::verbosity_level.

is_listing()

bool micro_os_plus::micro_test_plus::runner::is_listing ( void ) const

inlinenodiscardnoexcept

Set by the --list-tests (or --list) command-line option, or by runner_options::list_tests. While the test cases are listed, their bodies do not run, so the code in main() or in the suite bodies that depends on their results (their totals, or the exit code of run_suites()) can use it to skip those parts, and the tests can use it to keep their own messages out of the list. Before initialise() is called, it is false.

Parameters

None.

Return values

true	The test cases are listed.
false	The test cases are run.

Since

6.0.0

Returns runner_options::list_tests of the session options.

Definition at line 87 of file runner-inlines.h.

  {
    return options_.list_tests;
  }

References options_.

is_selected()

bool micro_os_plus::micro_test_plus::runner::is_selected ( const char * name, size_t level ) const

nodiscardprivate

Level 0 refers to the suites, level 1 to their test cases, and each further level to the test cases nested one level deeper. A name is selected when there is no pattern for its level, or when it matches one of the alternatives of the pattern, separated by |, as defined by utility::is_match().

Also called by detail::runnable_base, a friend, before running a test case.

Parameters

name	The name of the suite or of the test case.
level	The nesting level; 0 for suites.

Returns

true if it must run, false if it must be skipped.

The levels beyond the last pattern are not filtered. Otherwise, the alternatives of the pattern, separated by |, are tried in order, until one matches the whole name.

Definition at line 530 of file runner.cpp.

  {
    if (level >= options_.filter_patterns.size ())
      {
        return true;
      }
 
    std::string_view alternatives{ options_.filter_patterns[level] };
    while (true)
      {
        const size_t separator = alternatives.find ('|');
        if (utility::is_match (name, alternatives.substr (0, separator)))
          {
            return true;
          }
        if (separator == std::string_view::npos)
          {
            return false;
          }
        alternatives.remove_prefix (separator + 1);
      }
  }

References micro_os_plus::micro_test_plus::runner_options::filter_patterns, micro_os_plus::micro_test_plus::utility::is_match(), name(), and options_.

Referenced by micro_os_plus::micro_test_plus::detail::runnable_base::after_test_case_create(), and run_child_suites().

link_static_suite()

void micro_os_plus::micro_test_plus::runner::link_static_suite ( runner & test_runner, class suite & suite )

staticprivatenoexcept

Called by the static_suite constructors. A static suite may be constructed before its runner, which must not be accessed then; therefore the runners that have started are kept in a constant-initialised list, which is searched by address. If the runner is in the list, run_suites() has started and the suite would never run, so it is rejected, as by add_suite(); otherwise, it is linked.

Parameters

[in]	test_runner	The runner of the suite.
[in]	suite	The suite being constructed.

Returns

Nothing.

Searches the list of the started runners for test_runner, without accessing it, since it may not be constructed yet. If found, the runner reports the rejection; otherwise, the suite is linked. No memory is allocated.

Definition at line 728 of file runner.cpp.

  {
    for (const runner* started = started_first_; started != nullptr;
         started = started->started_next_)
      {
        if (started == &test_runner)
          {
            test_runner.reject_suite (suite.name (),
                                      suite.located_name_.location ());
            return;
          }
      }
 
    suite.link ();
  }

References runner(), started_first_, and suite().

Referenced by micro_os_plus::micro_test_plus::static_suite::link_or_reject().

list_test_case()

void micro_os_plus::micro_test_plus::runner::list_test_case ( const class suite & suite, const class test_case & test_case )

private

Called by detail::runnable_base, a friend, for each selected test case created while the test cases are listed (see runner_options::list_tests). The name of the suite is written before its first listed test case, indented by two spaces, and the name of the test case after it, indented by four spaces, through the reporter, to the console, whatever the verbosity, and to the output file, if any.

Parameters

suite	The suite of the test case.
test_case	The test case to list.

Returns

Nothing.

The suites are listed in the order in which their first test cases are created: the top suite first, during main(), then the other suites, in the order of run_child_suites(); so the name of a suite is written when it differs from the previous one.

Definition at line 563 of file runner.cpp.

  {
    if (&suite != listed_suite_)
      {
        listed_suite_ = &suite;
        ++listed_suites_count_;
        reporter_->write_line (true, "  %s\n", suite.name ());
      }
 
    ++listed_test_cases_count_;
    reporter_->write_line (true, "    %s\n", test_case.name ());
  }

References listed_suite_, listed_suites_count_, listed_test_cases_count_, micro_os_plus::micro_test_plus::detail::runnable_base::name(), reporter_, and suite().

Referenced by micro_os_plus::micro_test_plus::detail::runnable_base::after_test_case_create().

mark_rejected()

void micro_os_plus::micro_test_plus::runner::mark_rejected ( void )

privatenoexcept

Sets has_rejected_calls_, so that run_suites() returns 1 (unless an option error requires 2), and, if the session has already ended, updates the stored exit code, for the later calls of run_suites(). Used by reject_call().

Parameters

None.

Returns

Nothing.

The flag is read by run_suites() when it computes the exit code. If the session has already finished, the stored exit code is changed too, unless it is already not 0.

Definition at line 711 of file runner.cpp.

  {
    has_rejected_calls_ = true;
    if (session_state_ == session_state::finished && exit_code_ == 0)
      {
        exit_code_ = 1;
      }
  }

References exit_code_, finished, has_rejected_calls_, and session_state_.

Referenced by reject_call().

name()

const char * micro_os_plus::micro_test_plus::runner::name ( void ) const

nodiscardnoexcept

In v5.0.1, the runner was a test node, and always returned "runner". The runner is no longer a node; the name shown at the beginning of the reports is that of the top suite, returned by add_top_suite().

Parameters

None.

Returns

The constant string "runner".

Deprecated

the runner has no name; see add_top_suite() (since 6.0.0)

Returns the constant string "runner", as before the runner stopped being a test node.

Definition at line 1086 of file runner.cpp.

  {
    return "runner";
  }

Referenced by add_suite(), is_selected(), operator=(), reject_suite(), and suite().

operator=() [1/2]

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

delete

The runner owns the suites, the reporter, and the session totals, which must not be duplicated.

References runner().

operator=() [2/2]

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

delete

The suites keep a reference to the runner, so it must not be relocated.

References runner(), add_suite(), add_top_suite(), exit_code(), initialise(), name(), run_suites(), and suite().

register_suite()

void micro_os_plus::micro_test_plus::runner::register_suite ( std::unique_ptr< class suite > suite )

private

Called by add_suite(). Once run_suites() has started, the suite is rejected: it is destroyed, the error is reported on stderr and by the reporter, and has_rejected_calls_ is set.

Parameters

suite

Owning pointer to the test suite to register.

Returns

Nothing.

Takes ownership of the supplied suite unique pointer and appends it to the internal children_suites_ vector, then inserts the suite into the list of suites, sorted by name, deferring execution until run_child_suites() is called. The suite is inserted after it is stored, so that a failed allocation of the vector leaves it out of the list. If tracing is enabled, the suite name is logged for diagnostic purposes.

Once run_suites() has started, the suite is rejected, since it would never run: run_child_suites() takes the number of suites only once, before running them, and after the session has ended nothing runs. The error is reported with reject_suite(), on stderr and in the report, the suite is destroyed when the pointer goes out of scope, and has_rejected_calls_ is set, so that the exit code is not 0; if the session has already ended, the stored exit code is updated, for the later calls of run_suites().

Definition at line 599 of file runner.cpp.

  {
#if defined(MICRO_OS_PLUS_MICRO_TEST_PLUS_TRACE_ENABLED)
    trace::printf ("%s '%s'\n", __PRETTY_FUNCTION__, suite->name ());
#endif // MICRO_OS_PLUS_MICRO_TEST_PLUS_TRACE_ENABLED
 
    if (session_state_ == session_state::declined)
      {
        // Nothing runs in a declined session; the suite is discarded.
        return;
      }
 
    if (session_state_ == session_state::running
        || session_state_ == session_state::finished)
      {
        reject_suite (suite->name (), suite->located_name_.location ());
        return;
      }
 
    children_suites_.push_back (std::move (suite));
    children_suites_.back ()->link ();
  }

References children_suites_, declined, finished, reject_suite(), running, session_state_, and suite().

Referenced by add_suite().

reject_call()

void micro_os_plus::micro_test_plus::runner::reject_call ( const std::string & message, const reflection::source_location * location = nullptr )

private

Writes the message on stderr, calls mark_rejected(), and gives the message to the reporter, as a failed check of the running test case, as a failed test point of the running suite, or as a comment line, so that the report and the output file tell why the session failed. Used by reject_suite(), by initialise() and add_top_suite() for the calls made twice, and by detail::runnable_base, for a test case started on a suite that is not running, where no running test case or suite can report it, and for an exception that escapes a suite body while the test cases are listed.

Parameters

[in]	message	The message, without the prefix.
[in]	location	The location of the call, or a null pointer if it is not known.

Returns

Nothing.

The message is always written on stderr, for a shell or a script that discards the standard output, and the rejection is recorded with mark_rejected(), so that the exit code is not 0.

The message is also given to the reporter, so that the report and the output file tell why the session failed, where the reporter can still write it:

• in a running test case, as a failed check of that test case, at location, or at the location of the test case;
• in a running suite, including the top suite, as a failed test point of that suite;
• otherwise, for example after run_suites() returned, or while the test cases are listed, as a comment line, since the report is complete, or there are no test points.

Nothing is given to the reporter if there is none yet, after the session was declined because of the options, and after the execution was aborted.

Definition at line 660 of file runner.cpp.

  {
    fprintf (stderr, "error: %s\n", message.c_str ());
    mark_rejected ();
 
    if (reporter_ == nullptr || session_state_ == session_state::declined
        || aborted_)
      {
        return;
      }
 
    if (options_.list_tests)
      {
        reporter_->write_line (options_.verbosity_level != verbosity::silent,
                               "%serror: %s\n", reporter_->comment_prefix (),
                               message.c_str ());
        reporter_->flush_streams ();
        return;
      }
 
    if (running_test_case_ != nullptr)
      {
        running_test_case_->report_rejected_test (
            message, location != nullptr
                         ? *location
                         : running_test_case_->located_name_.location ());
        return;
      }
 
    if (running_suite_ != nullptr)
      {
        running_suite_->next_test_point_number ();
        reporter_->fail_suite (message, *running_suite_);
        running_suite_->totals_.increment_failed_checks ();
        return;
      }
 
    reporter_->write_line (options_.verbosity_level != verbosity::silent,
                           "%serror: %s\n", reporter_->comment_prefix (),
                           message.c_str ());
    reporter_->flush_streams ();
  }

References aborted_, declined, micro_os_plus::micro_test_plus::counters::increment_failed_checks(), micro_os_plus::micro_test_plus::runner_options::list_tests, micro_os_plus::micro_test_plus::test_case::located_name_, micro_os_plus::micro_test_plus::located_name::location(), mark_rejected(), micro_os_plus::micro_test_plus::detail::runnable_base::next_test_point_number(), options_, micro_os_plus::micro_test_plus::test_case::report_rejected_test(), reporter_, running_suite_, running_test_case_, session_state_, micro_os_plus::micro_test_plus::silent, micro_os_plus::micro_test_plus::detail::runnable_base::totals_, and micro_os_plus::micro_test_plus::runner_options::verbosity_level.

Referenced by micro_os_plus::micro_test_plus::detail::runnable_base::accepts_test_case(), add_top_suite(), initialise(), micro_os_plus::micro_test_plus::detail::runnable_base::reject_body_exception(), and reject_suite().

reject_suite()

void micro_os_plus::micro_test_plus::runner::reject_suite ( const char * name, const reflection::source_location & location )

private

Reports the error with reject_call(). Used by register_suite(), by add_top_suite(), and by link_static_suite().

Parameters

[in]	name	The name of the rejected suite.
[in]	location	The location where the suite was named.

Returns

Nothing.

Builds the message and passes it to reject_call(). The suite itself is destroyed by the caller.

Definition at line 628 of file runner.cpp.

  {
    std::string message{ "suite '" };
    message.append (name);
    message.append ("' added after run_suites() started, rejected");
 
    reject_call (message, &location);
  }

References name(), and reject_call().

Referenced by add_top_suite(), and register_suite().

reporter()

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

inlinenodiscardnoexcept

Returns the internal reporter, created by initialise(), as selected by the session options; the call is valid only after initialise(). In v5.0.1, the returned class was the top namespace reporter, now detail::reporter; of its members, the applications used only verbosity(), kept, deprecated, on detail::reporter.

Parameters

None.

Returns

A reference to the reporter of the session.

Deprecated

use verbosity_level() (since 6.0.0)

Returns a reference to the reporter owned by the reporter_ unique pointer, which is empty before initialise().

Definition at line 170 of file runner-inlines.h.

  {
    return *reporter_;
  }

References reporter_.

run_child_suites()

void micro_os_plus::micro_test_plus::runner::run_child_suites ( void )

private

Runs the suites registered with add_suite() and the static suites that refer to this runner in a single order, sorted by name; for equal names, in the order of their insertion into the list, so the static suites constructed before main() run first. The suites not selected by the first filter pattern are reported as skipped.

Parameters

None.

Returns

Nothing.

Runs the suites registered with add_suite() and the static suites that refer to this runner in a single order, sorted by name.

Both kinds of suites are in the list of suites, which suite::link() keeps sorted by name, so no sorting is needed here; the suites of other runners are skipped. The names are compared with std::strcmp(), so in byte order, case-sensitively, and without comparing the numbers by value; the suites with the same name run in the order of their insertion into the list.

Each suite is assigned a 1-based index, following the top suite, if added, in the order of execution. If the first filter pattern selects it, it is executed via suite::run(), and its totals are accumulated into the runner totals; otherwise, it is reported as skipped and counted in skipped_suites_count_, keeping its index, so that the TAP plan remains complete; while the test cases are listed, the skipped suites are not reported. The executed test cases counter is not incremented; suites are not counted as test cases.

The next suite is read after the current one has run, since the suites of the local runners created by the current suite are inserted into the list, and removed again, while it runs.

Definition at line 778 of file runner.cpp.

  {
    // The top suite, if added, has index 1.
    size_t own_index = has_top_suite_ ? 1 : 0;
    for (micro_test_plus::suite* suite_ptr = suite::first_;
         suite_ptr != nullptr; suite_ptr = suite_ptr->next_)
      {
        // Skip the suites run by other runners.
        if (&suite_ptr->test_runner () != this)
          {
            continue;
          }
 
        suite_ptr->own_index_ = ++own_index;
 
        if (!is_selected (suite_ptr->name (), 0))
          {
            ++skipped_suites_count_;
            if (!options_.list_tests)
              {
                reporter_->skip_suite (*suite_ptr);
              }
            continue;
          }
 
        suite_ptr->run ();
 
        // Accumulate the totals from the child suite into the runner
        // totals.
        // DO NOT increment executed_test_cases here.
        totals_ += suite_ptr->totals ();
      }
  }

References micro_os_plus::micro_test_plus::suite::first_, has_top_suite_, is_selected(), micro_os_plus::micro_test_plus::runner_options::list_tests, micro_os_plus::micro_test_plus::suite::next_, options_, reporter_, skipped_suites_count_, and totals_.

Referenced by run_suites().

run_suites()

int micro_os_plus::micro_test_plus::runner::run_suites ( void )

nodiscard

Completes the top suite, if any, runs the suites registered with add_suite() and the static suites that refer to this runner, together, sorted by name, and ends the session. If the runner is not yet initialised, it is initialised with the default options. When filter patterns are given, the suites whose names do not match the first pattern are reported as skipped, without being run.

While the test cases are listed (see is_listing()), the suites run only to create their test cases, which are listed, and the number of listed test cases is written; the result of the checks does not affect the exit code, since no check is evaluated; a rejected call or an exception that escapes a suite body, which make the list incomplete, are written on stderr, and in the list, on the console and in the output file, and make the exit code 1.

A session without any suite (no top suite, no suite added with add_suite(), and no static suite) is reported as an error, since a test program that runs nothing must not pass unnoticed.

The session runs only once; later calls return the same exit code without running anything again. A call made while the session runs, for example from a suite body, or after the test execution was aborted (see abort()), is reported on stderr and returns 1, without other effects.

Parameters

None.

Returns

0 if all checks passed, if the test cases were listed without errors, or if the usage was displayed by --help; 1 if a check failed, if a suite was rejected by add_suite() or add_top_suite(), if initialise() or add_top_suite() was called twice, if a test case was started on a suite that is not running, if an exception escaped a suite body while the test cases were listed, if there was no suite, if the runner is running, or if the test execution was aborted; 2 if initialise() reported an option error, or if the filters selected no test case, regardless of the checks.

Since

6.0.0

Initialises the runner with the default options, if not yet done. Finalises the top suite, if added, by stopping its stopwatch and notifying the reporter, then accumulates its totals into the runner totals. Subsequently invokes run_child_suites() to execute, sorted by name, and accumulate the registered and the static child suites. Finally, stops the session stopwatch, notifies the reporter, and returns 0 if all checks passed or 1 otherwise, or if a call was rejected (see mark_rejected()), or if there was no suite at all; if initialise() reported an option error, or if the filters selected no test case, 2 is returned, regardless of the checks.

While the suites run, the session is in the running state, so that the suites added by them are rejected.

While the test cases are listed, the top suite is not reported, the suites run only to create their test cases, the numbers of listed test cases and suites end the list, and the exit code is 0, 1 if a call was rejected or an exception escaped a suite body, or 2 after an option error, or if the filters selected no test case.

The result is stored, and the later calls return it without running anything again. If the runner is already running (a call from a suite or a test case), or if the test execution was aborted, an error is reported on stderr and 1 is returned.

Definition at line 840 of file runner.cpp.

  {
#if defined(MICRO_OS_PLUS_MICRO_TEST_PLUS_TRACE_ENABLED)
    trace::printf ("%s\n", __PRETTY_FUNCTION__);
#endif // MICRO_OS_PLUS_MICRO_TEST_PLUS_TRACE_ENABLED
 
    if (aborted_)
      {
        fprintf (stderr, "error: test execution aborted\n");
        return 1;
      }
 
    if (session_state_ == session_state::finished
        || session_state_ == session_state::declined)
      {
        // The session has ended; do not run the suites again.
        return exit_code_;
      }
 
    if (session_state_ == session_state::running)
      {
        fprintf (stderr, "error: test runner already running\n");
        return 1;
      }
 
    if (session_state_ == session_state::created)
      {
        initialise (runner_options{});
      }
 
    session_state_ = session_state::running;
    running_suite_ = nullptr;
    started_next_ = started_first_;
    started_first_ = this;
 
    // When listing, the suites run only to create their test cases, which
    // are listed, and the number of listed test cases ends the list.
    if (options_.list_tests)
      {
        run_child_suites ();
 
        const size_t test_cases = listed_test_cases_count_;
        const size_t suites = listed_suites_count_;
        reporter_->write_line (
            true,
            "%" MICRO_OS_PLUS_MICRO_TEST_PLUS_PRI_SIZE
            " test case%s in %" MICRO_OS_PLUS_MICRO_TEST_PLUS_PRI_SIZE
            " test suite%s\n",
            test_cases, (test_cases == 1) ? "" : "s", suites,
            (suites == 1) ? "" : "s");
 
        // As for a run, filters that select no test case are an error.
        const bool listed_nothing = total_suites_count () != 0
                                    && !options_.filter_patterns.empty ()
                                    && listed_test_cases_count_ == 0;
        if (listed_nothing)
          {
            fprintf (stderr, "error: the filters selected no test case\n");
            reporter_->write_line (
                options_.verbosity_level != verbosity::silent,
                "%serror: the filters selected no test case\n",
                reporter_->comment_prefix ());
          }
        reporter_->flush_streams ();
 
        if (listed_nothing || has_option_errors ())
          {
            exit_code_ = 2;
          }
        else
          {
            exit_code_ = has_rejected_calls_ ? 1 : 0;
          }
        session_state_ = session_state::finished;
        return exit_code_;
      }
 
    if (has_top_suite_)
      {
        top_suite_.stopwatch_.stop ();
        reporter_->end_suite (top_suite_);
        totals_ += top_suite_.totals ();
      }
 
    run_child_suites ();
 
    // A session without suites runs nothing; report it.
    const bool has_no_suites = (total_suites_count () == 0);
    if (has_no_suites)
      {
        fprintf (stderr, "error: no test suites\n");
        reporter_->write_line (options_.verbosity_level != verbosity::silent,
                               "%serror: no test suites\n",
                               reporter_->comment_prefix ());
      }
 
    // A filter that selects no test case disables the tests; report it.
    const bool selected_nothing = !has_no_suites
                                  && !options_.filter_patterns.empty ()
                                  && totals_.executed_test_cases () == 0;
    if (selected_nothing)
      {
        fprintf (stderr, "error: the filters selected no test case\n");
        reporter_->write_line (options_.verbosity_level != verbosity::silent,
                               "%serror: the filters selected no test case\n",
                               reporter_->comment_prefix ());
      }
 
    stopwatch_.stop ();
    reporter_->end_session (*this);
 
    if (selected_nothing || has_option_errors ())
      {
        exit_code_ = 2;
      }
    else
      {
        exit_code_
            = (totals_.passed () && !has_rejected_calls_ && !has_no_suites)
                  ? 0
                  : 1;
      }
    session_state_ = session_state::finished;
 
#if defined(MICRO_OS_PLUS_MICRO_TEST_PLUS_TRACE_ENABLED)
    trace::printf ("%s -> %d\n", __PRETTY_FUNCTION__, exit_code_);
#endif // MICRO_OS_PLUS_MICRO_TEST_PLUS_TRACE_ENABLED
 
    return exit_code_;
  }

References aborted_, created, declined, micro_os_plus::micro_test_plus::counters::executed_test_cases(), exit_code_, micro_os_plus::micro_test_plus::runner_options::filter_patterns, finished, has_option_errors(), has_rejected_calls_, has_top_suite_, initialise(), micro_os_plus::micro_test_plus::runner_options::list_tests, listed_suites_count_, listed_test_cases_count_, MICRO_OS_PLUS_MICRO_TEST_PLUS_PRI_SIZE, options_, micro_os_plus::micro_test_plus::counters::passed(), reporter_, run_child_suites(), running, running_suite_, session_state_, micro_os_plus::micro_test_plus::silent, started_first_, started_next_, micro_os_plus::micro_test_plus::detail::stopwatch::stop(), stopwatch_, micro_os_plus::micro_test_plus::suite::stopwatch_, top_suite_, total_suites_count(), micro_os_plus::micro_test_plus::detail::runnable_base::totals(), totals_, and micro_os_plus::micro_test_plus::runner_options::verbosity_level.

Referenced by exit_code(), and operator=().

set_abort_handler()

runner::abort_handler_t micro_os_plus::micro_test_plus::runner::set_abort_handler ( abort_handler_t handler )

noexcept

Test execution is aborted by a failed require(), when exceptions are not enabled (otherwise only the test case is stopped), or by an explicit call of abort(). The abort is reported before the handler is called (see abort()).

The handler can be set at any time, before or after initialise().

Parameters

handler

The new handler, or nullptr to restore the default behaviour, which terminates the process with ::abort().

Returns

The previous handler, or nullptr if none was set.

Since

6.0.0

Stores the new handler and returns the previous one; a null handler restores the default behaviour.

Definition at line 991 of file runner.cpp.

  {
    abort_handler_t previous = abort_handler_;
    abort_handler_ = handler;
    return previous;
  }

References abort_handler_.

skipped_suites_count()

size_t micro_os_plus::micro_test_plus::runner::skipped_suites_count ( void ) const

nodiscardnoexcept

Counts the suites, registered or static, whose names do not match the first filter pattern (--filter or runner_options::filter_patterns); it is complete only after run_suites() has returned, and is zero when there are no patterns. The skipped suites are included in added_suites_count() and static_suites_count(); the skipped test cases are counted by counters::skipped_test_cases().

Parameters

None.

Returns

The number of test suites that were not run.

Since

6.0.0

Returns the counter incremented by run_child_suites().

Definition at line 1142 of file runner.cpp.

  {
    return skipped_suites_count_;
  }

References skipped_suites_count_.

Referenced by micro_os_plus::micro_test_plus::detail::reporter::format_session_totals().

static_suites_count()

size_t micro_os_plus::micro_test_plus::runner::static_suites_count ( void ) const

nodiscardnoexcept

Counts the static_suite objects that refer to this runner; it is complete only after the static initialisation.

Parameters

None.

Returns

The number of static test suites run by this runner.

Walks the list of suites, counts those that refer to this runner, and subtracts the suites registered with add_suite(), which are all in the list.

Definition at line 1111 of file runner.cpp.

  {
    size_t count = 0;
    for (const micro_test_plus::suite* suite_ptr = suite::first_;
         suite_ptr != nullptr; suite_ptr = suite_ptr->next_)
      {
        if (&suite_ptr->test_runner () == this)
          {
            ++count;
          }
      }
    return count - children_suites_.size ();
  }

References children_suites_, micro_os_plus::micro_test_plus::suite::first_, and micro_os_plus::micro_test_plus::suite::next_.

Referenced by total_suites_count().

suite()

template<typename Callable_T, typename... Args_T>

void micro_os_plus::micro_test_plus::runner::suite	(	std::string_view	name,
		Callable_T &&	callable,
		Args_T &&...	arguments )

Calls add_suite(). The old name did not show that the suite is only stored, to be run later by run_suites(), unlike the test cases, which run immediately; it also hid the suite class inside the runner.

Template Parameters

Callable_T	The type of a callable object.
Args_T	The types of the callable arguments.

Parameters

name	The test suite name or description, as for add_suite().
callable	A generic callable object, usually a lambda, invoked to perform the test suite.
arguments	A possibly empty list of arguments to be passed to the callable.

Returns

Nothing.

Deprecated

use add_suite() (since 6.0.0)

Forwards the name, the callable, and the arguments to add_suite().

Definition at line 231 of file runner-inlines.h.

  {
    add_suite (located_name{ name }, std::forward<Callable_T> (callable),
               std::forward<Args_T> (arguments)...);
  }

References add_suite(), and name().

Referenced by add_suite(), link_static_suite(), list_test_case(), operator=(), and register_suite().

suites_count()

size_t micro_os_plus::micro_test_plus::runner::suites_count ( void ) const

nodiscardnoexcept

Returns added_suites_count() plus one, for the top suite. The name suggested that all the suites are counted, while the static suites are not. Use added_suites_count(), plus one for the top suite, or total_suites_count().

Parameters

None.

Returns

The number of test suites added with add_suite(), plus one.

Deprecated

use added_suites_count() or total_suites_count() (since 6.0.0)

Returns added_suites_count() plus one, for the top suite, as before the rename.

Definition at line 1098 of file runner.cpp.

  {
    return added_suites_count () + 1;
  }

References added_suites_count().

timings() [1/2]

const detail::stopwatch & micro_os_plus::micro_test_plus::runner::timings ( void ) const

inlinenodiscardnoexcept

Returns the internal stopwatch of the session, started by initialise() and stopped at the end of run_suites(); the elapsed time is complete only after run_suites() has returned. In v5.0.1, the returned class was detail::timestamps, now a deprecated alias; only its read-only members are kept. The timings are internal; the elapsed times are shown by the reporters.

Parameters

None.

Returns

A const reference to the stopwatch of the session.

Deprecated

the timings are internal (since 6.0.0)

Returns a const reference to the stopwatch member.

Definition at line 147 of file runner-inlines.h.

  {
    return stopwatch_;
  }

References stopwatch_.

timings() [2/2]

detail::stopwatch & micro_os_plus::micro_test_plus::runner::timings ( void )

inlinenodiscardnoexcept

Kept for the v5.0.1 code that binds a non-const reference (detail::timestamps& t = tr.timings ();). The test code must not start or stop the stopwatch through it, since the reporters show its elapsed time.

Parameters

None.

Returns

A reference to the stopwatch of the session.

Deprecated

the timings are internal (since 6.0.0)

Returns a reference to the stopwatch member.

Definition at line 158 of file runner-inlines.h.

  {
    return stopwatch_;
  }

References stopwatch_.

total_suites_count()

size_t micro_os_plus::micro_test_plus::runner::total_suites_count ( void ) const

nodiscardnoexcept

One, if the top suite was added by add_top_suite(), plus added_suites_count() plus static_suites_count(); this is the number of suites printed by the reporters.

Parameters

None.

Returns

The total number of test suites managed by this runner, including the top suite, if any, and the static suites.

Returns one, if the top suite was added, plus the count of the suites added with add_suite(), plus the count of the static suites.

Definition at line 1131 of file runner.cpp.

  {
    return (has_top_suite_ ? 1u : 0u) + added_suites_count ()
           + static_suites_count ();
  }

References added_suites_count(), has_top_suite_, and static_suites_count().

Referenced by micro_os_plus::micro_test_plus::detail::reporter_tap::end_session(), micro_os_plus::micro_test_plus::detail::reporter::format_session_totals(), and run_suites().

totals()

const counters & micro_os_plus::micro_test_plus::runner::totals ( void ) const

inlinenodiscardnoexcept

The counters include the checks and the test cases of all the suites that were run, including the top suite, if any; they are complete only after run_suites() has returned. The totals are read-only; there is no non-const overload, so that the counters cannot be modified from the test code.

Parameters

None.

Returns

A const reference to the session totals.

Returns a const reference to the counters member.

Definition at line 124 of file runner-inlines.h.

  {
    return totals_;
  }

References totals_.

Referenced by micro_os_plus::micro_test_plus::detail::reporter_human::end_session(), and micro_os_plus::micro_test_plus::detail::reporter::format_session_totals().

verbosity()

auto micro_os_plus::micro_test_plus::runner::verbosity ( void ) const -> micro_test_plus::verbosity

inlinenodiscardnoexcept

Calls verbosity_level(). The old name hid the verbosity enumeration inside the runner.

Parameters

None.

Returns

The value returned by verbosity_level().

Deprecated

use verbosity_level() (since 6.0.0)

Forwards to verbosity_level().

Definition at line 113 of file runner-inlines.h.

  {
    return verbosity_level ();
  }

References verbosity_level().

verbosity_level()

auto micro_os_plus::micro_test_plus::runner::verbosity_level ( void ) const -> micro_test_plus::verbosity

inlinenodiscardnoexcept

The level is selected with the --silent, --quiet, and --verbose command-line options, or with runner_options::verbosity_level; the tests can use it to decide whether to display their own messages. Before initialise() is called, it is verbosity::normal.

Parameters

None.

Returns

The active verbosity value.

Since

6.0.0

Returns the level kept in options_, which does not depend on the reporter, so the call is safe before initialise().

Definition at line 77 of file runner-inlines.h.

  {
    return options_.verbosity_level;
  }

References options_.

Referenced by verbosity().

Friends And Related Symbol Documentation

detail::reporter_human

friend class detail::reporter_human

friend

It reads the stopwatch, to display the duration of the session.

Definition at line 194 of file runner.h.

detail::reporter_tap

friend class detail::reporter_tap

friend

It reads the stopwatch, to display the duration of the session.

Definition at line 202 of file runner.h.

detail::runnable_base

friend class detail::runnable_base

friend

It passes the reporter to the suites and the test cases, applies the filter, lists the test cases, keeps the running test case, and aborts for a failed requirement.

Definition at line 213 of file runner.h.

static_suite

friend class static_suite

friend

The static_suite constructors call link_static_suite(), which rejects the suites constructed after run_suites() has started.

Definition at line 222 of file runner.h.

References static_suite.

Referenced by static_suite.

Member Data Documentation

abort_handler_

abort_handler_t micro_os_plus::micro_test_plus::runner::abort_handler_ = nullptr

private

Set by set_abort_handler().

Definition at line 1373 of file runner.h.

Referenced by abort(), and set_abort_handler().

aborted_

bool micro_os_plus::micro_test_plus::runner::aborted_ = false

private

Set by abort(), before the abort is reported, and never cleared. Read by detail::runnable_base, a friend, so that, when the abort handler throws an exception, the test cases and the suites pass it on instead of reporting it, and no test case runs afterwards; read by initialise() and run_suites(), which then refuse to start, and by abort(), so that a later abort is not reported again.

Definition at line 1386 of file runner.h.

Referenced by abort(), micro_os_plus::micro_test_plus::detail::runnable_base::accepts_test_case(), add_top_suite(), micro_os_plus::micro_test_plus::detail::runnable_base::after_test_case_create(), initialise(), initialise(), initialise(), reject_call(), and run_suites().

children_suites_

std::vector<std::unique_ptr<class suite> > micro_os_plus::micro_test_plus::runner::children_suites_

private

Each call to add_suite() appends a new suite to this vector, and inserts it into the list of suites, sorted by name; the suites are run later, by run_suites(), in the order of the list. The vector retains ownership of all suites for the lifetime of the runner.

Definition at line 1263 of file runner.h.

Referenced by added_suites_count(), register_suite(), and static_suites_count().

exit_code_

int micro_os_plus::micro_test_plus::runner::exit_code_ = 1

private

Returned again by the calls of run_suites() made after the session ended.

Definition at line 1354 of file runner.h.

Referenced by initialise(), mark_rejected(), and run_suites().

has_rejected_calls_

bool micro_os_plus::micro_test_plus::runner::has_rejected_calls_ = false

private

Set by mark_rejected(), for a suite added after run_suites() had started, and for a second call of initialise() or of add_top_suite(); run_suites() then returns 1, unless an option error requires 2.

Definition at line 1365 of file runner.h.

Referenced by mark_rejected(), and run_suites().

has_top_suite_

bool micro_os_plus::micro_test_plus::runner::has_top_suite_ = false

private

Set by add_top_suite(). When not set, the top suite is neither run, nor reported, nor counted.

Definition at line 1252 of file runner.h.

Referenced by add_top_suite(), run_child_suites(), run_suites(), and total_suites_count().

listed_suite_

const class suite* micro_os_plus::micro_test_plus::runner::listed_suite_ = nullptr

private

Used by list_test_case() to write the name of a suite only once, before its first listed test case.

Definition at line 1418 of file runner.h.

Referenced by list_test_case().

listed_suites_count_

size_t micro_os_plus::micro_test_plus::runner::listed_suites_count_ = 0

private

Incremented by list_test_case() when it writes the name of a suite; written by run_suites() at the end of the list.

Definition at line 1436 of file runner.h.

Referenced by list_test_case(), and run_suites().

listed_test_cases_count_

size_t micro_os_plus::micro_test_plus::runner::listed_test_cases_count_ = 0

private

Incremented by list_test_case(); written by run_suites() at the end of the list.

Definition at line 1427 of file runner.h.

Referenced by list_test_case(), and run_suites().

options_

runner_options micro_os_plus::micro_test_plus::runner::options_ {}

private

Moved in by initialise(), and kept for the whole session: the verbosity is returned by verbosity_level(), the filter patterns are read by is_selected(), the listing of the test cases by run_suites() and is_listing(), and the command line by the reporters, which are friends. The defaults until then.

Definition at line 1306 of file runner.h.

Referenced by micro_os_plus::micro_test_plus::detail::runnable_base::accepts_test_case(), add_top_suite(), micro_os_plus::micro_test_plus::detail::runnable_base::after_test_case_create(), application_arguments(), micro_os_plus::micro_test_plus::detail::reporter_human::begin_session(), micro_os_plus::micro_test_plus::detail::reporter_tap::begin_session(), has_option_errors(), initialise(), is_listing(), is_selected(), reject_call(), run_child_suites(), run_suites(), and verbosity_level().

reporter_

std::unique_ptr<detail::reporter> micro_os_plus::micro_test_plus::runner::reporter_

private

Created by initialise(), as selected by the session options, either given by the caller or parsed from the command line by the runner_options constructor. Used by the suites and the test cases, through detail::runnable_base, which is a friend.

Definition at line 1275 of file runner.h.

Referenced by abort(), add_top_suite(), has_option_errors(), initialise(), list_test_case(), reject_call(), reporter(), run_child_suites(), and run_suites().

running_suite_

class suite* micro_os_plus::micro_test_plus::runner::running_suite_ = nullptr

private

Set to the top suite by add_top_suite(), and cleared when run_suites() starts; set by detail::runnable_base, a friend, to each suite while its body is called, and restored when the body returns. suite::test() accepts new test cases only on this suite (see runnable_base::accepts_test_case()).

Definition at line 1409 of file runner.h.

Referenced by micro_os_plus::micro_test_plus::detail::runnable_base::accepts_test_case(), add_top_suite(), reject_call(), and run_suites().

running_test_case_

test_case* micro_os_plus::micro_test_plus::runner::running_test_case_ = nullptr

private

Set by detail::runnable_base, a friend, while a test case runs, and restored when it ends, so that suite::test(), when called from the body of a test case (for example via a captured suite reference), runs the new test case nested in it.

Definition at line 1397 of file runner.h.

Referenced by micro_os_plus::micro_test_plus::detail::runnable_base::accepts_test_case(), micro_os_plus::micro_test_plus::detail::runnable_base::after_test_case_create(), and reject_call().

session_state_

session_state micro_os_plus::micro_test_plus::runner::session_state_ = session_state::created

private

Set by initialise() and run_suites(); read by register_suite(), to reject the suites added too late and to discard silently those added to a declined session.

Definition at line 1345 of file runner.h.

Referenced by abort(), add_top_suite(), initialise(), initialise(), initialise(), mark_rejected(), register_suite(), reject_call(), and run_suites().

skipped_suites_count_

size_t micro_os_plus::micro_test_plus::runner::skipped_suites_count_ = 0

private

Incremented by run_child_suites(); returned by skipped_suites_count().

Definition at line 1315 of file runner.h.

Referenced by run_child_suites(), and skipped_suites_count().

started_first_

runner * micro_os_plus::micro_test_plus::runner::started_first_ = nullptr

staticconstinitprivate

Constant-initialised, so it is valid before any constructor runs. A runner is inserted by run_suites() and removed by the destructor.

Constant-initialised, so it is null before any static constructor runs.

Definition at line 1144 of file runner.h.

Referenced by ~runner(), link_static_suite(), and run_suites().

started_next_

runner* micro_os_plus::micro_test_plus::runner::started_next_ = nullptr

private

Null if this runner has not started, or is the last one.

Definition at line 1152 of file runner.h.

Referenced by ~runner(), and run_suites().

stopwatch_

detail::stopwatch micro_os_plus::micro_test_plus::runner::stopwatch_

private

Measures the duration of the entire test session; started by initialise(), stopped by run_suites(), and read by the reporters, which are friends.

Definition at line 1285 of file runner.h.

Referenced by micro_os_plus::micro_test_plus::detail::reporter_human::end_session(), micro_os_plus::micro_test_plus::detail::reporter_tap::end_session(), initialise(), run_suites(), timings(), and timings().

top_suite_

class top_suite micro_os_plus::micro_test_plus::runner::top_suite_

private

Always constructed with the runner, but part of the session only after add_top_suite() (see has_top_suite_); its test cases are added directly, between add_top_suite() and run_suites().

Definition at line 1243 of file runner.h.

Referenced by runner(), runner(), add_top_suite(), initialise(), and run_suites().

totals_

counters micro_os_plus::micro_test_plus::runner::totals_

private

The totals of each suite are added by run_suites() and run_child_suites(), after the suite was run.

Definition at line 1294 of file runner.h.

Referenced by run_child_suites(), run_suites(), and totals().

---

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

• runner.h
• runner-inlines.h
• runner.cpp