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

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

@@ -0,0 +1,135 @@
+/*
+ * 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
+
+// ----------------------------------------------------------------------------
+
+#if defined(MICRO_OS_PLUS_INCLUDE_CONFIG_H)
+#include <micro-os-plus/config.h>
+#endif // MICRO_OS_PLUS_INCLUDE_CONFIG_H
+
+#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
+
+// ----------------------------------------------------------------------------
+
+#endif // MICRO_TEST_PLUS_UTILITY_H_
+
+// ----------------------------------------------------------------------------

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

@@ -71,26 +71,22 @@
 #include "micro-test-plus/math.h"
 #include "micro-test-plus/literals.h"
 #include "micro-test-plus/function-comparators.h"
+#include "micro-test-plus/exceptions.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"
+#include "micro-test-plus/deferred-reporter.h"
+#include "micro-test-plus/test.h"
 
-// ----------------------------------------------------------------------------
+#include "micro-test-plus/runner.h"
+#include "micro-test-plus/runner-totals.h"
+
+#include "micro-test-plus/reporter.h"
+#include "micro-test-plus/reporter-human.h"
+#include "micro-test-plus/reporter-tap.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
+#include "micro-test-plus/utility.h"
+
+// ----------------------------------------------------------------------------
 
 /**
  * @namespace micro_os_plus::micro_test_plus
@@ -116,229 +112,30 @@
  * 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);
+// ============================================================================
+// Templates & constexpr implementations.
 
-#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
-// ====================================
+#include <micro-os-plus/diag/trace.h>
 
 // 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/deferred-reporter-inlines.h"
+#include "micro-test-plus/inlines/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/runner-inlines.h"
+#include "micro-test-plus/inlines/test-inlines.h"
 
-#include "micro-test-plus/inlines/micro-test-plus-inlines.h"
+#include "micro-test-plus/inlines/utility-inlines.h"
+
+// ----------------------------------------------------------------------------
+
+#endif // __cplusplus
 
 // ----------------------------------------------------------------------------
 

package/meson.build

@@ -43,12 +43,16 @@ _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/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.0",
+  "version": "4.0.0",
   "description": "A source code library with µTest++, a lightweight testing framework for embedded platforms",
   "repository": {
     "type": "git",

package/src/deferred-reporter.cpp

@@ -0,0 +1,118 @@
+/*
+ * 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
+
+#include <micro-os-plus/micro-test-plus.h>
+#include <micro-os-plus/diag/trace.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 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
+
+      if (value_) [[likely]]
+        {
+          subtest_.totals ().increment_successful_checks ();
+        }
+      else
+        {
+          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
+
+// ----------------------------------------------------------------------------

package/src/reflection.cpp

@@ -0,0 +1,95 @@
+/*
+ * 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++ methods.
+ *
+ * @details
+ * This source file contains the implementation of
+ * `reflection::short_name()`, which extracts the base file name from a
+ * fully qualified path by returning the portion after the last `/`
+ * separator, or the original string if no separator is present.
+ *
+ * All definitions reside within the
+ * `micro_os_plus::micro_test_plus::reflection` 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
+
+#include <micro-os-plus/micro-test-plus.h>
+
+// ----------------------------------------------------------------------------
+
+#if defined(__GNUC__)
+#if defined(__clang__)
+#pragma clang diagnostic ignored "-Wc++98-compat"
+#endif
+#endif
+
+// ============================================================================
+
+namespace micro_os_plus::micro_test_plus
+{
+  // --------------------------------------------------------------------------
+  // Public API.
+
+  // --------------------------------------------------------------------------
+  // Too small to deserve a separate source file.
+  namespace reflection
+  {
+
+    /**
+     * @details
+     * This function extracts the short name from a given file path by locating
+     * the final folder separator ('/'). If a separator is found, it returns a
+     * pointer to the character immediately following it, effectively providing
+     * the file or folder name. If no separator is present, the original input
+     * string is returned. This utility is useful for reporting concise file or
+     * folder names in test output.
+     */
+    const char*
+    short_name (const char* name) noexcept
+    {
+#if defined(__GNUC__)
+#pragma GCC diagnostic push
+#if defined(__clang__)
+#pragma clang diagnostic ignored "-Wunsafe-buffer-usage"
+#endif
+#endif
+      const char* p = strrchr (name, '/');
+      if (p != nullptr)
+        return p + 1;
+      else
+        return name;
+#if defined(__GNUC__)
+#pragma GCC diagnostic pop
+#endif
+    }
+
+  } // namespace reflection
+
+  // ==========================================================================
+} // namespace micro_os_plus::micro_test_plus
+
+// ----------------------------------------------------------------------------