runner.h File

C++ header file with declarations for the µTest++ test runner. More...

Included Headers

#include "stopwatch.h" #include "test.h" #include "reflection.h" #include "reporter.h" #include "runner-options.h" #include "counters.h" #include <functional> #include <memory> #include <span> #include <string> #include <string_view> #include <vector> #include "inlines/runner-inlines.h"

Namespaces Index

namespace	micro_os_plus
	The primary namespace for the µOS++ framework. More...
namespace	micro_test_plus
	Primary namespace for the µTest++ testing framework. More...

Classes Index

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

Description

C++ header file with declarations for the µTest++ test runner.

This header provides the declarations for the test runner facilities used within the µTest++ framework. It defines the runner class, which manages the registration and execution of test suites, including the static suites declared at namespace scope. The deprecated static_runner alias is declared in deprecated.h.

The test runner is responsible for initialising the test environment, creating the reporter, registering test suites, processing command-line arguments, and determining the overall test result via an exit code. It also provides a mechanism for aborting test execution.

All definitions reside within the micro_os_plus::micro_test_plus namespace.

This file is included by micro-os-plus/micro-test-plus.h, which is the header that the applications include.

File Listing

The file content with the documentation metadata removed is:

1/*

2 * This file is part of the µOS++ project (https://micro-os-plus.github.io/).

3 * Copyright (c) 2021-2026 Liviu Ionescu. All rights reserved.

4 *

5 * Permission to use, copy, modify, and/or distribute this software for any

6 * purpose is hereby granted, under the terms of the MIT license.

7 *

8 * If a copy of the license was not distributed with this file, it can be

9 * obtained from https://opensource.org/licenses/mit.

10 */

11

12// ----------------------------------------------------------------------------

13

36

37#ifndef MICRO_OS_PLUS_MICRO_TEST_PLUS_RUNNER_H_

38#define MICRO_OS_PLUS_MICRO_TEST_PLUS_RUNNER_H_

39

40// ----------------------------------------------------------------------------

41

42#if defined(__cplusplus)

43

44// ----------------------------------------------------------------------------

45

46#if __has_include("micro-os-plus/project-config.h")

47#include "micro-os-plus/project-config.h"

48#endif // __has_include("micro-os-plus/project-config.h")

49

50#if __has_include("micro-os-plus/micro-test-plus-defines.h")

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

52#endif // __has_include("micro-os-plus/micro-test-plus-defines.h")

53

54#include "stopwatch.h"

55#include "test.h"

56#include "reflection.h"

57#include "reporter.h"

58#include "runner-options.h"

59#include "counters.h"

60

61#include <functional>

62#include <memory>

63#include <span>

64#include <string>

65#include <string_view>

66#include <vector>

67

68// ----------------------------------------------------------------------------

69

70#if defined(__GNUC__)

71#pragma GCC diagnostic push

72

73#pragma GCC diagnostic ignored "-Wpadded"

74#if defined(__clang__)

75#pragma clang diagnostic ignored "-Wc++98-compat"

76#else // GCC only

77#pragma GCC diagnostic ignored "-Wsuggest-final-types"

78#pragma GCC diagnostic ignored "-Wsuggest-final-methods"

79#pragma GCC diagnostic ignored "-Wredundant-tags"

80#endif // defined(__clang__)

81#endif // defined(__GNUC__)

82

83// ============================================================================

84

109namespace micro_os_plus::micro_test_plus

110{

111 // --------------------------------------------------------------------------

112

113 class suite;

114 class test_case;

115 class top_suite;

116

117 // ==========================================================================

118

186 class runner

187 {

194 friend class detail::reporter_human;

195

202 friend class detail::reporter_tap;

203

213 friend class detail::runnable_base;

214

222 friend class static_suite;

223

224 public:

235 runner (void);

236

237#if defined(MICRO_OS_PLUS_MICRO_TEST_PLUS_DEPRECATED_ENABLED)

242

252 [[deprecated ("use runner() and add_top_suite() (since 4.1.0)")]]

253 runner (const char* top_suite_name);

254

258#endif // defined(MICRO_OS_PLUS_MICRO_TEST_PLUS_DEPRECATED_ENABLED)

259

267 runner (const runner&) = delete;

268

276 runner (runner&&) = delete;

277

285 runner&

286 operator=(const runner&)

287 = delete;

288

296 runner&

297 operator=(runner&&)

298 = delete;

299

307 ~runner ();

308

309#if defined(MICRO_OS_PLUS_MICRO_TEST_PLUS_DEPRECATED_ENABLED)

314

341 [[deprecated ("use initialise (argc, argv) and add_top_suite() "

342 "(since 6.0.0)")]] class suite&

343 initialise (int argc, char* argv[], const char* top_suite_name);

344

348#endif // defined(MICRO_OS_PLUS_MICRO_TEST_PLUS_DEPRECATED_ENABLED)

349

373 void

374 initialise (int argc, char* argv[]);

375

415 void

416 initialise (runner_options options);

417

451 class suite&

452 add_top_suite (const located_name& top_suite_name);

453

468 class suite&

469 add_top_suite (void);

470

516 [[nodiscard]] int

517 run_suites (void);

518

519#if defined(MICRO_OS_PLUS_MICRO_TEST_PLUS_DEPRECATED_ENABLED)

524

536 [[deprecated ("use run_suites() (since 6.0.0)")]] int

537 exit_code (void);

538

542#endif // defined(MICRO_OS_PLUS_MICRO_TEST_PLUS_DEPRECATED_ENABLED)

543

579 template <typename Callable_T, typename... Args_T>

580 requires detail::suite_body<Callable_T, Args_T...>

581 void

582 add_suite (located_name name, Callable_T&& callable,

583 Args_T&&... arguments);

584

585#if !defined(__DOXYGEN__)

604 template <typename Callable_T, typename... Args_T>

605 requires (!detail::suite_body<Callable_T, Args_T...>)

606 void

607 add_suite (located_name name, Callable_T&& callable,

608 Args_T&&... arguments);

609#endif // !defined(__DOXYGEN__)

610

611#if defined(MICRO_OS_PLUS_MICRO_TEST_PLUS_DEPRECATED_ENABLED)

616

638 template <typename Callable_T, typename... Args_T>

639 [[deprecated ("use add_suite() (since 6.0.0)")]] void

640 suite (std::string_view name, Callable_T&& callable,

641 Args_T&&... arguments);

642

646#endif // defined(MICRO_OS_PLUS_MICRO_TEST_PLUS_DEPRECATED_ENABLED)

647

648 // ------------------------------------------------------------------------

649

670 using abort_handler_t = void (*) (const reflection::source_location& sl);

671

689 abort_handler_t

690 set_abort_handler (abort_handler_t handler) noexcept;

691

717 [[noreturn]] void

718 abort (const reflection::source_location& sl

719 = reflection::source_location::current ());

720

721 // ------------------------------------------------------------------------

722 // Getters.

723

737 [[nodiscard]] size_t

738 total_suites_count (void) const noexcept;

739

756 [[nodiscard]] auto

757 verbosity_level (void) const noexcept -> micro_test_plus::verbosity;

758

778 [[nodiscard]] bool

779 is_listing (void) const noexcept;

780

781#if defined(MICRO_OS_PLUS_MICRO_TEST_PLUS_DEPRECATED_ENABLED)

786

798 [[deprecated ("use verbosity_level() (since 6.0.0)"), nodiscard]] auto

799 verbosity (void) const noexcept -> micro_test_plus::verbosity;

800

804#endif // defined(MICRO_OS_PLUS_MICRO_TEST_PLUS_DEPRECATED_ENABLED)

805

823 [[nodiscard]] size_t

824 added_suites_count (void) const noexcept;

825

826#if defined(MICRO_OS_PLUS_MICRO_TEST_PLUS_DEPRECATED_ENABLED)

831

848 [[deprecated ("the runner has no name; see add_top_suite() "

849 "(since 6.0.0)"),

850 nodiscard]] const char*

851 name (void) const noexcept;

852

868 [[deprecated (

869 "use added_suites_count() or total_suites_count() (since 6.0.0)"),

870 nodiscard]] size_t

871 suites_count (void) const noexcept;

872

876#endif // defined(MICRO_OS_PLUS_MICRO_TEST_PLUS_DEPRECATED_ENABLED)

877

889 [[nodiscard]] size_t

890 static_suites_count (void) const noexcept;

891

910 [[nodiscard]] size_t

911 skipped_suites_count (void) const noexcept;

912

927 [[nodiscard]] const counters&

928 totals (void) const noexcept;

929

952 [[nodiscard]] std::span<const std::string>

953 application_arguments (void) const noexcept;

954

955#if defined(MICRO_OS_PLUS_MICRO_TEST_PLUS_DEPRECATED_ENABLED)

960

976 [[deprecated ("the timings are internal (since 6.0.0)"),

977 nodiscard]] const detail::stopwatch&

978 timings (void) const noexcept;

979

994 [[deprecated ("the timings are internal (since 6.0.0)"),

995 nodiscard]] detail::stopwatch&

996 timings (void) noexcept;

997

1013 [[deprecated ("use verbosity_level() (since 6.0.0)"),

1014 nodiscard]] detail::reporter&

1015 reporter (void) const noexcept;

1016

1020#endif // defined(MICRO_OS_PLUS_MICRO_TEST_PLUS_DEPRECATED_ENABLED)

1021

1022 private:

1038 void

1039 run_child_suites (void);

1040

1053 void

1054 register_suite (std::unique_ptr<class suite> suite);

1055

1069 void

1070 reject_suite (const char* name,

1071 const reflection::source_location& location);

1072

1095 void

1096 reject_call (const std::string& message,

1097 const reflection::source_location* location = nullptr);

1098

1113 void

1114 mark_rejected (void) noexcept;

1115

1134 static void

1135 link_static_suite (runner& test_runner, class suite& suite) noexcept;

1136

1144 static runner* started_first_;

1145

1152 runner* started_next_ = nullptr;

1153

1172 [[nodiscard]] bool

1173 is_selected (const char* name, size_t level) const;

1174

1191 [[nodiscard]] bool

1192 has_option_errors (void) const noexcept;

1193

1211 void

1212 list_test_case (const class suite& suite,

1213 const class test_case& test_case);

1214

1230 [[noreturn]] void

1231 abort (const reflection::source_location& sl, bool is_requirement);

1232

1233 // ------------------------------------------------------------------------

1234 private:

1243 class top_suite top_suite_;

1244

1252 bool has_top_suite_ = false;

1253

1263 std::vector<std::unique_ptr<class suite>> children_suites_;

1264

1275 std::unique_ptr<detail::reporter> reporter_;

1276

1285 detail::stopwatch stopwatch_;

1286

1294 counters totals_;

1295

1306 runner_options options_{};

1307

1315 size_t skipped_suites_count_ = 0;

1316

1328 enum class session_state

1329 {

1330 created,

1331 initialised,

1332 declined,

1333 running,

1334 finished

1335 };

1336

1345 session_state session_state_ = session_state::created;

1346

1354 int exit_code_ = 1;

1355

1365 bool has_rejected_calls_ = false;

1366

1373 abort_handler_t abort_handler_ = nullptr;

1374

1386 bool aborted_ = false;

1387

1397 test_case* running_test_case_ = nullptr;

1398

1409 class suite* running_suite_ = nullptr;

1410

1418 const class suite* listed_suite_ = nullptr;

1419

1427 size_t listed_test_cases_count_ = 0;

1428

1436 size_t listed_suites_count_ = 0;

1437 };

1438

1439 // --------------------------------------------------------------------------

1440} // namespace micro_os_plus::micro_test_plus

1441

1442#if defined(__GNUC__)

1443#pragma GCC diagnostic pop

1444#endif // defined(__GNUC__)

1445

1446// ----------------------------------------------------------------------------

1447

1448#endif // defined(__cplusplus)

1449

1450// ============================================================================

1451// Templates, inlines & constexpr implementations.

1452

1453#include "inlines/runner-inlines.h"

1454

1455// ----------------------------------------------------------------------------

1456

1457#endif // MICRO_OS_PLUS_MICRO_TEST_PLUS_RUNNER_H_

1458

1459// ----------------------------------------------------------------------------

---

Generated via doxygen2docusaurus 2.2.8 by Doxygen 1.18.0.