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

package/CHANGELOG.md

@@ -6,6 +6,50 @@ Please check
 [GitHub](https://github.com/micro-os-plus/micro-test-plus-xpack/issues/)
 and close existing issues and pull requests.
 
+## 2023-12-06
+
+* v3.2.0
+* 90963ce micro-test-plus.h cosmetics
+* c57c46e literals.h: silence clang deprecation warning
+* f776b18 doxygen metadata: add @headerfile
+* 94ff7d7 website: use to_*
+* 9d4f8bb tests/sample-test.cpp: use to_*
+* 24606d7 literals.h: add to_*, deprecate _*
+
+## 2023-12-05
+
+* 76ddc99 user-guide.md: use mt::
+* 86adedf doxygen metadata: use mt:: in examples
+* 71db099 tests: use explicit mt::
+* c508d4f testing.md: remove reference to test-all.yml
+* 11a1f31 testing.md: update
+* 1ee57a8 testing.md: fix typo
+* 749e2d6 testing.md: add clang 17
+* 221a630 rename xpack-development
+* 06419e5 tests/package.json: enable gcc11
+* 03cb2ed tests/package.json: bump deps
+
+## 2023-12-04
+
+* ebe7e55 package-lock.json updates
+* 17e8859 tests/package.json: add clang 17
+* 75e585a micro-test-plus.cpp: silence warning for clang 17
+
+## 2023-11-30
+
+* b4ff766 website/package.json: #v2.3.1
+* 19a43d6 testing.md update
+* 822e464 rework tests with platforms sub-folder
+* 2aef49a website/package.json: explicit #v2.3.0
+* 313fd41 website/package.json: explicit #2.3.0
+* 80d0fe8 testing.md: updates
+
+## 2023-11-29
+
+* 2227c94 3.1.2
+* 552865e prepare v3.1.2
+* 993d0f7 testing.md: updates
+
 ## 2023-11-28
 
 * 21393a5 ci.yml cosmetics

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

@@ -47,6 +47,7 @@ namespace micro_os_plus::micro_test_plus
   {
     /**
      * @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
@@ -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
@@ -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
@@ -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
@@ -311,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
@@ -368,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
@@ -426,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
@@ -485,6 +492,7 @@ 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
@@ -520,6 +528,7 @@ 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
@@ -555,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
@@ -583,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
@@ -617,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
@@ -647,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
@@ -681,6 +694,7 @@ 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
     {
@@ -715,6 +729,7 @@ namespace micro_os_plus::micro_test_plus
     /**
      * @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

@@ -75,8 +75,10 @@ namespace micro_os_plus::micro_test_plus
    * @par Example
    *
    * ```cpp
-   *   test_case ("Check answer with comparator", [] {
-   *     expect (eq (compute_answer (), 42)) << "answer is 42";
+   *   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";
    *   });
    * ```
    */
@@ -155,8 +157,10 @@ namespace micro_os_plus::micro_test_plus
      *
      * @par Example
      * ```cpp
-     * expect (std::vector<std::string_view>{ "a", "b" }
-     *             == utility::split<std::string_view> ("a.b", "."))
+     * 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]";
      * ```
      */

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

@@ -347,39 +347,132 @@ namespace micro_os_plus::micro_test_plus
 
   // --------------------------------------------------------------------------
 
-  /**
-   * @addtogroup micro-test-plus-literals
-   * @{
-   */
+#if defined(__GNUC__)
+#pragma GCC diagnostic push
+#if defined(__clang__)
+#pragma clang diagnostic ignored "-Wdocumentation-deprecated-sync"
+#endif
+#endif
 
-  // Wrappers that can be used to convert dynamic values to specific types
-  // that are recognised by the comparators.
-  // The syntax is similar to function calls, like `_i(expression)`, but the
-  // results have custom types expected by comparators.
+  /** @deprecated Use `to_b` (since 3.2.0). */
   using _b = type_traits::value<bool>;
+  /** @deprecated Use `to_c` (since 3.2.0). */
   using _c = type_traits::value<char>;
+  /** @deprecated Use `to_sc` (since 3.2.0). */
   using _sc = type_traits::value<signed char>;
+  /** @deprecated Use `to_s` (since 3.2.0). */
   using _s = type_traits::value<short>;
+  /** @deprecated Use `to_i` (since 3.2.0). */
   using _i = type_traits::value<int>;
+  /** @deprecated Use `to_l` (since 3.2.0). */
   using _l = type_traits::value<long>;
+  /** @deprecated Use `to_ll` (since 3.2.0). */
   using _ll = type_traits::value<long long>;
+  /** @deprecated Use `to_u` (since 3.2.0). */
   using _u = type_traits::value<unsigned>;
+  /** @deprecated Use `to_uc` (since 3.2.0). */
   using _uc = type_traits::value<unsigned char>;
+  /** @deprecated Use `to_us` (since 3.2.0). */
   using _us = type_traits::value<unsigned short>;
+  /** @deprecated Use `to_ul` (since 3.2.0). */
   using _ul = type_traits::value<unsigned long>;
+  /** @deprecated Use `to_ull` (since 3.2.0). */
   using _ull = type_traits::value<unsigned long long>;
+  /** @deprecated Use `to_i8` (since 3.2.0). */
   using _i8 = type_traits::value<std::int8_t>;
+  /** @deprecated Use `to_i16` (since 3.2.0). */
   using _i16 = type_traits::value<std::int16_t>;
+  /** @deprecated Use `to_i32` (since 3.2.0). */
   using _i32 = type_traits::value<std::int32_t>;
+  /** @deprecated Use `to_i64` (since 3.2.0). */
   using _i64 = type_traits::value<std::int64_t>;
+  /** @deprecated Use `to_u8` (since 3.2.0). */
   using _u8 = type_traits::value<std::uint8_t>;
+  /** @deprecated Use `to_u16` (since 3.2.0). */
   using _u16 = type_traits::value<std::uint16_t>;
+  /** @deprecated Use `to_u32` (since 3.2.0). */
   using _u32 = type_traits::value<std::uint32_t>;
+  /** @deprecated Use `to_u64` (since 3.2.0). */
   using _u64 = type_traits::value<std::uint64_t>;
+  /** @deprecated Use `to_f` (since 3.2.0). */
   using _f = type_traits::value<float>;
+  /** @deprecated Use `to_d` (since 3.2.0). */
   using _d = type_traits::value<double>;
+  /** @deprecated Use `to_ld` (since 3.2.0). */
   using _ld = type_traits::value<long double>;
 
+  /**
+   * @deprecated Use `to_t` (since 3.2.0).
+   * @headerfile micro-test-plus.h <micro-os-plus/micro-test-plus.h>
+   */
+  template <class T>
+  struct _t : type_traits::value<T>
+  {
+    constexpr explicit _t (const T& t) : type_traits::value<T>{ t }
+    {
+    }
+  };
+
+#if defined(__GNUC__)
+#pragma GCC diagnostic pop
+#endif
+
+  /**
+   * @addtogroup micro-test-plus-literals
+   * @{
+   */
+
+  // Wrappers that can be used to convert dynamic values to specific types
+  // that are recognised by the comparators.
+  // The syntax is similar to function calls, like `_i(expression)`, but the
+  // results have custom types expected by comparators.
+  /** @since 3.2.0 */
+  using to_b = type_traits::value<bool>;
+  /** @since 3.2.0 */
+  using to_c = type_traits::value<char>;
+  /** @since 3.2.0 */
+  using to_sc = type_traits::value<signed char>;
+  /** @since 3.2.0 */
+  using to_s = type_traits::value<short>;
+  /** @since 3.2.0 */
+  using to_i = type_traits::value<int>;
+  /** @since 3.2.0 */
+  using to_l = type_traits::value<long>;
+  /** @since 3.2.0 */
+  using to_ll = type_traits::value<long long>;
+  /** @since 3.2.0 */
+  using to_u = type_traits::value<unsigned>;
+  /** @since 3.2.0 */
+  using to_uc = type_traits::value<unsigned char>;
+  /** @since 3.2.0 */
+  using to_us = type_traits::value<unsigned short>;
+  /** @since 3.2.0 */
+  using to_ul = type_traits::value<unsigned long>;
+  /** @since 3.2.0 */
+  using to_ull = type_traits::value<unsigned long long>;
+  /** @since 3.2.0 */
+  using to_i8 = type_traits::value<std::int8_t>;
+  /** @since 3.2.0 */
+  using to_i16 = type_traits::value<std::int16_t>;
+  /** @since 3.2.0 */
+  using to_i32 = type_traits::value<std::int32_t>;
+  /** @since 3.2.0 */
+  using to_i64 = type_traits::value<std::int64_t>;
+  /** @since 3.2.0 */
+  using to_u8 = type_traits::value<std::uint8_t>;
+  /** @since 3.2.0 */
+  using to_u16 = type_traits::value<std::uint16_t>;
+  /** @since 3.2.0 */
+  using to_u32 = type_traits::value<std::uint32_t>;
+  /** @since 3.2.0 */
+  using to_u64 = type_traits::value<std::uint64_t>;
+  /** @since 3.2.0 */
+  using to_f = type_traits::value<float>;
+  /** @since 3.2.0 */
+  using to_d = type_traits::value<double>;
+  /** @since 3.2.0 */
+  using to_ld = type_traits::value<long double>;
+
   /**
    * @}
    */
@@ -387,11 +480,17 @@ namespace micro_os_plus::micro_test_plus
   /**
    * @ingroup micro-test-plus-literals
    * @brief Template for wrapping any other type.
+   * @headerfile micro-test-plus.h <micro-os-plus/micro-test-plus.h>
+   * @since 3.2.0
+   *
+   * @details
+   * A public class used only to convert the type.
    */
   template <class T>
-  struct _t : type_traits::value<T>
+  struct to_t : type_traits::value<T>
   {
-    constexpr explicit _t (const T& t) : type_traits::value<T>{ t }
+    /** @brief Constructor. */
+    constexpr explicit to_t (const T& t) : type_traits::value<T>{ t }
     {
     }
   };

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

@@ -40,7 +40,6 @@
 
 #if defined(__GNUC__)
 #pragma GCC diagnostic push
-
 #pragma GCC diagnostic ignored "-Wpadded"
 #pragma GCC diagnostic ignored "-Waggregate-return"
 #if defined(__clang__)
@@ -128,7 +127,9 @@ namespace micro_os_plus::micro_test_plus
    *
    * @par Example
    * ```cpp
-   * expect (compute_answer () == 42) << "answer is 42";
+   * namespace mt = micro_os_plus::micro_test_plus;
+   *
+   * mt::expect (compute_answer () == 42) << "answer is 42";
    * ```
    */
   template <class Expr_T, type_traits::requires_t<
@@ -156,7 +157,9 @@ namespace micro_os_plus::micro_test_plus
    *
    * @par Example
    * ```cpp
-   * assert (compute_answer () == 42) << "answer is 42";
+   * namespace mt = micro_os_plus::micro_test_plus;
+   *
+   * mt::assume (compute_answer () == 42) << "answer is 42";
    * ```
    */
   template <class Expr_T, type_traits::requires_t<

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

@@ -52,6 +52,7 @@ namespace micro_os_plus::micro_test_plus
 #else
     /**
      * @brief Local implementation of the std::source_location.
+     * @headerfile micro-test-plus.h <micro-os-plus/micro-test-plus.h>
      */
     class source_location
     {

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

@@ -49,6 +49,7 @@ namespace micro_os_plus::micro_test_plus
 
   /**
    * @brief Colours used to highlight pass vs. fail.
+   * @headerfile micro-test-plus.h <micro-os-plus/micro-test-plus.h>
    */
   struct colors
   {
@@ -59,6 +60,7 @@ namespace micro_os_plus::micro_test_plus
 
   /**
    * @brief The verbosity levels.
+   * @headerfile micro-test-plus.h <micro-os-plus/micro-test-plus.h>
    */
   enum class verbosity
   {
@@ -80,6 +82,7 @@ namespace micro_os_plus::micro_test_plus
   /**
    * @brief Reporter to display the test results. For failed
    * tests it prints the actual values of the operands, with their types.
+   * @headerfile micro-test-plus.h <micro-os-plus/micro-test-plus.h>
    */
   class test_reporter
   {

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

@@ -46,6 +46,7 @@ namespace micro_os_plus::micro_test_plus
   /**
    * @brief The test runner. It maintains a list of test suites which
    * automatically register themselves in their constructors.
+   * @headerfile micro-test-plus.h <micro-os-plus/micro-test-plus.h>
    */
   class test_runner
   {

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

@@ -45,6 +45,7 @@ namespace micro_os_plus::micro_test_plus
 
   /**
    * @brief Base class for all test suites.
+   * @headerfile micro-test-plus.h <micro-os-plus/micro-test-plus.h>
    */
   class test_suite_base
   {
@@ -249,6 +250,7 @@ namespace micro_os_plus::micro_test_plus
    * @ingroup micro-test-plus-test-suites
    * @brief Test suites are classes that represent a named group of
    * test cases which self register to the runner.
+   * @headerfile micro-test-plus.h <micro-os-plus/micro-test-plus.h>
    */
   class test_suite : public test_suite_base
   {

package/include/micro-os-plus/type-traits.h

@@ -45,11 +45,17 @@ namespace micro_os_plus::micro_test_plus
    */
   namespace type_traits
   {
+    /**
+     * @headerfile micro-test-plus.h <micro-os-plus/micro-test-plus.h>
+     */
     template <class...>
     struct list
     {
     };
 
+    /**
+     * @headerfile micro-test-plus.h <micro-os-plus/micro-test-plus.h>
+     */
     template <class T, class...>
     struct identity
     {
@@ -69,6 +75,9 @@ namespace micro_os_plus::micro_test_plus
     };
 #endif
 
+    /**
+     * @headerfile micro-test-plus.h <micro-os-plus/micro-test-plus.h>
+     */
     template <class R, class... Args_T>
     struct function_traits<R (*) (Args_T...)>
     {
@@ -76,6 +85,9 @@ namespace micro_os_plus::micro_test_plus
       using args = list<Args_T...>;
     };
 
+    /**
+     * @headerfile micro-test-plus.h <micro-os-plus/micro-test-plus.h>
+     */
     template <class R, class... Args_T>
     struct function_traits<R (Args_T...)>
     {
@@ -83,6 +95,9 @@ namespace micro_os_plus::micro_test_plus
       using args = list<Args_T...>;
     };
 
+    /**
+     * @headerfile micro-test-plus.h <micro-os-plus/micro-test-plus.h>
+     */
     template <class R, class T, class... Args_T>
     struct function_traits<R (T::*) (Args_T...)>
     {
@@ -90,6 +105,9 @@ namespace micro_os_plus::micro_test_plus
       using args = list<Args_T...>;
     };
 
+    /**
+     * @headerfile micro-test-plus.h <micro-os-plus/micro-test-plus.h>
+     */
     template <class R, class T, class... Args_T>
     struct function_traits<R (T::*) (Args_T...) const>
     {
@@ -159,11 +177,17 @@ namespace micro_os_plus::micro_test_plus
     constexpr auto is_convertible_v = is_convertible<From, To> (0);
 #endif
 
+    /**
+     * @headerfile micro-test-plus.h <micro-os-plus/micro-test-plus.h>
+     */
     template <bool>
     struct requires_
     {
     };
 
+    /**
+     * @headerfile micro-test-plus.h <micro-os-plus/micro-test-plus.h>
+     */
     template <>
     struct requires_<true>
     {
@@ -175,6 +199,7 @@ namespace micro_os_plus::micro_test_plus
 
     /**
      * @brief Empty base class of all operators.
+     * @headerfile micro-test-plus.h <micro-os-plus/micro-test-plus.h>
      */
     struct op
     {
@@ -183,6 +208,7 @@ namespace micro_os_plus::micro_test_plus
     /**
      * @brief A generic integral constant.
      * It has a getter and a '-' operator to return the negative value.
+     * @headerfile micro-test-plus.h <micro-os-plus/micro-test-plus.h>
      */
     template <auto N>
     struct integral_constant : op
@@ -213,6 +239,7 @@ namespace micro_os_plus::micro_test_plus
      * @brief A generic floating point constant, with custom size
      * and precision.
      * It has a getter and a '-' operator to return the negative value.
+     * @headerfile micro-test-plus.h <micro-os-plus/micro-test-plus.h>
      */
     template <class T, auto N, auto D, auto Size, auto P = 1>
     struct floating_point_constant : op
@@ -242,6 +269,9 @@ namespace micro_os_plus::micro_test_plus
       }
     };
 
+    /**
+     * @headerfile micro-test-plus.h <micro-os-plus/micro-test-plus.h>
+     */
     template <class T>
     struct genuine_integral_value : op
     {
@@ -271,6 +301,7 @@ namespace micro_os_plus::micro_test_plus
 
     /**
      * @brief Class defining a generic value, accessible via a getter.
+     * @headerfile micro-test-plus.h <micro-os-plus/micro-test-plus.h>
      */
     template <class T, class = int>
     struct value : type_traits::op
@@ -301,6 +332,7 @@ namespace micro_os_plus::micro_test_plus
      * in addition to the actual value, has an epsilon, to use the
      * desired precision during comparisons.
      * If missing, the default is 1 / (10^decimals).
+     * @headerfile micro-test-plus.h <micro-os-plus/micro-test-plus.h>
      */
     template <class T>
     struct value<T,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@micro-os-plus/micro-test-plus",
-  "version": "3.1.2",
+  "version": "3.2.0",
   "description": "A source code library with µTest++, a lightweight testing framework for embedded platforms",
   "main": "",
   "scripts": {

package/src/micro-test-plus.cpp

@@ -93,11 +93,11 @@ namespace micro_os_plus::micro_test_plus
 #pragma clang diagnostic ignored "-Wunsafe-buffer-usage"
 #endif
       const char* p = strrchr (name, '/');
-#pragma GCC diagnostic pop
       if (p != nullptr)
         return p + 1;
       else
         return name;
+#pragma GCC diagnostic pop
     }
 
   } // namespace reflection
@@ -113,8 +113,10 @@ namespace micro_os_plus::micro_test_plus
      * @par Examples
      *
      * ```cpp
-     * expect (utility::is_match ("abc", "a?c")) << "abc matches a?c";
-     * expect (utility::is_match ("abc", "a*c")) << "abc matches a*c";
+     * namespace mt = micro_os_plus::micro_test_plus;
+     *
+     * mt::expect (mt::utility::is_match ("abc", "a?c")) << "abc matches a?c";
+     * mt::expect (mt::utility::is_match ("abc", "a*c")) << "abc matches a*c";
      * ```
      */
     [[nodiscard]] bool