@micro-os-plus/micro-test-plus 3.1.1 → 3.2.0

package/include/micro-os-plus/detail.h

@@ -41,12 +41,13 @@ namespace micro_os_plus::micro_test_plus
   // --------------------------------------------------------------------------
 
   /**
-   * @brief Implementation details, not part of the public API.
+   * @brief Namespace with implementation details, not part of the public API.
    */
   namespace detail
   {
     /**
      * @brief An object used to pass assertion parameters to the evaluator.
+     * @headerfile micro-test-plus.h <micro-os-plus/micro-test-plus.h>
      */
     template <class Expr_T>
     struct assertion
@@ -87,7 +88,7 @@ namespace micro_os_plus::micro_test_plus
     [[nodiscard]] constexpr auto
     get (const T& t)
     {
-      // Call the variadic function, besically to force it return `t`.
+      // Call the variadic function, basically to force it return `t`.
       return get_impl (t, 0);
     }
 
@@ -95,6 +96,7 @@ namespace micro_os_plus::micro_test_plus
 
     /**
      * @brief Equality comparator.
+     * @headerfile micro-test-plus.h <micro-os-plus/micro-test-plus.h>
      */
     template <class Lhs_T, class Rhs_T>
     struct eq_ : type_traits::op
@@ -117,16 +119,15 @@ namespace micro_os_plus::micro_test_plus
 #pragma clang diagnostic ignored "-Wpedantic"
 #endif
 #endif
-              if constexpr (type_traits::has_value_v<
-                                Lhs_T> and type_traits::has_value_v<Rhs_T>)
+              if constexpr (type_traits::has_value_v<Lhs_T>
+                            and type_traits::has_value_v<Rhs_T>)
                 {
                   // If both types have values (like numeric constants),
                   // compare them directly.
                   return Lhs_T::value == Rhs_T::value;
                 }
-              else if constexpr (
-                  type_traits::has_epsilon_v<
-                      Lhs_T> and type_traits::has_epsilon_v<Rhs_T>)
+              else if constexpr (type_traits::has_epsilon_v<Lhs_T>
+                                 and type_traits::has_epsilon_v<Rhs_T>)
                 {
                   // If both values have precision, compare them using
                   // the smalles precision.
@@ -156,7 +157,8 @@ namespace micro_os_plus::micro_test_plus
       {
       }
 
-      [[nodiscard]] constexpr operator bool () const
+      [[nodiscard]] constexpr
+      operator bool () const
       {
         return value_;
       }
@@ -180,6 +182,7 @@ namespace micro_os_plus::micro_test_plus
 
     /**
      * @brief Non-equality comparator.
+     * @headerfile micro-test-plus.h <micro-os-plus/micro-test-plus.h>
      */
     template <class Lhs_T, class Rhs_T>
     struct ne_ : type_traits::op
@@ -201,14 +204,13 @@ namespace micro_os_plus::micro_test_plus
 #pragma clang diagnostic ignored "-Wpedantic"
 #endif
 #endif
-              if constexpr (type_traits::has_value_v<
-                                Lhs_T> and type_traits::has_value_v<Rhs_T>)
+              if constexpr (type_traits::has_value_v<Lhs_T>
+                            and type_traits::has_value_v<Rhs_T>)
                 {
                   return Lhs_T::value != Rhs_T::value;
                 }
-              else if constexpr (
-                  type_traits::has_epsilon_v<
-                      Lhs_T> and type_traits::has_epsilon_v<Rhs_T>)
+              else if constexpr (type_traits::has_epsilon_v<Lhs_T>
+                                 and type_traits::has_epsilon_v<Rhs_T>)
                 {
                   return math::abs (get (lhs_) - get (rhs_))
                          > math::min_value (Lhs_T::epsilon, Rhs_T::epsilon);
@@ -232,7 +234,8 @@ namespace micro_os_plus::micro_test_plus
       {
       }
 
-      [[nodiscard]] constexpr operator bool () const
+      [[nodiscard]] constexpr
+      operator bool () const
       {
         return value_;
       }
@@ -254,6 +257,7 @@ namespace micro_os_plus::micro_test_plus
 
     /**
      * @brief Greater than comparator.
+     * @headerfile micro-test-plus.h <micro-os-plus/micro-test-plus.h>
      */
     template <class Lhs_T, class Rhs_T>
     struct gt_ : type_traits::op
@@ -272,8 +276,8 @@ namespace micro_os_plus::micro_test_plus
 #pragma clang diagnostic ignored "-Wpedantic"
 #endif
 #endif
-              if constexpr (type_traits::has_value_v<
-                                Lhs_T> and type_traits::has_value_v<Rhs_T>)
+              if constexpr (type_traits::has_value_v<Lhs_T>
+                            and type_traits::has_value_v<Rhs_T>)
                 {
                   return Lhs_T::value > Rhs_T::value;
                 }
@@ -288,7 +292,8 @@ namespace micro_os_plus::micro_test_plus
       {
       }
 
-      [[nodiscard]] constexpr operator bool () const
+      [[nodiscard]] constexpr
+      operator bool () const
       {
         return value_;
       }
@@ -310,6 +315,7 @@ namespace micro_os_plus::micro_test_plus
 
     /**
      * @brief Greater than or equal comparator.
+     * @headerfile micro-test-plus.h <micro-os-plus/micro-test-plus.h>
      */
     template <class Lhs_T, class Rhs_T>
     struct ge_ : type_traits::op
@@ -328,8 +334,8 @@ namespace micro_os_plus::micro_test_plus
 #pragma clang diagnostic ignored "-Wpedantic"
 #endif
 #endif
-              if constexpr (type_traits::has_value_v<
-                                Lhs_T> and type_traits::has_value_v<Rhs_T>)
+              if constexpr (type_traits::has_value_v<Lhs_T>
+                            and type_traits::has_value_v<Rhs_T>)
                 {
                   return Lhs_T::value >= Rhs_T::value;
                 }
@@ -344,7 +350,8 @@ namespace micro_os_plus::micro_test_plus
       {
       }
 
-      [[nodiscard]] constexpr operator bool () const
+      [[nodiscard]] constexpr
+      operator bool () const
       {
         return value_;
       }
@@ -366,6 +373,7 @@ namespace micro_os_plus::micro_test_plus
 
     /**
      * @brief Less than comparator.
+     * @headerfile micro-test-plus.h <micro-os-plus/micro-test-plus.h>
      */
     template <class Lhs_T, class Rhs_T>
     struct lt_ : type_traits::op
@@ -384,8 +392,8 @@ namespace micro_os_plus::micro_test_plus
 #pragma clang diagnostic ignored "-Wpedantic"
 #endif
 #endif
-              if constexpr (type_traits::has_value_v<
-                                Lhs_T> and type_traits::has_value_v<Rhs_T>)
+              if constexpr (type_traits::has_value_v<Lhs_T>
+                            and type_traits::has_value_v<Rhs_T>)
                 {
                   return Lhs_T::value < Rhs_T::value;
                 }
@@ -400,7 +408,8 @@ namespace micro_os_plus::micro_test_plus
       {
       }
 
-      [[nodiscard]] constexpr operator bool () const
+      [[nodiscard]] constexpr
+      operator bool () const
       {
         return value_;
       }
@@ -423,6 +432,7 @@ namespace micro_os_plus::micro_test_plus
 
     /**
      * @brief Less than or equal comparator.
+     * @headerfile micro-test-plus.h <micro-os-plus/micro-test-plus.h>
      */
     template <class Lhs_T, class Rhs_T>
     struct le_ : type_traits::op
@@ -441,8 +451,8 @@ namespace micro_os_plus::micro_test_plus
 #pragma clang diagnostic ignored "-Wpedantic"
 #endif
 #endif
-              if constexpr (type_traits::has_value_v<
-                                Lhs_T> and type_traits::has_value_v<Rhs_T>)
+              if constexpr (type_traits::has_value_v<Lhs_T>
+                            and type_traits::has_value_v<Rhs_T>)
                 {
                   return Lhs_T::value <= Rhs_T::value;
                 }
@@ -457,7 +467,8 @@ namespace micro_os_plus::micro_test_plus
       {
       }
 
-      [[nodiscard]] constexpr operator bool () const
+      [[nodiscard]] constexpr
+      operator bool () const
       {
         return value_;
       }
@@ -481,17 +492,19 @@ namespace micro_os_plus::micro_test_plus
 
     /**
      * @brief Logical and operator.
+     * @headerfile micro-test-plus.h <micro-os-plus/micro-test-plus.h>
      */
     template <class Lhs_T, class Rhs_T>
     struct and_ : type_traits::op
     {
       constexpr and_ (const Lhs_T& lhs = {}, const Rhs_T& rhs = {})
-          : lhs_{ lhs }, rhs_{ rhs }, value_{ static_cast<bool> (lhs)
-                                              and static_cast<bool> (rhs) }
+          : lhs_{ lhs }, rhs_{ rhs },
+            value_{ static_cast<bool> (lhs) and static_cast<bool> (rhs) }
       {
       }
 
-      [[nodiscard]] constexpr operator bool () const
+      [[nodiscard]] constexpr
+      operator bool () const
       {
         return value_;
       }
@@ -515,17 +528,19 @@ namespace micro_os_plus::micro_test_plus
 
     /**
      * @brief Logical or operator.
+     * @headerfile micro-test-plus.h <micro-os-plus/micro-test-plus.h>
      */
     template <class Lhs_T, class Rhs_T>
     struct or_ : type_traits::op
     {
       constexpr or_ (const Lhs_T& lhs = {}, const Rhs_T& rhs = {})
-          : lhs_{ lhs }, rhs_{ rhs }, value_{ static_cast<bool> (lhs)
-                                              or static_cast<bool> (rhs) }
+          : lhs_{ lhs }, rhs_{ rhs },
+            value_{ static_cast<bool> (lhs) or static_cast<bool> (rhs) }
       {
       }
 
-      [[nodiscard]] constexpr operator bool () const
+      [[nodiscard]] constexpr
+      operator bool () const
       {
         return value_;
       }
@@ -549,6 +564,7 @@ namespace micro_os_plus::micro_test_plus
 
     /**
      * @brief Logical not operator.
+     * @headerfile micro-test-plus.h <micro-os-plus/micro-test-plus.h>
      */
     template <class T>
     struct not_ : type_traits::op
@@ -558,7 +574,8 @@ namespace micro_os_plus::micro_test_plus
       {
       }
 
-      [[nodiscard]] constexpr operator bool () const
+      [[nodiscard]] constexpr
+      operator bool () const
       {
         return value_;
       }
@@ -576,6 +593,7 @@ namespace micro_os_plus::micro_test_plus
 #if defined(__cpp_exceptions)
     /**
      * @brief Operator to check if the expression throws a specific exception.
+     * @headerfile micro-test-plus.h <micro-os-plus/micro-test-plus.h>
      */
     template <class Callable_T, class Exception_T = void>
     struct throws_ : type_traits::op
@@ -599,7 +617,8 @@ namespace micro_os_plus::micro_test_plus
       {
       }
 
-      [[nodiscard]] constexpr operator bool () const
+      [[nodiscard]] constexpr
+      operator bool () const
       {
         return value_;
       }
@@ -609,6 +628,7 @@ namespace micro_os_plus::micro_test_plus
 
     /**
      * @brief Operator to check if the expression throws any exception.
+     * @headerfile micro-test-plus.h <micro-os-plus/micro-test-plus.h>
      */
     template <class Callable_T>
     struct throws_<Callable_T, void> : type_traits::op
@@ -628,7 +648,8 @@ namespace micro_os_plus::micro_test_plus
       {
       }
 
-      [[nodiscard]] constexpr operator bool () const
+      [[nodiscard]] constexpr
+      operator bool () const
       {
         return value_;
       }
@@ -638,6 +659,7 @@ namespace micro_os_plus::micro_test_plus
 
     /**
      * @brief Operator to check if the expression does not throw any exception.
+     * @headerfile micro-test-plus.h <micro-os-plus/micro-test-plus.h>
      */
     template <class Callable_T>
     struct nothrow_ : type_traits::op
@@ -657,7 +679,8 @@ namespace micro_os_plus::micro_test_plus
       {
       }
 
-      [[nodiscard]] constexpr operator bool () const
+      [[nodiscard]] constexpr
+      operator bool () const
       {
         return value_;
       }
@@ -668,6 +691,11 @@ namespace micro_os_plus::micro_test_plus
 
     // ------------------------------------------------------------------------
 
+    /**
+     * @brief Base class for a deferred reporter, that collects the
+     * messages into a string.
+     * @headerfile micro-test-plus.h <micro-os-plus/micro-test-plus.h>
+     */
     class deferred_reporter_base
     {
     public:
@@ -698,6 +726,11 @@ namespace micro_os_plus::micro_test_plus
       std::string message_{};
     };
 
+    /**
+     * @brief Class template for a deferred reporter specific
+     * to an expression.
+     * @headerfile micro-test-plus.h <micro-os-plus/micro-test-plus.h>
+     */
     template <class Expr_T>
     class deferred_reporter : public deferred_reporter_base
     {

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

@@ -40,8 +40,8 @@ namespace micro_os_plus::micro_test_plus
   template <typename Callable_T, typename... Args_T>
   test_suite::test_suite (const char* name, Callable_T&& callable,
                           Args_T&&... arguments)
-      : test_suite_base{ name }, callable_{ std::bind (callable,
-                                                       arguments...) }
+      : test_suite_base{ name },
+        callable_{ std::bind (callable, arguments...) }
   {
 #if defined(MICRO_TEST_PLUS_TRACE)
     printf ("%s\n", __PRETTY_FUNCTION__);
@@ -52,16 +52,46 @@ namespace micro_os_plus::micro_test_plus
 
   // --------------------------------------------------------------------------
 
+  /**
+   * @details
+   * A test case is a sequence of test conditions (or simply tests,
+   * or checks), which are expectations/assumptions, i.e. conditions
+   * expected to be true.
+   *
+   * Tests are based on logical expressions, which usually compute
+   * a result and compare it to an expected value.
+   * For C++ projects, it is also possible to check if, while
+   * evaluating an expression, exceptions are thrown or not.
+   * Each test either succeeds or fails.
+   * For expectations, the runner keeps counts of successful
+   * and failed tests.
+   *
+   * A test case has a name, a function which performs the checks, and
+   * possibly arguments.
+   *
+   * The `test_case` implementation invokes the function with
+   * the provided arguments, and reports the results.
+   *
+   * @par Example
+   *
+   * ```cpp
+   *   namespace mt = micro_os_plus::micro_test_plus;
+   *
+   *   mt::test_case ("Check answer with comparator", [] {
+   *     mt::expect (mt::eq (compute_answer (), 42)) << "answer is 42";
+   *   });
+   * ```
+   */
   template <typename Callable_T, typename... Args_T>
   void
-  test_case (const char* name, Callable_T&& func, Args_T&&... arguments)
+  test_case (const char* name, Callable_T&& callable, Args_T&&... arguments)
   {
 #if 0 // defined(MICRO_TEST_PLUS_TRACE)
     printf ("%s\n", __PRETTY_FUNCTION__);
 #endif // MICRO_TEST_PLUS_TRACE
 
     current_test_suite->begin_test_case (name);
-    std::invoke (std::forward<Callable_T> (func),
+    std::invoke (std::forward<Callable_T> (callable),
                  std::forward<Args_T> (arguments)...);
     current_test_suite->end_test_case ();
   }
@@ -92,9 +122,8 @@ namespace micro_os_plus::micro_test_plus
     constexpr deferred_reporter<Expr_T>::deferred_reporter (
         const Expr_T& expr, bool abort,
         const reflection::source_location& location)
-        : deferred_reporter_base{ static_cast<bool> (expr), location }, expr_{
-            expr
-          }
+        : deferred_reporter_base{ static_cast<bool> (expr), location },
+          expr_{ expr }
     {
 #if 0 // defined(MICRO_TEST_PLUS_TRACE)
       printf ("%s\n", __PRETTY_FUNCTION__);
@@ -121,6 +150,20 @@ namespace micro_os_plus::micro_test_plus
   // --------------------------------------------------------------------------
   namespace utility
   {
+    /**
+     * @details
+     * For tests handling strings, this function template allows
+     * to split a string into a vector of substrings, using a delimiter.
+     *
+     * @par Example
+     * ```cpp
+     * namespace mt = micro_os_plus::micro_test_plus;
+     *
+     * mt::expect (std::vector<std::string_view>{ "a", "b" }
+     *             == mt::utility::split<std::string_view> ("a.b", "."))
+     *         << "a.b splits into [a,b]";
+     * ```
+     */
     template <class T = std::string_view, class Delim_T>
     [[nodiscard]] auto
     split (T input, Delim_T delim) -> std::vector<T>