@micro-os-plus/micro-test-plus 3.3.1 → 4.1.0

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

@@ -0,0 +1,136 @@
+/*
+ * 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 declarations for the µTest++ utility helpers.
+ *
+ * @details
+ * This header provides declarations for the utility helper functions used
+ * within the µTest++ framework. It defines interfaces for string operations
+ * including file-name extraction, pattern matching, and string splitting.
+ */
+
+#ifndef MICRO_TEST_PLUS_UTILITY_H_
+#define MICRO_TEST_PLUS_UTILITY_H_
+
+// ----------------------------------------------------------------------------
+
+#ifdef __cplusplus
+
+// ----------------------------------------------------------------------------
+
+#include <string_view>
+#include <vector>
+
+// ----------------------------------------------------------------------------
+
+#if defined(__GNUC__)
+#pragma GCC diagnostic push
+#if defined(__clang__)
+#pragma clang diagnostic ignored "-Wc++98-compat"
+#endif
+#endif
+
+// ============================================================================
+
+namespace micro_os_plus::micro_test_plus
+{
+  // --------------------------------------------------------------------------
+
+  /**
+   * @namespace micro_os_plus::micro_test_plus::utility
+   * @brief Utility functions for the µTest++ testing framework.
+   *
+   * @details
+   * The `micro_os_plus::micro_test_plus::utility` namespace provides a suite
+   * of helper functions designed to support advanced string operations and
+   * other common tasks within the µTest++ framework.
+   *
+   * These utilities include functions for pattern matching—such as verifying
+   * whether a string matches a specified pattern—and for splitting strings
+   * into sub-strings based on delimiters. The implementations are efficient
+   * and suitable for both embedded and general C++ projects.
+   *
+   * By encapsulating these helper functions within a dedicated namespace, the
+   * framework maintains clear code organisation and minimises naming
+   * conflicts.
+   */
+  namespace utility
+  {
+    /**
+     * @ingroup micro-test-plus-utility-functions
+     * @brief Extracts the file name component from a full path.
+     *
+     * @param [in] path A null-terminated file path string.
+     * @return A pointer to the first character of the file name within
+     * `path`, or `path` itself if no directory separator is found.
+     */
+    [[nodiscard]] const char*
+    extract_file_name (const char* path) noexcept;
+
+    /**
+     * @ingroup micro-test-plus-utility-functions
+     * @brief Check if a string matches a pattern.
+     *
+     * @param [in] input The string view to be checked.
+     * @param [in] pattern The string view containing the pattern to match.
+     * @return `true` if the input string matches the pattern; otherwise,
+     * `false`.
+     */
+    [[nodiscard]] bool
+    is_match (std::string_view input, std::string_view pattern);
+
+    /**
+     * @ingroup micro-test-plus-utility-functions
+     * @brief Split a string into a vector of sub-strings.
+     *
+     * @tparam T Type of the input string.
+     * @tparam Delim_T Type of the delimiter.
+     *
+     * @param [in] input Input string to split.
+     * @param [in] delim Delimiter string.
+     * @return A vector containing the resulting sub-strings.
+     */
+    template <class T, class Delim_T>
+    [[nodiscard]] auto
+    split (T input, Delim_T delim) -> std::vector<T>;
+
+    // ------------------------------------------------------------------------
+  } // namespace utility
+
+  // --------------------------------------------------------------------------
+} // namespace micro_os_plus::micro_test_plus
+
+#if defined(__GNUC__)
+#pragma GCC diagnostic pop
+#endif
+
+// ----------------------------------------------------------------------------
+
+#endif // __cplusplus
+
+// ============================================================================
+// Templates & constexpr implementations.
+
+#include "inlines/utility-inlines.h"
+
+// ----------------------------------------------------------------------------
+
+#endif // MICRO_TEST_PLUS_UTILITY_H_
+
+// ----------------------------------------------------------------------------

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

@@ -63,34 +63,59 @@
 #include <micro-os-plus/config.h>
 #endif // MICRO_OS_PLUS_INCLUDE_CONFIG_H
 
+// No deps.
+#include "micro-test-plus/math.h"
+
+// Requires math.h.
 #include "micro-test-plus/type-traits.h"
+
+// No deps.
 #include "micro-test-plus/reflection.h"
 
+// Requires type-traits.h, reflection.h.
 #include "micro-test-plus/detail.h"
 
-#include "micro-test-plus/math.h"
+// Requires type-traits.h, math.h.
 #include "micro-test-plus/literals.h"
+
+// No deps.
 #include "micro-test-plus/function-comparators.h"
+
+// No deps.
+#include "micro-test-plus/exceptions.h"
+
+// Requires type-traits.h + detail.h,
 #include "micro-test-plus/operators.h"
 
-#include "micro-test-plus/test-suite.h"
-#include "micro-test-plus/test-runner.h"
-#include "micro-test-plus/test-reporter.h"
-#include "micro-test-plus/test-reporter-basic.h"
-#include "micro-test-plus/test-reporter-tap.h"
+// Requires type-traits.h, detail.h + reflection.h.
+#include "micro-test-plus/expression-formatter.h"
 
-// ----------------------------------------------------------------------------
+// Requires type-traits.h, detail.h, expression-formatter.h, reflection.h.
+#include "micro-test-plus/reporter.h"
+
+// Requires type-traits.h, reflection.h, expression-formatter.h.
+#include "micro-test-plus/deferred-reporter.h"
+
+// No deps.
+#include "micro-test-plus/runner-totals.h"
+
+// Requires reporter.h, reflection.h.
+#include "micro-test-plus/reporter-human.h"
 
-#if defined(__GNUC__)
-#pragma GCC diagnostic push
-#pragma GCC diagnostic ignored "-Wpadded"
-#pragma GCC diagnostic ignored "-Waggregate-return"
-#if defined(__clang__)
-#pragma clang diagnostic ignored "-Wc++98-compat"
-#pragma clang diagnostic ignored "-Wc++98-compat-pedantic"
-#pragma clang diagnostic ignored "-Wctad-maybe-unsupported"
-#endif
-#endif
+// Requires reporter.h, reflection.h.
+#include "micro-test-plus/reporter-tap.h"
+
+// No deps.
+#include "micro-test-plus/utility.h"
+
+// Requires reporter.h, runner-totals.h, reflection.h, type-traits.h and
+// timings.h + deferred-reporter.h, reporter.h.
+#include "micro-test-plus/test.h"
+
+// Requires timings.h, test.h (detail::test_node, top_suite), reflection.h.
+#include "micro-test-plus/runner.h"
+
+// ----------------------------------------------------------------------------
 
 /**
  * @namespace micro_os_plus::micro_test_plus
@@ -116,230 +141,11 @@
  * folder, ensuring a clear separation from user code and facilitating
  * straightforward integration with the wider µOS++ ecosystem.
  */
-namespace micro_os_plus::micro_test_plus
-{
-  // --------------------------------------------------------------------------
-
-  extern test_runner runner;
-  extern test_reporter* reporter;
-  extern test_suite_base* current_test_suite;
-
-  // --------------------------------------------------------------------------
-  // Public API.
-
-  /**
-   * @ingroup micro-test-plus-inits
-   * @brief Initialise the µTest++ framework.
-   *
-   * @param [in] argc The number of command-line arguments.
-   * @param [in] argv Array of pointers to null-terminated argument strings.
-   * @param [in] name The name of the default test suite. Defaults to `"Main"`
-   * if not specified.
-   * @par Returns
-   *  Nothing.
-   */
-  void
-  initialize (int argc, char* argv[], const char* name = "Main");
-
-  /**
-   * @ingroup micro-test-plus-inits
-   * @brief Complete the test run and return the exit code.
-   *
-   * @par Parameters
-   *	 None.
-   * @return 0 if all tests were successful, 1 if any test failed.
-   */
-  [[nodiscard]] int
-  exit_code (void);
-
-  /**
-   * @ingroup micro-test-plus-test-case
-   * @brief Define and execute a test case.
-   *
-   * @tparam Callable_T The type of the callable object to be executed as the
-   * test case.
-   * @tparam Args_T The types of the arguments to be passed to the callable.
-   * @param [in] name The test case name or description, used in test reports.
-   * @param [in] callable A generic callable object, usually a lambda, invoked
-   * to perform the test.
-   * @param [in] arguments A possibly empty list of arguments to be passed to
-   * the callable.
-   * @par Returns
-   *  Nothing.
-   */
-  template <typename Callable_T, typename... Args_T>
-  void
-  test_case (const char* name, Callable_T&& callable, Args_T&&... arguments);
-
-  /**
-   * @ingroup micro-test-plus-expectations
-   * @brief Evaluate a generic condition and report the results.
-   *
-   * @tparam Expr_T The type of the custom expression.
-   *
-   * @par SFINAE
-   * Enabled only if `Expr_T` is derived from `detail::op` or
-   * is convertible to `bool`.
-   *
-
-   * @param [in] expr Logical expression to evaluate.
-   * @param [in] sl Optional source location, defaulting to the current line.
-   * @return An output stream to write optional messages.
-   */
-  template <class Expr_T, type_traits::requires_t<
-                              type_traits::is_op_v<Expr_T>
-                              or type_traits::is_convertible_v<Expr_T, bool>>
-                          = 0>
-  constexpr auto
-  expect (const Expr_T& expr, const reflection::source_location& sl
-                              = reflection::source_location::current ());
-
-  /**
-   * @ingroup micro-test-plus-assumptions
-   * @brief Check a condition and, if false, abort test execution.
-   *
-   * @tparam Expr_T The type of the custom expression.
-   *
-   * @par SFINAE
-   * Enabled only if `Expr_T` is derived from `detail::op` or
-   * is convertible to `bool`.
-   *
-   * @param [in] expr Logical expression to evaluate.
-   * @param [in] sl Optional source location, defaulting to the current line.
-   * @return An output stream to write optional messages.
-   */
-  template <class Expr_T, type_traits::requires_t<
-                              type_traits::is_op_v<Expr_T>
-                              or type_traits::is_convertible_v<Expr_T, bool>>
-                          = 0>
-  constexpr auto
-  assume (const Expr_T& expr, const reflection::source_location& sl
-                              = reflection::source_location::current ());
-
-  // --------------------------------------------------------------------------
-
-#if defined(__cpp_exceptions)
-
-  /**
-   * @ingroup micro-test-plus-exceptions
-   * @brief Check if a callable throws a specific exception.
-   *
-   * @tparam Exception_T The type of the exception expected to be thrown.
-   * @tparam Callable_T The type of the callable object to be invoked.
-   * @param [in] func The callable object to check for exception throwing
-   * behaviour.
-   * @return An output stream to write optional messages.
-   */
-  template <class Exception_T, class Callable_T>
-  [[nodiscard]] constexpr auto
-  throws (const Callable_T& func);
-
-  /**
-   * @ingroup micro-test-plus-exceptions
-   * @brief Check if a callable throws an exception (any exception).
-   *
-   * @tparam Callable_T The type of the callable object to be invoked.
-   * @param [in] func The callable object to check for exception throwing
-   * behaviour.
-   * @return An output stream to write optional messages.
-   */
-  template <class Callable_T>
-  [[nodiscard]] constexpr auto
-  throws (const Callable_T& func);
-
-  /**
-   * @ingroup micro-test-plus-exceptions
-   * @brief Check if a callable does not throw an exception.
-   *
-   * @tparam Callable_T The type of the callable object to be invoked.
-   * @param [in] func The callable object to check for exception safety.
-   * @return An output stream to write optional messages.
-   */
-  template <class Callable_T>
-  [[nodiscard]] constexpr auto
-  nothrow (const Callable_T& func);
-
-#endif
-
-  // --------------------------------------------------------------------------
-
-  /**
-   * @namespace micro_os_plus::micro_test_plus::utility
-   * @brief Utility functions for the µTest++ testing framework.
-   *
-   * @details
-   * The `micro_os_plus::micro_test_plus::utility` namespace provides a suite
-   * of helper functions designed to support advanced string operations and
-   * other common tasks within the µTest++ framework.
-   *
-   * These utilities include functions for pattern matching—such as verifying
-   * whether a string matches a specified pattern—and for splitting strings
-   * into sub-strings based on delimiters. The implementations are efficient
-   * and suitable for both embedded and general C++ projects.
-   *
-   * By encapsulating these helper functions within a dedicated namespace, the
-   * framework maintains clear code organisation and minimises naming
-   * conflicts.
-   */
-  namespace utility
-  {
-    /**
-     * @ingroup micro-test-plus-utility-functions
-     * @brief Check if a string matches a pattern.
-     *
-     * @param [in] input The string view to be checked.
-     * @param [in] pattern The string view containing the pattern to match.
-     * @return `true` if the input string matches the pattern; otherwise,
-     * `false`.
-     */
-    [[nodiscard]] bool
-    is_match (std::string_view input, std::string_view pattern);
-
-    /**
-     * @ingroup micro-test-plus-utility-functions
-     * @brief Split a string into a vector of sub-strings.
-     *
-     * @tparam T Type of the input string.
-     * @tparam Delim_T Type of the delimiter.
-     *
-     * @param [in] input Input string to split.
-     * @param [in] delim Delimiter string.
-     * @return A vector containing the resulting sub-strings.
-     */
-    template <class T, class Delim_T>
-    [[nodiscard]] auto
-    split (T input, Delim_T delim) -> std::vector<T>;
-
-    // ------------------------------------------------------------------------
-  } // namespace utility
-
-  // --------------------------------------------------------------------------
-} // namespace micro_os_plus::micro_test_plus
-
-#if defined(__GNUC__)
-#pragma GCC diagnostic pop
-#endif
 
 // ----------------------------------------------------------------------------
 
 #endif // __cplusplus
 
-// ===== Inlines & templates implementations
-// ====================================
-
-// All inlines are included **after** all declarations.
-#include "micro-test-plus/inlines/details-inlines.h"
-#include "micro-test-plus/inlines/literals-inlines.h"
-#include "micro-test-plus/inlines/math-inlines.h"
-
-#include "micro-test-plus/inlines/reflection-inlines.h"
-#include "micro-test-plus/inlines/test-reporter-inlines.h"
-
-#include "micro-test-plus/inlines/function-comparators-inlines.h"
-#include "micro-test-plus/inlines/test-suite-inlines.h"
-
-#include "micro-test-plus/inlines/micro-test-plus-inlines.h"
-
 // ----------------------------------------------------------------------------
 
 #endif // MICRO_TEST_PLUS_MICRO_TEST_PLUS_H_

package/meson.build

@@ -43,12 +43,17 @@ _local_include_directories += [
 ]
 
 _local_sources += [
-  'src/micro-test-plus.cpp',
-  'src/test-runner.cpp',
-  'src/test-reporter.cpp',
-  'src/test-reporter-basic.cpp',
-  'src/test-reporter-tap.cpp',
-  'src/test-suite.cpp',
+  'src/runner.cpp',
+  'src/runner-totals.cpp',
+  'src/deferred-reporter.cpp',
+  'src/expression-formatter.cpp',
+  'src/reporter.cpp',
+  'src/reporter-human.cpp',
+  'src/reporter-tap.cpp',
+  'src/test.cpp',
+  'src/timings.cpp',
+  'src/reflection.cpp',
+  'src/utility.cpp',
 ]
 
 # https://mesonbuild.com/Reference-manual_functions.html#declare_dependency

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@micro-os-plus/micro-test-plus",
-  "version": "3.3.1",
+  "version": "4.1.0",
   "description": "A source code library with µTest++, a lightweight testing framework for embedded platforms",
   "repository": {
     "type": "git",
@@ -50,12 +50,20 @@
     "postversion": "git push origin --all && git push origin --tags"
   },
   "xpack": {
-    "minimumXpmRequired": "0.20.8"
+    "minimumXpmRequired": "0.20.8",
+    "devDependencies": {
+      "@xpack-dev-tools/clang": "21.1.8-1.1"
+    },
+    "actions": {
+      "clang-format": "bash scripts/clang-format.sh",
+      "cmake-format": "bash scripts/cmake-format.sh"
+    }
   },
   "topConfig": {
     "descriptiveName": "µTest++ Testing Framework",
     "permalinkName": "micro-test-plus",
-    "useDoxygen": "true"
+    "useDoxygen": "true",
+    "hasObjectLibrary": "true"
   },
   "engines": {
     "node": ">=20.0"

package/src/deferred-reporter.cpp

@@ -0,0 +1,137 @@
+/*
+ * 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++ source file with implementations for the µTest++ deferred
+ * reporter methods.
+ *
+ * @details
+ * This source file contains the implementation of the
+ * `detail::deferred_reporter_base` class, which supports deferred
+ * reporting of test expression results. The constructor captures the
+ * result value, source location, and subtest reference; the destructor
+ * updates the subtest counters and optionally aborts execution on
+ * critical failures.
+ *
+ * All definitions reside within the
+ * `micro_os_plus::micro_test_plus::detail` namespace.
+ *
+ * This file must be included when building the µTest++ library.
+ */
+
+// ----------------------------------------------------------------------------
+
+#if defined(MICRO_OS_PLUS_INCLUDE_CONFIG_H)
+#include <micro-os-plus/config.h>
+#endif // MICRO_OS_PLUS_INCLUDE_CONFIG_H
+
+#if defined(MICRO_OS_PLUS_TRACE)
+#include <micro-os-plus/diag/trace.h>
+#endif // MICRO_OS_PLUS_TRACE
+
+#include "micro-os-plus/micro-test-plus/deferred-reporter.h"
+#include "micro-os-plus/micro-test-plus/test.h"
+
+// ----------------------------------------------------------------------------
+
+#if defined(__GNUC__)
+#pragma GCC diagnostic ignored "-Waggregate-return"
+#if defined(__clang__)
+#pragma clang diagnostic ignored "-Wc++98-compat"
+#pragma clang diagnostic ignored "-Wexit-time-destructors"
+#pragma clang diagnostic ignored "-Wglobal-constructors"
+#endif
+#endif
+
+// ============================================================================
+
+namespace micro_os_plus::micro_test_plus
+{
+  // --------------------------------------------------------------------------
+  namespace detail
+  {
+    /**
+     * @details
+     * Stores the evaluated Boolean @p value, the @p location identifying
+     * the source line of the assertion, and a reference to the owning
+     * @p subtest. The subtest's check index counter is incremented
+     * immediately so that the first check is reported as check #1.
+     */
+    deferred_reporter_base::deferred_reporter_base (
+        bool value, const reflection::source_location& location,
+        subtest& subtest)
+        : value_{ value }, location_{ location }, subtest_{ subtest }
+    {
+      // The index starts at 0, must be incremented before the first check is
+      // reported, to ensure that the first check is reported as check #1.
+      subtest_.increment_subtest_index ();
+    }
+
+    /**
+     * @details
+     * The destructor finalises the deferred reporting process for a test
+     * expression. If the evaluated expression is true, the reporter records a
+     * successful outcome along with any accumulated message. If the expression
+     * is false, the reporter records a failure, including the abort status,
+     * message, and source location for comprehensive reporting.
+     *
+     * This mechanism ensures that all relevant information about the test
+     * outcome is captured and reported accurately when the deferred reporter
+     * goes out of scope.
+     *
+     * The destructor ensures that if an abort condition is set and the test
+     * expression has failed, the test output is flushed and the process is
+     * terminated. This mechanism guarantees immediate feedback and halts
+     * further execution upon critical test failures, aiding in rapid
+     * identification and resolution of issues during test runs.
+     */
+    deferred_reporter_base::~deferred_reporter_base ()
+    {
+#if defined(MICRO_OS_PLUS_TRACE) \
+    && defined(MICRO_OS_PLUS_TRACE_MICRO_TEST_PLUS_CONSTRUCTORS)
+      trace::printf ("%s\n", __PRETTY_FUNCTION__);
+#endif // MICRO_OS_PLUS_TRACE_MICRO_TEST_PLUS_CONSTRUCTORS
+
+      auto& expression_str = subtest_.reporter ().expression ().str ();
+
+      if (value_) [[likely]]
+        {
+          subtest_.reporter ().pass (deferred_output_, expression_str,
+                                     subtest_);
+          subtest_.totals ().increment_successful_checks ();
+        }
+      else
+        {
+          subtest_.reporter ().fail (abort_, deferred_output_, expression_str,
+                                     has_expression_, location_, subtest_);
+          subtest_.totals ().increment_failed_checks ();
+        }
+
+      if (abort_ && !value_) [[unlikely]]
+        {
+          subtest_.reporter ().write_buffer_to_stdout ();
+          subtest_.reporter ().flush ();
+          subtest_.abort (location_);
+        }
+    }
+  } // namespace detail
+
+  // ==========================================================================
+} // namespace micro_os_plus::micro_test_plus
+
+// ----------------------------------------------------------------------------