test.h File

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

Included Headers

#include <functional> #include <memory> #include "runner-totals.h" #include "type-traits.h" #include "timings.h" #include "reflection.h" #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 122 of file test.h, definition at line 93 of file runner.cpp.

93 detail::register_static_suite (static_runner& static_runner_ref,

94 static_suite& static_suite_ref)

95 {

96 static_runner::register_static_suite (static_runner_ref, static_suite_ref);

97 }

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

Referenced by micro_os_plus::micro_test_plus::static_suite::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 109 of file test.h, definition at line 81 of file runner.cpp.

81 detail::to_runner (static_runner& static_runner_ref) noexcept

82 {

83 return static_cast<runner&> (static_runner_ref);

84 }

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_TEST_PLUS_TEST_H_

49#define MICRO_TEST_PLUS_TEST_H_

50

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

52

53#ifdef __cplusplus

54

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

56

57#include <functional>

58#include <memory>

59

60#include "runner-totals.h"

61#include "type-traits.h"

62#include "timings.h"

63#include "reflection.h"

64

65// ----------------------------------------------------------------------------

66

67#if defined(__GNUC__)

68#pragma GCC diagnostic push

69#pragma GCC diagnostic ignored "-Wpadded"

70#if defined(__clang__)

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

72#else // GCC only

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

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

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

76#endif

77#endif

78

79// =============================================================================

80

81namespace micro_os_plus::micro_test_plus

82{

83 // --------------------------------------------------------------------------

84

85 class runner;

86 class static_runner;

87 class reporter;

88 class runner_totals;

89 class subtest;

90 class suite;

91 class static_suite;

92

93 namespace detail

94 {

95 // ========================================================================

96

108 runner&

109 to_runner (static_runner& static_runner_ref) noexcept;

110

121 void

122 register_static_suite (static_runner& static_runner_ref,

123 static_suite& static_suite_ref);

124

145 class test_node

146 {

147 public:

153 test_node (const char* name);

154

158 test_node (const test_node&) = delete;

159

163 test_node (test_node&&) = delete;

164

168 test_node&

169 operator=(const test_node&)

170 = delete;

171

175 test_node&

176 operator=(test_node&&)

177 = delete;

178

182 virtual ~test_node ();

183

184 // ----------------------------------------------------------------------

185

193 [[nodiscard]] const char*

194 name (void) const noexcept;

195

196 public:

204 [[nodiscard]] runner_totals&

205 totals () noexcept;

206

214 [[nodiscard]] const runner_totals&

215 totals () const noexcept;

216

217 protected:

224 const char* name_;

225

229 runner_totals totals_;

230 };

231

232 // ========================================================================

233

253 class runnable_base : public test_node

254 {

255 public:

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

265

269 runnable_base (const runnable_base&) = delete;

270

274 runnable_base (runnable_base&&) = delete;

275

279 runnable_base&

280 operator=(const runnable_base&)

281 = delete;

282

286 runnable_base&

287 operator=(runnable_base&&)

288 = delete;

289

293 virtual ~runnable_base () override;

294

295 // ----------------------------------------------------------------------

296

304 [[nodiscard]] size_t

305 own_index () const noexcept;

306

318 void

319 own_index (size_t index) noexcept;

320

328 [[nodiscard]] size_t

329 current_subtest_index () const noexcept;

330

338 size_t

339 increment_subtest_index () noexcept;

340

348 [[nodiscard]] size_t

349 children_subtests_count (void) const noexcept;

350

358 [[nodiscard]] class reporter&

359 reporter (void) const noexcept;

360

368 [[noreturn]] void

369 abort (const reflection::source_location& sl

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

371

379 [[nodiscard]] class runner&

380 runner (void) const noexcept;

381

382 protected:

393 void

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

395 suite& suite);

396

397 protected:

401 class runner& runner_;

402

406 size_t own_index_;

407

417 size_t current_subtest_index_ = 0;

418

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

428 };

429

430 // ========================================================================

431

442 template <typename Self_T>

443 class runnable : public detail::runnable_base

444 {

445 public:

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

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

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

462

466 runnable (const runnable&) = delete;

467

471 runnable (runnable&&) = delete;

472

476 runnable&

477 operator=(const runnable&)

478 = delete;

479

483 runnable&

484 operator=(runnable&&)

485 = delete;

486

490 virtual ~runnable () override;

491

492 // ----------------------------------------------------------------------

493

503 virtual void

504 run (void)

505 = 0;

506

507 protected:

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

513 };

514

515 // ------------------------------------------------------------------------

516 } // namespace detail

517

518 // ==========================================================================

519

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

542 {

543 public:

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

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

564 size_t own_index, size_t nesting_depth, Callable_T&& callable,

565 Args_T&&... arguments);

566

570 subtest (const subtest&) = delete;

571

575 subtest (subtest&&) = delete;

576

580 subtest&

581 operator= (const subtest&)

582 = delete;

583

587 subtest&

588 operator= (subtest&&)

589 = delete;

590

594 virtual ~subtest () override;

595

596 // ------------------------------------------------------------------------

597

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

611 void

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

613

614 // ------------------------------------------------------------------------

615

630 template <class Expr_T>

631 requires type_traits::checkable<Expr_T>

632 auto

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

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

635

650 template <class Expr_T>

651 requires type_traits::checkable<Expr_T>

652 auto

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

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

655

656 // ------------------------------------------------------------------------

657

666 virtual void

667 run (void) override;

668

676 [[nodiscard]] size_t

677 nesting_depth () const noexcept;

678

679 protected:

683 suite& parent_suite_;

684

688 size_t nesting_depth_;

689 };

690

691 // ==========================================================================

692

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

714 {

715 public:

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

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

732 Args_T&&... arguments);

733

737 suite (const suite&) = delete;

738

742 suite (suite&&) = delete;

743

747 suite&

748 operator= (const suite&)

749 = delete;

750

754 suite&

755 operator= (suite&&)

756 = delete;

757

761 virtual ~suite () override;

762

763 // ------------------------------------------------------------------------

764

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

778 void

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

780

781 // ------------------------------------------------------------------------

782

790 [[nodiscard]] detail::timestamps&

791 timings () noexcept;

792

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

801 timings () const noexcept;

802

811 virtual void

812 run (void) override;

813

814 protected:

818 detail::timestamps timings_;

819 };

820

821 // ==========================================================================

822

838 class top_suite : public suite

839 {

840 public:

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

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

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

844 using detail::test_node::name;

845

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

853

857 top_suite (const top_suite&) = delete;

858

862 top_suite (top_suite&&) = delete;

863

867 top_suite&

868 operator= (const top_suite&)

869 = delete;

870

874 top_suite&

875 operator= (top_suite&&)

876 = delete;

877

881 virtual ~top_suite () override;

882

888 void

889 name (const char* new_name) noexcept;

890 };

891

892 // ==========================================================================

893

923 class static_suite : public suite

924 {

925 public:

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

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

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

942

946 static_suite (const static_suite&) = delete;

947

951 static_suite (static_suite&&) = delete;

952

956 static_suite&

957 operator= (const static_suite&)

958 = delete;

959

963 static_suite&

964 operator= (static_suite&&)

965 = delete;

966

970 virtual ~static_suite () override;

971

972 // ------------------------------------------------------------------------

973

982 virtual void

983 run (void) override;

984

985 protected:

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

991 };

992

993 // --------------------------------------------------------------------------

994} // namespace micro_os_plus::micro_test_plus

995

996#if defined(__GNUC__)

997#pragma GCC diagnostic pop

998#endif

999

1000// ----------------------------------------------------------------------------

1001

1002#endif // __cplusplus

1003

1004// ============================================================================

1005// Templates & constexpr implementations.

1006

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

1008

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

1010

1011#endif // MICRO_TEST_PLUS_TEST_H_

1012

1013// ----------------------------------------------------------------------------

---

Generated via doxygen2docusaurus 2.2.0 by Doxygen 1.17.0.