@micro-os-plus/micro-test-plus 3.3.0 → 4.0.0

package/include/micro-os-plus/micro-test-plus/inlines/test-inlines.h

@@ -0,0 +1,369 @@
+/*
+ * This file is part of the µOS++ project (https://micro-os-plus.github.io/).
+ * Copyright (c) 2021-2026 Liviu Ionescu. All rights reserved.
+ *
+ * Permission to use, copy, modify, and/or distribute this software for any
+ * purpose is hereby granted, under the terms of the MIT license.
+ *
+ * If a copy of the license was not distributed with this file, it can be
+ * obtained from https://opensource.org/licenses/mit.
+ *
+ * Major parts of the code are inspired from v1.1.8 of the Boost UT project,
+ * released under the terms of the Boost Version 1.0 Software License,
+ * which can be obtained from https://www.boost.org/LICENSE_1_0.txt.
+ */
+
+// ----------------------------------------------------------------------------
+
+/**
+ * @file
+ * @brief C++ header file with inline implementations for the µTest++ test
+ * suite.
+ *
+ * @details
+ * This header provides the inline implementations for the test suite
+ * facilities used within the µTest++ framework. It defines the logic for
+ * constructing and registering test suites, including the binding of callable
+ * objects and their arguments for flexible test suite definitions.
+ *
+ * The implementation ensures that each test suite is automatically registered
+ * with the global test runner upon construction, enabling automated discovery
+ * and execution of test suites. The use of `std::bind` allows for versatile
+ * test suite initialisation with arbitrary callable types and arguments.
+ *
+ * All definitions reside within the `micro_os_plus::micro_test_plus`
+ * namespace, maintaining a 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.
+ */
+
+#ifndef MICRO_TEST_PLUS_TEST_INLINES_H_
+#define MICRO_TEST_PLUS_TEST_INLINES_H_
+
+// ----------------------------------------------------------------------------
+
+#ifdef __cplusplus
+
+// ----------------------------------------------------------------------------
+
+#include <cstdio>
+#include <cstring>
+
+// ----------------------------------------------------------------------------
+
+#if defined(__GNUC__)
+#pragma GCC diagnostic push
+#pragma GCC diagnostic ignored "-Waggregate-return"
+#if defined(__clang__)
+#pragma clang diagnostic ignored "-Wc++98-compat"
+#pragma clang diagnostic ignored "-Wc++98-compat-pedantic"
+#else // GCC only
+#endif
+#endif
+
+// ============================================================================
+
+namespace micro_os_plus::micro_test_plus
+{
+  // ==========================================================================
+
+  /**
+   * @details
+   * Binds the callable and its arguments into the stored `callable_` function
+   * object. When `run()` is called, the stored function is invoked with a
+   * reference to the derived `Self_T` instance as its first argument,
+   * followed by the bound arguments.
+   */
+  template <typename Self_T>
+  template <typename Callable_T, typename... Args_T>
+  runnable<Self_T>::runnable (const char* name, class runner& runner,
+                              size_t own_index, Callable_T&& callable,
+                              Args_T&&... arguments)
+      : runnable_base{ name, runner, own_index }
+  {
+    // When there are no extra arguments the callable already has the signature
+    // void(Self_T&), so store it directly. Only use std::bind when additional
+    // arguments must be pre-bound, to avoid triggering a GCC ARM bug in
+    // __is_nothrow_invocable<_Bind<...>, Self_T&> (GCC 15.2.1).
+    if constexpr (sizeof...(arguments) == 0)
+      {
+        callable_ = std::forward<Callable_T> (callable);
+      }
+    else
+      {
+        callable_ = std::bind (std::forward<Callable_T> (callable),
+                               std::placeholders::_1,
+                               std::forward<Args_T> (arguments)...);
+      }
+
+#if defined(MICRO_OS_PLUS_TRACE) \
+    && defined(MICRO_OS_PLUS_TRACE_MICRO_TEST_PLUS_CONSTRUCTORS)
+#if defined(__GNUC__)
+#pragma GCC diagnostic push
+#if defined(__clang__)
+#pragma clang diagnostic ignored "-Wunsafe-buffer-usage-in-libc-call"
+#endif
+#endif
+    trace::printf ("%s '%s' %zu\n", __PRETTY_FUNCTION__, name, own_index_);
+#if defined(__GNUC__)
+#pragma GCC diagnostic pop
+#endif
+#endif // MICRO_OS_PLUS_TRACE_MICRO_TEST_PLUS_CONSTRUCTORS
+  }
+
+  /**
+   * @details
+   * No-op in production builds. When tracing is enabled via
+   * `MICRO_OS_PLUS_TRACE_MICRO_TEST_PLUS_CONSTRUCTORS`, emits a trace
+   * message identifying the instance being destroyed.
+   */
+  template <typename Self_T>
+  runnable<Self_T>::~runnable ()
+  {
+#if defined(MICRO_OS_PLUS_TRACE) \
+    && defined(MICRO_OS_PLUS_TRACE_MICRO_TEST_PLUS_CONSTRUCTORS)
+#if defined(__GNUC__)
+#pragma GCC diagnostic push
+#if defined(__clang__)
+#pragma clang diagnostic ignored "-Wunsafe-buffer-usage-in-libc-call"
+#endif
+#endif
+    trace::printf ("%s '%s'\n", __PRETTY_FUNCTION__, name_);
+#if defined(__GNUC__)
+#pragma GCC diagnostic pop
+#endif
+#endif // MICRO_OS_PLUS_TRACE_MICRO_TEST_PLUS_CONSTRUCTORS
+  }
+
+  // ==========================================================================
+
+  /**
+   * @details
+   * Delegates to `runnable`, which binds the callable with
+   * its arguments.
+   */
+  template <typename Callable_T, typename... Args_T>
+  subtest::subtest (const char* name, class runner& runner,
+                    suite& parent_suite, size_t own_index,
+                    size_t nesting_depth, Callable_T&& callable,
+                    Args_T&&... arguments)
+      : runnable<subtest>{ name, runner, own_index,
+                           std::forward<Callable_T> (callable),
+                           std::forward<Args_T> (arguments)... },
+        parent_suite_{ parent_suite }, nesting_depth_{ nesting_depth }
+  {
+#if defined(MICRO_OS_PLUS_TRACE) \
+    && defined(MICRO_OS_PLUS_TRACE_MICRO_TEST_PLUS_CONSTRUCTORS)
+#if defined(__GNUC__)
+#pragma GCC diagnostic push
+#if defined(__clang__)
+#pragma clang diagnostic ignored "-Wunsafe-buffer-usage-in-libc-call"
+#endif
+#endif
+    trace::printf ("%s '%s' %zu %zu\n", __PRETTY_FUNCTION__, name, own_index_,
+                   nesting_depth_);
+#if defined(__GNUC__)
+#pragma GCC diagnostic pop
+#endif
+#endif // MICRO_OS_PLUS_TRACE_MICRO_TEST_PLUS_CONSTRUCTORS
+  }
+
+  /**
+   * @details
+   * Allocates a child `subtest` on the heap, incrementing the subtest index
+   * and deepening the nesting level by one relative to this subtest's depth,
+   * then transfers ownership to the framework via `after_subtest_create_()`.
+   */
+  template <typename Callable_T, typename... Args_T>
+  void
+  subtest::test (const char* name, Callable_T&& callable,
+                 Args_T&&... arguments)
+  {
+#if defined(MICRO_OS_PLUS_TRACE) \
+    && defined(MICRO_OS_PLUS_TRACE_MICRO_TEST_PLUS)
+#if defined(__GNUC__)
+#pragma GCC diagnostic push
+#if defined(__clang__)
+#pragma clang diagnostic ignored "-Wunsafe-buffer-usage-in-libc-call"
+#endif
+#endif
+    trace::printf ("%s '%s'\n", __PRETTY_FUNCTION__, name);
+#if defined(__GNUC__)
+#pragma GCC diagnostic pop
+#endif
+#endif // MICRO_OS_PLUS_TRACE_MICRO_TEST_PLUS
+
+    size_t own_index = increment_subtest_index ();
+    auto child_subtest = std::make_unique<subtest> (
+        name, runner (), parent_suite_, own_index, nesting_depth_ + 1,
+        std::forward<Callable_T> (callable),
+        std::forward<Args_T> (arguments)...);
+
+    after_subtest_create_ (std::move (child_subtest), parent_suite_);
+  }
+
+  // ==========================================================================
+
+  /**
+   * @details
+   * Delegates to `runnable`, which binds the callable with
+   * its arguments. After construction, the suite is registered with the
+   * static test runner.
+   */
+  template <typename Callable_T, typename... Args_T>
+  suite::suite (const char* name, class runner& runner, Callable_T&& callable,
+                Args_T&&... arguments)
+      : runnable<suite>{ name, runner, 0, std::forward<Callable_T> (callable),
+                         std::forward<Args_T> (arguments)... }
+  {
+#if defined(MICRO_OS_PLUS_TRACE) \
+    && defined(MICRO_OS_PLUS_TRACE_MICRO_TEST_PLUS_CONSTRUCTORS)
+#if defined(__GNUC__)
+#pragma GCC diagnostic push
+#if defined(__clang__)
+#pragma clang diagnostic ignored "-Wunsafe-buffer-usage-in-libc-call"
+#endif
+#endif
+    trace::printf ("%s '%s' %zu\n", __PRETTY_FUNCTION__, name, own_index_);
+#if defined(__GNUC__)
+#pragma GCC diagnostic pop
+#endif
+#endif // MICRO_OS_PLUS_TRACE_MICRO_TEST_PLUS_CONSTRUCTORS
+  }
+
+#if defined(__GNUC__)
+#pragma GCC diagnostic push
+#if defined(__clang__)
+#pragma clang diagnostic ignored "-Wdocumentation"
+#endif
+#endif
+  /**
+   * @details
+   * The `test` function template registers and executes a test case
+   * within the µTest++ framework. It accepts a descriptive name, a callable
+   * object (such as a lambda or function pointer), and an optional list of
+   * arguments to be passed to the callable. The test case is reported using
+   * the provided name, and its execution is managed by the framework's test
+   * runner.
+   *
+   * Each test case typically involves evaluating a logical expression, such as
+   * comparing a computed result to an expected value. For C++ projects, it is
+   * also possible to verify whether evaluating an expression throws
+   * exceptions. Each test either succeeds or fails, and for expectations, the
+   * test runner maintains counts of successful and failed checks.
+   *
+   * This function template enables flexible and expressive test case
+   * definitions, supporting both parameterised and non-parameterised tests. It
+   * is typically invoked at global scope or within test suite definitions to
+   * ensure automatic registration and execution.
+   *
+   * A test case is characterised by a name, a function that performs the
+   * checks, and optionally, arguments to be passed to that function. The
+   * implementation of `test` invokes the provided function with the given
+   * arguments and reports the results to the test runner.
+   *
+   * @par Example
+   *
+   * @code{.cpp}
+   *   namespace mt = micro_os_plus::micro_test_plus;
+   *
+   *   ts.test ("Check answer with comparator", [] (auto& t) {
+   *     t.expect (mt::eq (compute_answer (), 42)) << "answer is 42";
+   *   });
+   * @endcode
+   */
+#if defined(__GNUC__)
+#pragma GCC diagnostic pop
+#endif
+  template <typename Callable_T, typename... Args_T>
+  void
+  suite::test (const char* name, Callable_T&& callable, Args_T&&... arguments)
+  {
+#if defined(MICRO_OS_PLUS_TRACE) \
+    && defined(MICRO_OS_PLUS_TRACE_MICRO_TEST_PLUS)
+#if defined(__GNUC__)
+#pragma GCC diagnostic push
+#if defined(__clang__)
+#pragma clang diagnostic ignored "-Wunsafe-buffer-usage-in-libc-call"
+#endif
+#endif
+    trace::printf ("%s '%s'\n", __PRETTY_FUNCTION__, name);
+#if defined(__GNUC__)
+#pragma GCC diagnostic pop
+#endif
+#endif // MICRO_OS_PLUS_TRACE_MICRO_TEST_PLUS
+
+    size_t own_index = increment_subtest_index ();
+    auto child_subtest
+        = std::make_unique<subtest> (name, runner (), *this, own_index, 1,
+                                     std::forward<Callable_T> (callable),
+                                     std::forward<Args_T> (arguments)...);
+
+    after_subtest_create_ (std::move (child_subtest), *this);
+  }
+
+  // ==========================================================================
+
+  /**
+   * @details
+   * Delegates to `runnable`, which binds the callable with
+   * its arguments. After construction, the suite is registered with the
+   * static test runner.
+   */
+  template <typename Callable_T, typename... Args_T>
+  static_suite::static_suite (const char* name, static_runner& runner,
+                              Callable_T&& callable, Args_T&&... arguments)
+      // The nullptr passed to the base constructor is an optimisation to save
+      // some space, since this callble is not used by the static runner.
+      : suite{ name, runner, nullptr }
+  {
+    if constexpr (sizeof...(arguments) == 0)
+      {
+        static_callable_ = std::forward<Callable_T> (callable);
+      }
+    else
+      {
+        static_callable_ = std::bind (std::forward<Callable_T> (callable),
+                                      std::placeholders::_1,
+                                      std::forward<Args_T> (arguments)...);
+      }
+
+#if defined(MICRO_OS_PLUS_TRACE) \
+    && defined(MICRO_OS_PLUS_TRACE_MICRO_TEST_PLUS_CONSTRUCTORS)
+#if defined(__GNUC__)
+#pragma GCC diagnostic push
+#if defined(__clang__)
+#pragma clang diagnostic ignored "-Wunsafe-buffer-usage-in-libc-call"
+#endif
+#endif
+    trace::printf ("%s '%s' %zu\n", __PRETTY_FUNCTION__, name, own_index_);
+#if defined(__GNUC__)
+#pragma GCC diagnostic pop
+#endif
+#endif // MICRO_OS_PLUS_TRACE_MICRO_TEST_PLUS_CONSTRUCTORS
+
+    static_runner::register_static_suite (runner, *this);
+  }
+
+  // --------------------------------------------------------------------------
+} // namespace micro_os_plus::micro_test_plus
+
+#if defined(__GNUC__)
+#pragma GCC diagnostic pop
+#endif
+
+// ----------------------------------------------------------------------------
+
+#endif // __cplusplus
+
+// ----------------------------------------------------------------------------
+
+#endif // MICRO_TEST_PLUS_TEST_INLINES_H_
+
+// ----------------------------------------------------------------------------

package/include/micro-os-plus/micro-test-plus/inlines/utility-inlines.h

@@ -0,0 +1,126 @@
+/*
+ * This file is part of the µOS++ project (https://micro-os-plus.github.io/).
+ * Copyright (c) 2021-2026 Liviu Ionescu. All rights reserved.
+ *
+ * Permission to use, copy, modify, and/or distribute this software for any
+ * purpose is hereby granted, under the terms of the MIT license.
+ *
+ * If a copy of the license was not distributed with this file, it can be
+ * obtained from https://opensource.org/licenses/mit.
+ *
+ * Major parts of the code are inspired from v1.1.8 of the Boost UT project,
+ * released under the terms of the Boost Version 1.0 Software License,
+ * which can be obtained from https://www.boost.org/LICENSE_1_0.txt.
+ */
+
+// ----------------------------------------------------------------------------
+
+/**
+ * @file
+ * @brief C++ header file with inline implementations for the µTest++ utility
+ * functions.
+ *
+ * @details
+ * This header provides the inline implementations for the utility function
+ * templates used within the µTest++ framework. It defines the logic for
+ * splitting strings into substrings using a specified delimiter, enabling
+ * convenient and type-safe string parsing in test expressions.
+ *
+ * All definitions reside within the
+ * `micro_os_plus::micro_test_plus::utility` 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.
+ */
+
+#ifndef MICRO_TEST_PLUS_UTILITY_INLINES_H_
+#define MICRO_TEST_PLUS_UTILITY_INLINES_H_
+
+// ----------------------------------------------------------------------------
+
+#ifdef __cplusplus
+
+// ----------------------------------------------------------------------------
+
+#if defined(__GNUC__)
+#pragma GCC diagnostic push
+#pragma GCC diagnostic ignored "-Waggregate-return"
+#if defined(__clang__)
+#pragma clang diagnostic ignored "-Wc++98-compat"
+#endif
+#endif
+
+// ============================================================================
+
+namespace micro_os_plus::micro_test_plus
+{
+  // --------------------------------------------------------------------------
+  namespace utility
+  {
+    /**
+     * @details
+     * This function template facilitates string handling in tests by splitting
+     * a string into a vector of substrings, using the specified delimiter.
+     *
+     * The function iterates through the input string, identifying delimiter
+     * positions and extracting substrings between them. Each resulting
+     * substring is added to the output vector. This approach supports flexible
+     * parsing of delimited data, which is particularly useful for validating
+     * string processing logic in test cases.
+     *
+     * **Example**
+     *
+     * @code{.cpp}
+     * namespace mt = micro_os_plus::micro_test_plus;
+     *
+     * t.expect (std::vector<std::string_view>{ "a", "b" }
+     *             == mt::utility::split<std::string_view> ("a.b", "."))
+     *         << "a.b splits into [a,b]";
+     * @endcode
+     */
+    template <class T = std::string_view, class Delim_T>
+    [[nodiscard]] auto
+    split (T input, Delim_T delim) -> std::vector<T>
+    {
+      std::vector<T> output{};
+      std::size_t first{};
+      while (first < std::size (input))
+        {
+          const auto second = input.find_first_of (delim, first);
+          if (first != second)
+            {
+              output.emplace_back (input.substr (first, second - first));
+            }
+          if (second == T::npos)
+            {
+              break;
+            }
+          first = second + 1;
+        }
+      return output;
+    }
+
+    // ------------------------------------------------------------------------
+  } // namespace utility
+
+  // --------------------------------------------------------------------------
+} // namespace micro_os_plus::micro_test_plus
+
+#if defined(__GNUC__)
+#pragma GCC diagnostic pop
+#endif
+
+// ----------------------------------------------------------------------------
+
+#endif // __cplusplus
+
+// ----------------------------------------------------------------------------
+
+#endif // MICRO_TEST_PLUS_UTILITY_INLINES_H_
+
+// ----------------------------------------------------------------------------

package/include/micro-os-plus/micro-test-plus/literals.h

@@ -74,6 +74,8 @@
 #endif
 #endif
 
+// =============================================================================
+
 namespace micro_os_plus::micro_test_plus
 {
   // --------------------------------------------------------------------------
@@ -324,7 +326,6 @@ namespace micro_os_plus::micro_test_plus
      *
      * @return A `type_traits::integral_constant` instance holding the parsed
      * `uint8_t` value.
-     * and reporting mechanisms.
      */
     template <char... Cs>
     [[nodiscard]] constexpr auto
@@ -675,8 +676,8 @@ namespace micro_os_plus::micro_test_plus
    *
    * @code
    * int x = 42;
-   * auto wrapped = to_i{x}; // Explicitly treat x as an int for test
-   * comparison
+   * // Explicitly treat x as an int for test comparison.
+   * auto wrapped = to_i{x};
    * @endcode
    *
    * @since 3.2.0

package/include/micro-os-plus/micro-test-plus/math.h

@@ -64,9 +64,12 @@
 #pragma GCC diagnostic ignored "-Wconversion"
 #if defined(__clang__)
 #pragma clang diagnostic ignored "-Wc++98-compat"
+#pragma clang diagnostic ignored "-Wc++20-compat"
 #endif
 #endif
 
+// ============================================================================
+
 namespace micro_os_plus::micro_test_plus
 {
   // --------------------------------------------------------------------------
@@ -103,7 +106,7 @@ namespace micro_os_plus::micro_test_plus
      */
     template <class T>
     [[nodiscard]] constexpr auto
-    abs (const T t) -> T;
+    abs (const T t) noexcept -> T;
 
     /**
      * @brief Computes the minimum of two comparable values.
@@ -117,7 +120,7 @@ namespace micro_os_plus::micro_test_plus
      */
     template <class T>
     [[nodiscard]] constexpr auto
-    min_value (const T& lhs, const T& rhs) -> const T&;
+    min_value (const T& lhs, const T& rhs) noexcept -> const T&;
 
     /**
      * @brief Generic exponentiation function to compute the power of a base
@@ -134,7 +137,7 @@ namespace micro_os_plus::micro_test_plus
      */
     template <class T, class Exp_T>
     [[nodiscard]] constexpr auto
-    pow (const T base, const Exp_T exp) -> T;
+    pow (const T base, const Exp_T exp) noexcept -> T;
 
     /**
      * @brief Computes the integral value of a number represented as an array
@@ -148,7 +151,7 @@ namespace micro_os_plus::micro_test_plus
      * @return The parsed integral value of type \c T.
      */
     template <class T, char... Cs>
-    [[nodiscard]] constexpr auto
+    [[nodiscard]] consteval auto
     num (void) -> T;
 
     /**
@@ -163,7 +166,7 @@ namespace micro_os_plus::micro_test_plus
      * @return The parsed decimal part as an integral value of type \c T.
      */
     template <class T, char... Cs>
-    [[nodiscard]] constexpr auto
+    [[nodiscard]] consteval auto
     den (void) -> T;
 
     /**
@@ -178,7 +181,7 @@ namespace micro_os_plus::micro_test_plus
      * @return The number of decimal places as a value of type \c T.
      */
     template <class T, char... Cs>
-    [[nodiscard]] constexpr auto
+    [[nodiscard]] consteval auto
     den_size (void) -> T;
 
     /**