test.h File

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

Included Headers

#include "runner-totals.h" #include "type-traits.h" #include "timings.h" #include "reflection.h" #include <functional> #include <memory> #include "inlines/test-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...
namespace	detail
	Internal implementation details for the µTest++ framework. More...

Classes Index

class	runnable<Self_T>
	CRTP base class factoring out callable storage, rule-of-five, and run() logic shared by subtest and suite. More...
class	runnable_base
	Non-template base for all runnable objects (suites and subtests). More...
class	static_suite
	A test suite designed for static (namespace-scope) registration with a static_runner. More...
class	subtest
	A named, runnable test case that lives inside a suite. More...
class	suite
	A named, runnable test suite registered with the test runner. More...
class	test_node
	Base class for runners and runable tests. More...
class	top_suite
	The implicit top-level suite owned by every runner instance. More...

Functions Index

void	register_static_suite (static_runner &static_runner_ref, static_suite &static_suite_ref)
	Registers a static suite with a static runner. More...
runner &	to_runner (static_runner &static_runner_ref) noexcept
	Converts a static_runner reference to a runner reference. More...

Description

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

This header provides the declarations for the test suite facilities used within the µTest++ framework. It defines the interfaces for constructing, registering, and managing test suites and their associated test cases. The core classes, test_node and suite, offer mechanisms for tracking test case execution, managing counters for successful and failed checks, and supporting automated registration and discovery of test suites.

The design ensures that test suites are non-copyable and non-movable, maintaining unique ownership and consistent state. Flexible support for callable objects enables a wide range of test suite definitions, facilitating expressive and maintainable test organisation across embedded and general C++ projects.

All definitions reside within the micro_os_plus::micro_test_plus namespace, ensuring clear separation from user code and minimising the risk of naming conflicts.

The header files are organised within the include/micro-os-plus/micro-test-plus folder to maintain a structured and modular codebase.

This file is intended solely for internal use within the framework and should not be included directly by user code.

Functions

register_static_suite()

void micro_os_plus::micro_test_plus::detail::register_static_suite (static_runner & static_runner_ref, static_suite & static_suite_ref)

Registers a static suite with a static runner.

This declaration allows test-inlines.h to request registration without requiring the complete static_runner type in that header.

Parameters

static_runner_ref	The destination static runner.
static_suite_ref	The static suite to register.

Performs static-suite registration where static_runner is complete, allowing header-only template code to avoid direct dependence on runner.h include order.

Declaration at line 131 of file test.h, definition at line 95 of file runner.cpp.

95 detail::register_static_suite (static_runner& static_runner_ref,

96 static_suite& static_suite_ref)

97 {

98 static_runner::register_static_suite (static_runner_ref, static_suite_ref);

99 }

Reference micro_os_plus::micro_test_plus::static_runner::register_static_suite.

to_runner()

runner & micro_os_plus::micro_test_plus::detail::to_runner (static_runner & static_runner_ref)

noexcept

Converts a static_runner reference to a runner reference.

This declaration breaks the include-order cycle between test and runner headers. The definition is provided in a translation unit where both types are complete, so the conversion remains type-safe.

Parameters

static_runner_ref

The source static_runner reference.

Returns

The same object viewed as its runner base.

Performs the static_runner to runner upcast where both types are complete, allowing headers with only forward declarations to request this conversion safely.

Declaration at line 118 of file test.h, definition at line 83 of file runner.cpp.

83 detail::to_runner (static_runner& static_runner_ref) noexcept

84 {

85 return static_cast<runner&> (static_runner_ref);

86 }

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 * Major parts of the code are inspired from v1.1.8 of the Boost UT project,

12 * released under the terms of the Boost Version 1 Software License,

13 * which can be obtained from https://www.boost.org/LICENSE_1_0.txt.

14 */

15

16// ----------------------------------------------------------------------------

17

47

48#ifndef MICRO_OS_PLUS_MICRO_TEST_PLUS_TEST_H_

49#define MICRO_OS_PLUS_MICRO_TEST_PLUS_TEST_H_

50

51// ----------------------------------------------------------------------------

52

53#if defined(__cplusplus)

54

55// ----------------------------------------------------------------------------

56

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

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

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

60

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

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

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

64

65#include "runner-totals.h"

66#include "type-traits.h"

67#include "timings.h"

68#include "reflection.h"

69

70#include <functional>

71#include <memory>

72

73// ----------------------------------------------------------------------------

74

75#if defined(__GNUC__)

76#pragma GCC diagnostic push

77

78#pragma GCC diagnostic ignored "-Wpadded"

79#if defined(__clang__)

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

81#else // GCC only

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

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

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

85#endif // defined(__clang__)

86#endif // defined(__GNUC__)

87

88// =============================================================================

89

90namespace micro_os_plus::micro_test_plus

91{

92 // --------------------------------------------------------------------------

93

94 class runner;

95 class static_runner;

96 class reporter;

97 class runner_totals;

98 class subtest;

99 class suite;

100 class static_suite;

101

102 namespace detail

103 {

104 // ========================================================================

105

117 runner&

118 to_runner (static_runner& static_runner_ref) noexcept;

119

130 void

131 register_static_suite (static_runner& static_runner_ref,

132 static_suite& static_suite_ref);

133

154 class test_node

155 {

156 public:

162 test_node (const char* name);

163

167 test_node (const test_node&) = delete;

168

172 test_node (test_node&&) = delete;

173

177 test_node&

178 operator=(const test_node&)

179 = delete;

180

184 test_node&

185 operator=(test_node&&)

186 = delete;

187

191 virtual ~test_node ();

192

193 // ----------------------------------------------------------------------

194

202 [[nodiscard]] const char*

203 name (void) const noexcept;

204

205 public:

213 [[nodiscard]] runner_totals&

214 totals () noexcept;

215

223 [[nodiscard]] const runner_totals&

224 totals () const noexcept;

225

226 protected:

233 const char* name_;

234

238 runner_totals totals_;

239 };

240

241 // ========================================================================

242

262 class runnable_base : public test_node

263 {

264 public:

273 runnable_base (const char* name, runner& runner, size_t own_index);

274

278 runnable_base (const runnable_base&) = delete;

279

283 runnable_base (runnable_base&&) = delete;

284

288 runnable_base&

289 operator=(const runnable_base&)

290 = delete;

291

295 runnable_base&

296 operator=(runnable_base&&)

297 = delete;

298

302 virtual ~runnable_base () override;

303

304 // ----------------------------------------------------------------------

305

313 [[nodiscard]] size_t

314 own_index () const noexcept;

315

327 void

328 own_index (size_t index) noexcept;

329

337 [[nodiscard]] size_t

338 current_subtest_index () const noexcept;

339

347 size_t

348 increment_subtest_index () noexcept;

349

357 [[nodiscard]] size_t

358 children_subtests_count (void) const noexcept;

359

367 [[nodiscard]] class reporter&

368 reporter (void) const noexcept;

369

377 [[noreturn]] void

378 abort (const reflection::source_location& sl

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

380

388 [[nodiscard]] class runner&

389 runner (void) const noexcept;

390

391 protected:

402 void

403 after_subtest_create_ (std::unique_ptr<subtest> child_test,

404 suite& suite);

405

406 protected:

410 class runner& runner_;

411

415 size_t own_index_;

416

426 size_t current_subtest_index_ = 0;

427

436 std::vector<std::unique_ptr<subtest>> children_subtests_;

437 };

438

439 // ========================================================================

440

451 template <typename Self_T>

452 class runnable : public detail::runnable_base

453 {

454 public:

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

469 runnable (const char* name, class runner& runner, size_t own_index,

470 Callable_T&& callable, Args_T&&... arguments);

471

475 runnable (const runnable&) = delete;

476

480 runnable (runnable&&) = delete;

481

485 runnable&

486 operator=(const runnable&)

487 = delete;

488

492 runnable&

493 operator=(runnable&&)

494 = delete;

495

499 virtual ~runnable () override;

500

501 // ----------------------------------------------------------------------

502

512 virtual void

513 run (void)

514 = 0;

515

516 protected:

521 std::function<void (Self_T&)> callable_;

522 };

523

524 // ------------------------------------------------------------------------

525 } // namespace detail

526

527 // ==========================================================================

528

550 class subtest : public detail::runnable<subtest>

551 {

552 public:

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

572 subtest (const char* name, class runner& runner, suite& parent_suite,

573 size_t own_index, size_t nesting_depth, Callable_T&& callable,

574 Args_T&&... arguments);

575

579 subtest (const subtest&) = delete;

580

584 subtest (subtest&&) = delete;

585

589 subtest&

590 operator= (const subtest&)

591 = delete;

592

596 subtest&

597 operator= (subtest&&)

598 = delete;

599

603 virtual ~subtest () override;

604

605 // ------------------------------------------------------------------------

606

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

620 void

621 test (const char* name, Callable_T&& callable, Args_T&&... arguments);

622

623 // ------------------------------------------------------------------------

624

639 template <class Expr_T>

640 requires type_traits::checkable<Expr_T>

641 auto

642 expect (const Expr_T& expr, const reflection::source_location& sl

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

644

659 template <class Expr_T>

660 requires type_traits::checkable<Expr_T>

661 auto

662 assume (const Expr_T& expr, const reflection::source_location& sl

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

664

665 // ------------------------------------------------------------------------

666

675 virtual void

676 run (void) override;

677

685 [[nodiscard]] size_t

686 nesting_depth () const noexcept;

687

688 protected:

692 suite& parent_suite_;

693

697 size_t nesting_depth_;

698 };

699

700 // ==========================================================================

701

722 class suite : public detail::runnable<suite>

723 {

724 public:

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

740 suite (const char* name, class runner& runner, Callable_T&& callable,

741 Args_T&&... arguments);

742

746 suite (const suite&) = delete;

747

751 suite (suite&&) = delete;

752

756 suite&

757 operator= (const suite&)

758 = delete;

759

763 suite&

764 operator= (suite&&)

765 = delete;

766

770 virtual ~suite () override;

771

772 // ------------------------------------------------------------------------

773

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

787 void

788 test (const char* name, Callable_T&& callable, Args_T&&... arguments);

789

790 // ------------------------------------------------------------------------

791

799 [[nodiscard]] detail::timestamps&

800 timings () noexcept;

801

809 [[nodiscard]] const detail::timestamps&

810 timings () const noexcept;

811

820 virtual void

821 run (void) override;

822

823 protected:

827 detail::timestamps timings_;

828 };

829

830 // ==========================================================================

831

847 class top_suite : public suite

848 {

849 public:

850 // Expose the accessor for the suite name from the base test_node class,

851 // since the top_suite may need to change its name after construction, and

852 // the base class provides the necessary interface for that purpose.

853 using detail::test_node::name;

854

861 top_suite (const char* name, class runner& runner);

862

866 top_suite (const top_suite&) = delete;

867

871 top_suite (top_suite&&) = delete;

872

876 top_suite&

877 operator= (const top_suite&)

878 = delete;

879

883 top_suite&

884 operator= (top_suite&&)

885 = delete;

886

890 virtual ~top_suite () override;

891

897 void

898 name (const char* new_name) noexcept;

899 };

900

901 // ==========================================================================

902

932 class static_suite : public suite

933 {

934 public:

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

949 static_suite (const char* name, static_runner& runner,

950 Callable_T&& callable, Args_T&&... arguments);

951

955 static_suite (const static_suite&) = delete;

956

960 static_suite (static_suite&&) = delete;

961

965 static_suite&

966 operator= (const static_suite&)

967 = delete;

968

972 static_suite&

973 operator= (static_suite&&)

974 = delete;

975

979 virtual ~static_suite () override;

980

981 // ------------------------------------------------------------------------

982

991 virtual void

992 run (void) override;

993

994 protected:

999 std::function<void (static_suite&)> static_callable_;

1000 };

1001

1002 // --------------------------------------------------------------------------

1003} // namespace micro_os_plus::micro_test_plus

1004

1005#if defined(__GNUC__)

1006#pragma GCC diagnostic pop

1007#endif // defined(__GNUC__)

1008

1009// ----------------------------------------------------------------------------

1010

1011#endif // defined(__cplusplus)

1012

1013// ============================================================================

1014// Templates, inlines & constexpr implementations.

1015

1016#include "inlines/test-inlines.h"

1017

1018// ----------------------------------------------------------------------------

1019

1020#endif // MICRO_OS_PLUS_MICRO_TEST_PLUS_TEST_H_

1021

1022// ----------------------------------------------------------------------------

---

Generated via doxygen2docusaurus 2.2.2 by Doxygen 1.17.0.