runner Class
The test runner for the µTest++ framework. More...
Declaration
Included Headers
Public Member Typedefs Index
| using | abort_handler_t = void(*)(const reflection::source_location &sl) |
|
The type of the function called when test execution is aborted. More... | |
Private Enumerations Index
| enum class | session_state { ... } |
|
The states of a test session. More... | |
Friends Index
| class | detail::reporter_human |
|
The human-readable reporter, which displays the session. More... | |
| class | detail::reporter_tap |
|
The TAP reporter, which displays the session. More... | |
| class | detail::runnable_base |
|
The base of the nodes, which shares the state of the session. More... | |
| class | static_suite |
|
The static suites link themselves through the runner. More... | |
Public Constructors Index
| runner (const runner &)=delete | |
|
Deleted copy constructor to prevent copying. More... | |
| runner (runner &&)=delete | |
|
Deleted move constructor to prevent moving. More... | |
| runner (void) | |
|
Constructor for the runner class. More... | |
Public Destructor Index
| ~runner () | |
|
Destructor for the runner class. More... | |
Public Operators Index
| runner & | operator= (const runner &)=delete |
|
Deleted copy assignment operator to prevent copying. More... | |
| runner & | operator= (runner &&)=delete |
|
Deleted move assignment operator to prevent moving. More... | |
Public Member Functions Index
| void | abort (const reflection::source_location &sl=reflection::source_location::current()) |
|
Aborts test execution immediately. More... | |
template <typename Callable_T, typename... 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(). More... | |
| class suite & | add_top_suite (const located_name &top_suite_name) |
|
Adds the top suite and returns it. More... | |
| class suite & | add_top_suite (void) |
|
Adds the top suite, without a name, and returns it. More... | |
| size_t | added_suites_count (void) const noexcept |
|
Returns the count of the test suites added with add_suite(). More... | |
| std::span< const std::string > | application_arguments (void) const noexcept |
|
Returns the command-line arguments left to the application. More... | |
| void | initialise (int argc, char *argv[]) |
|
Initialises the test runner with the command-line arguments. More... | |
| void | initialise (runner_options options) |
|
Initialises the test runner with the given options. More... | |
| bool | is_listing (void) const noexcept |
|
Checks whether the test cases are listed instead of run. More... | |
| int | run_suites (void) |
|
Runs the registered suites, ends the session, and returns the exit code. More... | |
| abort_handler_t | set_abort_handler (abort_handler_t handler) noexcept |
|
Sets the function called when test execution is aborted. More... | |
| size_t | skipped_suites_count (void) const noexcept |
|
Returns the count of the test suites skipped by the filter. More... | |
| size_t | static_suites_count (void) const noexcept |
|
Returns the count of static test suites. More... | |
| size_t | total_suites_count (void) const noexcept |
|
Returns the count of all the test suites. More... | |
| const counters & | totals (void) const noexcept |
|
Returns the totals of the test session. More... | |
| micro_test_plus::verbosity | verbosity_level (void) const noexcept |
|
Returns the verbosity level of the console output. More... | |
Private Member Functions Index
| void | abort (const reflection::source_location &sl, bool is_requirement) |
|
Aborts test execution, telling the reporter why. More... | |
| bool | has_option_errors (void) const noexcept |
|
Checks whether an option error was found by initialise(). More... | |
| 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. More... | |
| void | list_test_case (const class suite &suite, const class test_case &test_case) |
|
Lists a test case, instead of running it. More... | |
| void | mark_rejected (void) noexcept |
|
Records that a call was rejected. More... | |
| void | register_suite (std::unique_ptr< class suite > suite) |
|
Registers a test suite with the runner. More... | |
| void | reject_call (const std::string &message, const reflection::source_location *location=nullptr) |
|
Reports a rejected call, and records it. More... | |
| void | reject_suite (const char *name, const reflection::source_location &location) |
|
Rejects a suite constructed after run_suites() has started. More... | |
| void | run_child_suites (void) |
|
Runs all registered test suites. More... | |
Private Member Attributes Index
| abort_handler_t | abort_handler_ = nullptr |
| bool | aborted_ = false |
|
Whether the test execution was aborted. More... | |
| std::vector< std::unique_ptr< class suite > > | children_suites_ |
|
Owning collection of dynamically registered child suites. More... | |
| int | exit_code_ = 1 |
|
The exit code computed by run_suites(). More... | |
| bool | has_rejected_calls_ = false |
|
Whether a call was rejected. More... | |
| bool | has_top_suite_ = false |
|
Whether the top suite was added to the session. More... | |
| const class suite * | listed_suite_ = nullptr |
|
The suite whose name was listed last, if any. More... | |
| size_t | listed_suites_count_ = 0 |
|
The number of suites with listed test cases. More... | |
| size_t | listed_test_cases_count_ = 0 |
|
The number of listed test cases. More... | |
| runner_options | options_ {} |
|
The options of the test session. More... | |
| std::unique_ptr< detail::reporter > | reporter_ |
|
Owning pointer to the test reporter used for outputting test results. More... | |
| class { ... } | running_suite_ = nullptr |
|
The suite whose body is running, if any. More... | |
| test_case * | running_test_case_ = nullptr |
|
The innermost test case being run, if any. More... | |
| session_state | session_state_ = session_state::created |
|
The current state of the test session. More... | |
| size_t | skipped_suites_count_ = 0 |
|
The number of suites skipped by the filter. More... | |
| runner * | started_next_ = nullptr |
|
The next runner in the list of the started runners. More... | |
| detail::stopwatch | stopwatch_ |
|
Stopwatch of this runner. More... | |
| class { ... } | top_suite_ |
|
The top suite, whose body is the code of main(). More... | |
| counters | totals_ |
|
Totals of the test session. More... | |
Private Static Functions Index
| static void | link_static_suite (runner &test_runner, class suite &suite) noexcept |
|
Inserts a static suite into the list of suites, or reject it. More... | |
Private Static Attributes Index
| static runner * | started_first_ = nullptr |
|
The head of the list of the runners that have started. More... | |
Deprecated Functions Index
| runner (const char *top_suite_name) | |
|
Deprecated constructor for the runner class. More... | |
| 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. More... | |
| int | exit_code (void) |
|
Deprecated name of run_suites(). More... | |
template <typename Callable_T, typename... Args_T> | |
| void | suite (std::string_view name, Callable_T &&callable, Args_T &&... arguments) |
|
Deprecated name of add_suite(). More... | |
| micro_test_plus::verbosity | verbosity (void) const noexcept |
|
Deprecated name of verbosity_level(). More... | |
| const char * | name (void) const noexcept |
|
Deprecated name of the runner. More... | |
| size_t | suites_count (void) const noexcept |
|
Deprecated count of the test suites added with add_suite(), plus the top suite. More... | |
| const detail::stopwatch & | timings (void) const noexcept |
|
Deprecated access to the timings of the test session. More... | |
| detail::stopwatch & | timings (void) noexcept |
|
Deprecated access to the timings of the test session, as a non-const reference. More... | |
| detail::reporter & | reporter (void) const noexcept |
|
Deprecated access to the reporter of the test session. More... | |
Description
The test runner for the µTest++ framework.
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:
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.
Public Member Typedefs
abort_handler_t
|
The type of the function called when test execution is aborted.
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.
Private Enumerations
session_state
| strong |
The states of a test session.
- Enumeration values
-
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.
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.
Friends
detail::reporter_human
|
The human-readable reporter, which displays the session.
It reads the stopwatch, to display the duration of the session.
Definition at line 194 of file runner.h.
detail::reporter_tap
|
The TAP reporter, which displays the session.
It reads the stopwatch, to display the duration of the session.
Definition at line 202 of file runner.h.
detail::runnable_base
|
The base of the nodes, which shares the state of the session.
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
|
The static suites link themselves through the runner.
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.
Reference static_suite.
Referenced by static_suite.
Public Constructors
runner()
| delete |
runner()
| delete |
runner()
|
Constructor for the runner class.
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.
Declaration at line 235 of file runner.h, definition at line 120 of file runner.cpp.
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=.
Public Destructor
~runner()
|
Destructor for the runner class.
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.
Declaration at line 307 of file runner.h, definition at line 149 of file runner.cpp.
References runner, started_first_ and started_next_.
Public Operators
operator=()
| delete |
operator=()
| delete |
Deleted move assignment operator to prevent moving.
The suites keep a reference to the runner, so it must not be relocated.
Definition at line 297 of file runner.h.
References runner, add_suite, add_top_suite, exit_code, initialise, name, run_suites and suite.
Public Member Functions
abort()
|
Aborts test execution immediately.
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.
Declaration at line 718 of file runner.h, definition at line 1004 of file runner.cpp.
Reference abort.
Referenced by micro_os_plus::micro_test_plus::detail::runnable_base::abort, abort and abort.
add_suite()
|
Adds a test suite to the runner, to be run by run_suites().
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().
Declaration at line 582 of file runner.h, definition at line 191 of file runner-inlines.h.
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.
add_top_suite()
|
Adds the top suite and returns it.
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.
Declaration at line 452 of file runner.h, definition at line 420 of file runner.cpp.
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()
|
Adds the top suite, without a name, and returns it.
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&.
Declaration at line 469 of file runner.h, definition at line 514 of file runner.cpp.
Reference add_top_suite.
added_suites_count()
| nodiscard noexcept |
Returns the count of the test suites added with add_suite().
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_.
Declaration at line 824 of file runner.h, definition at line 1073 of file runner.cpp.
Reference children_suites_.
Referenced by suites_count and total_suites_count.
application_arguments()
| inline nodiscard noexcept |
Returns the command-line arguments left to the application.
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.
Declaration at line 953 of file runner.h, definition at line 135 of file runner-inlines.h.
Reference options_.
initialise()
|
Initialises the test runner with the command-line arguments.
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.
Declaration at line 374 of file runner.h, definition at line 216 of file runner.cpp.
References aborted_, created, initialise and session_state_.
initialise()
|
Initialises the test runner with the given 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:
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.
Declaration at line 416 of file runner.h, definition at line 273 of file runner.cpp.
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()
| inline nodiscard noexcept |
Checks whether the test cases are listed instead of run.
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.
Declaration at line 779 of file runner.h, definition at line 87 of file runner-inlines.h.
Reference options_.
run_suites()
| nodiscard |
Runs the registered suites, ends the session, and returns the exit code.
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.
Declaration at line 517 of file runner.h, definition at line 840 of file runner.cpp.
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.
set_abort_handler()
| noexcept |
Sets the function called when test execution is aborted.
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.
Declaration at line 690 of file runner.h, definition at line 991 of file runner.cpp.
Reference abort_handler_.
skipped_suites_count()
| nodiscard noexcept |
Returns the count of the test suites skipped by the filter.
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().
Declaration at line 911 of file runner.h, definition at line 1142 of file runner.cpp.
Reference skipped_suites_count_.
Referenced by micro_os_plus::micro_test_plus::detail::reporter::format_session_totals.
static_suites_count()
| nodiscard noexcept |
Returns the count of static test suites.
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.
Declaration at line 890 of file runner.h, definition at line 1111 of file runner.cpp.
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.
total_suites_count()
| nodiscard noexcept |
Returns the count of all the test suites.
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.
Declaration at line 738 of file runner.h, definition at line 1131 of file runner.cpp.
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()
| inline nodiscard noexcept |
Returns the totals of the test session.
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.
Declaration at line 928 of file runner.h, definition at line 124 of file runner-inlines.h.
Reference 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_level()
| inline nodiscard noexcept |
Returns the verbosity level of the console output.
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().
Declaration at line 757 of file runner.h, definition at line 77 of file runner-inlines.h.
Reference options_.
Referenced by verbosity.
Private Member Functions
abort()
|
Aborts test execution, telling the reporter why.
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.
Declaration at line 1231 of file runner.h, definition at line 1029 of file runner.cpp.
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_.
has_option_errors()
| inline nodiscard noexcept |
Checks whether an option error was found by initialise().
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.
Declaration at line 1192 of file runner.h, definition at line 100 of file runner-inlines.h.
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.
is_selected()
| nodiscard |
Checks whether a suite or a test case is selected by the filter pattern of its nesting level.
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.
Declaration at line 1173 of file runner.h, definition at line 530 of file runner.cpp.
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.
list_test_case()
|
Lists a test case, instead of running it.
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.
Declaration at line 1212 of file runner.h, definition at line 563 of file runner.cpp.
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()
| noexcept |
Records that a call was rejected.
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.
Declaration at line 1114 of file runner.h, definition at line 711 of file runner.cpp.
References exit_code_, finished, has_rejected_calls_ and session_state_.
Referenced by reject_call.
register_suite()
|
Registers a test suite with the runner.
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().
Declaration at line 1054 of file runner.h, definition at line 599 of file runner.cpp.
References children_suites_, declined, finished, reject_suite, running, session_state_ and suite.
Referenced by add_suite.
reject_call()
|
Reports a rejected call, and records it.
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.
Declaration at line 1096 of file runner.h, definition at line 660 of file runner.cpp.
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()
|
Rejects a suite constructed after run_suites() has started.
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.
Declaration at line 1070 of file runner.h, definition at line 628 of file runner.cpp.
References name and reject_call.
Referenced by add_top_suite and register_suite.
run_child_suites()
|
Runs all registered test suites.
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.
Declaration at line 1039 of file runner.h, definition at line 778 of file runner.cpp.
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.
Private Member Attributes
abort_handler_
|
The function called by abort(), if not null.
Set by set_abort_handler().
Definition at line 1373 of file runner.h.
Referenced by abort and set_abort_handler.
aborted_
|
Whether the test execution was aborted.
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_
|
Owning collection of dynamically registered child suites.
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_
|
The exit code computed by run_suites().
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_
|
Whether a call was rejected.
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_
|
Whether the top suite was added to the session.
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_
|
The suite whose name was listed last, if any.
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_
|
The number of suites with listed test cases.
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_
|
The number of listed test cases.
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_
|
The options of the test session.
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_
|
Owning pointer to the test reporter used for outputting test results.
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_
|
The suite whose body is running, if any.
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_
|
The innermost test case being run, if any.
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_
|
The current state of the test session.
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_
|
The number of suites skipped by the filter.
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_next_
|
The next runner in the list of the started runners.
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_
|
Stopwatch of this runner.
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_
|
The top suite, whose body is the code of main().
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_
|
Totals of the test session.
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.
Private Static Functions
link_static_suite()
| noexcept static |
Inserts a static suite into the list of suites, or reject it.
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.
Declaration at line 1135 of file runner.h, definition at line 728 of file runner.cpp.
References runner, started_first_ and suite.
Referenced by micro_os_plus::micro_test_plus::static_suite::link_or_reject.
Private Static Attributes
started_first_
| static |
The head of the list of the runners that have started.
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.
Deprecated Functions
exit_code()
|
Deprecated name of run_suites().
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.
Declaration at line 537 of file runner.h, definition at line 979 of file runner.cpp.
Reference run_suites.
Referenced by operator=.
initialise()
|
Deprecated initialisation with the command-line arguments, which also adds the top suite.
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.
Declaration at line 343 of file runner.h, definition at line 189 of file runner.cpp.
References aborted_, add_top_suite, created, initialise, session_state_ and top_suite_.
Referenced by add_top_suite, initialise, initialise, operator= and run_suites.
name()
| nodiscard noexcept |
Deprecated name of the runner.
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.
Declaration at line 851 of file runner.h, definition at line 1086 of file runner.cpp.
Referenced by add_suite, is_selected, operator=, reject_suite and suite.
reporter()
| inline nodiscard noexcept |
Deprecated access to the reporter of the test session.
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().
Declaration at line 1015 of file runner.h, definition at line 170 of file runner-inlines.h.
Reference reporter_.
runner()
|
Deprecated constructor for the runner class.
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.
Declaration at line 253 of file runner.h, definition at line 135 of file runner.cpp.
References micro_os_plus::micro_test_plus::detail::runnable_base::name and top_suite_.
suite()
|
Deprecated name of add_suite().
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().
Declaration at line 640 of file runner.h, definition at line 231 of file runner-inlines.h.
References add_suite and name.
Referenced by add_suite, link_static_suite, list_test_case, operator= and register_suite.
suites_count()
| nodiscard noexcept |
Deprecated count of the test suites added with add_suite(), plus the top suite.
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.
Declaration at line 871 of file runner.h, definition at line 1098 of file runner.cpp.
Reference added_suites_count.
timings()
| inline nodiscard noexcept |
Deprecated access to the timings of the test session.
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.
Declaration at line 978 of file runner.h, definition at line 147 of file runner-inlines.h.
Reference stopwatch_.
timings()
| inline nodiscard noexcept |
Deprecated access to the timings of the test session, as a non-const reference.
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.
Declaration at line 996 of file runner.h, definition at line 158 of file runner-inlines.h.
Reference stopwatch_.
verbosity()
| inline nodiscard noexcept |
Deprecated name of verbosity_level().
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().
Declaration at line 799 of file runner.h, definition at line 113 of file runner-inlines.h.
Reference verbosity_level.
The documentation for this class was generated from the following files:
Generated via doxygen2docusaurus 2.2.8 by Doxygen 1.18.0.