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

package/src/runner.cpp

@@ -38,13 +38,21 @@
 
 // ----------------------------------------------------------------------------
 
+#include <algorithm>
+#include <string>
+
 #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(MICRO_OS_PLUS_TRACE)
 #include <micro-os-plus/diag/trace.h>
-#include <algorithm>
+#endif // MICRO_OS_PLUS_TRACE
+
+#include "micro-os-plus/micro-test-plus/runner.h"
+#include "micro-os-plus/micro-test-plus/utility.h"
+#include "micro-os-plus/micro-test-plus/reporter-tap.h"
+#include "micro-os-plus/micro-test-plus/reporter-human.h"
 
 // ----------------------------------------------------------------------------
 
@@ -65,12 +73,59 @@ namespace micro_os_plus::micro_test_plus
 
   /**
    * @details
-   * The constructor initialises a new instance of the `test_runner` class,
-   * preparing the test runner for managing test suites and cases within the
-   * µTest++ framework. If tracing is enabled, it outputs the function
-   * signature for diagnostic purposes. This setup ensures the test runner is
-   * ready to coordinate the registration, execution, and reporting of tests
-   * across all test cases and folders.
+   * Performs the `static_runner` to `runner` upcast where both types are
+   * complete, allowing headers with only forward declarations to request this
+   * conversion safely.
+   */
+  runner&
+  detail::to_runner (static_runner& static_runner_ref) noexcept
+  {
+    return static_cast<runner&> (static_runner_ref);
+  }
+
+  /**
+   * @details
+   * Performs static-suite registration where `static_runner` is complete,
+   * allowing header-only template code to avoid direct dependence on
+   * `runner.h` include order.
+   */
+  void
+  detail::register_static_suite (static_runner& static_runner_ref,
+                                 static_suite& static_suite_ref)
+  {
+    static_runner::register_static_suite (static_runner_ref, static_suite_ref);
+  }
+
+  // --------------------------------------------------------------------------
+
+  /**
+   * @details
+   * The constructor initialises a new `runner` instance together with
+   * its top suite (`top_suite_`). If tracing is enabled, it outputs the
+   * function signature for diagnostic purposes.
+   */
+  runner::runner (void) : test_node{ "runner" }, top_suite_{ "", *this }
+  {
+#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
+   * The constructor initialises a new `runner` instance together with
+   * its top suite (`top_suite_`). If tracing is enabled, it outputs the
+   * function signature for diagnostic purposes.
    */
   runner::runner (const char* top_suite_name)
       : test_node{ "runner" }, top_suite_{ top_suite_name, *this }
@@ -113,18 +168,18 @@ namespace micro_os_plus::micro_test_plus
 #endif
   /**
    * @details
-   * This method initialises the test runner by capturing the command-line
-   * arguments and the default test suite name, configuring the framework for
-   * subsequent test execution. It parses the arguments to determine the
-   * desired verbosity level (normal, verbose, quiet, or silent) and applies
-   * this setting to the test reporter. The method also outputs build and
-   * environment information when appropriate, aiding diagnostics and
-   * transparency. Finally, it creates and registers the default test suite,
-   * preparing the framework to manage and execute all test cases and suites
-   * across the project’s folders.
+   * Captures command-line arguments, selects the reporter implementation
+   * (`human` or `tap`), starts session timing, and emits the initial
+   * reporter notifications for the session and top suite.
+   *
+   * If the top suite name is not provided, it attempts to derive a name from
+   * `argv[0]` or defaults to "default suite".
+   *
+   * If tracing is enabled, the command-line arguments are
+   * also logged for diagnostic purposes.
    */
   suite&
-  runner::initialise (int argc, char* argv[])
+  runner::initialise (int argc, char* argv[], const char* top_suite_name)
   {
 #if defined(MICRO_OS_PLUS_TRACE) \
     && defined(MICRO_OS_PLUS_TRACE_MICRO_TEST_PLUS)
@@ -146,6 +201,38 @@ namespace micro_os_plus::micro_test_plus
 #endif // defined(MICRO_OS_PLUS_DEBUG)
 #endif // !defined(MICRO_OS_PLUS_INCLUDE_STARTUP)
 
+    if (strlen (top_suite_name) > 0)
+      {
+        // If provided by this call, use it, possibly override the
+        // deprecated constructor.
+        top_suite_name_ = top_suite_name;
+        top_suite_.name (top_suite_name_.c_str ());
+      }
+    else if (strlen (top_suite_.name ()) == 0)
+      {
+        // If not provided by the constructor or by this call, try to extract a
+        // name from argv[0], which is commonly the executable name. If that
+        // fails, use a default name.
+        if (argc > 0 && argv != nullptr && argv[0] != nullptr)
+          {
+            std::string_view top_suite_name_view{ utility::extract_file_name (
+                argv[0]) };
+
+            const auto dot_pos = top_suite_name_view.rfind ('.');
+            if (dot_pos != std::string_view::npos)
+              {
+                top_suite_name_view = top_suite_name_view.substr (0, dot_pos);
+              }
+
+            top_suite_name_ = top_suite_name_view;
+          }
+        else
+          {
+            top_suite_name_ = "default suite";
+          }
+        top_suite_.name (top_suite_name_.c_str ());
+      }
+
     std::vector<std::string_view> argvs (argv, argv + argc);
 
     std::string_view reporter_name{ "tap" };
@@ -277,7 +364,7 @@ namespace micro_os_plus::micro_test_plus
         // Run the child suite immediately.
         suite_ptr->run ();
 
-        // Accumulate the totals from the static suite into the runner
+        // Accumulate the totals from the child suite into the runner
         // totals.
         // DO NOT increment executed_subtests here.
         totals_ += suite_ptr->totals ();
@@ -337,12 +424,8 @@ namespace micro_os_plus::micro_test_plus
 
   /**
    * @details
-   * This method immediately terminates the process by invoking the standard C
-   * library `abort()` function. It is used to halt test execution in critical
-   * failure scenarios, ensuring that no further tests are run and that the
-   * cause of the failure can be promptly investigated. This approach provides
-   * a robust mechanism for enforcing strict test outcomes across all test
-   * cases and folders.
+   * Prints the source location of the fatal error to `stderr` and then
+   * terminates the process via `::abort()`.
    */
   void
   runner::abort (const reflection::source_location& sl)
@@ -391,6 +474,29 @@ namespace micro_os_plus::micro_test_plus
 
   // ==========================================================================
 
+  /**
+   * @details
+   * Delegates construction to the `runner` base class.
+   * If tracing is enabled, the function signature
+   * and suite name are output for diagnostic purposes.
+   */
+  static_runner::static_runner (void) : runner{}
+  {
+#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 construction to the `runner` base class with the given

package/src/test.cpp

@@ -47,8 +47,12 @@
 #include <micro-os-plus/config.h>
 #endif // MICRO_OS_PLUS_INCLUDE_CONFIG_H
 
-#include <micro-os-plus/micro-test-plus.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/test.h"
+#include "micro-os-plus/micro-test-plus/runner.h"
 
 // ----------------------------------------------------------------------------
 
@@ -63,20 +67,22 @@
 #endif
 #endif
 
-// ==========================================================================
+// ============================================================================
 
 namespace micro_os_plus::micro_test_plus
 {
-  // ==========================================================================
-
-  /**
-   * @details
-   * Stores the supplied @p name pointer, which is expected to point to
-   * a string with a lifetime exceeding that of this instance. If
-   * tracing is enabled, the name is output for diagnostic purposes.
-   */
-  test_node::test_node (const char* name) : name_{ name }
+  namespace detail
   {
+    // ========================================================================
+
+    /**
+     * @details
+     * Stores the supplied @p name pointer, which is expected to point to
+     * a string with a lifetime exceeding that of this instance. If
+     * tracing is enabled, the name is output for diagnostic purposes.
+     */
+    test_node::test_node (const char* name) : name_{ name }
+    {
 #if defined(MICRO_OS_PLUS_TRACE) \
     && defined(MICRO_OS_PLUS_TRACE_MICRO_TEST_PLUS_CONSTRUCTORS)
 #if defined(__GNUC__)
@@ -85,21 +91,21 @@ namespace micro_os_plus::micro_test_plus
 #pragma clang diagnostic ignored "-Wunsafe-buffer-usage-in-libc-call"
 #endif
 #endif
-    trace::printf ("%s '%s'\n", __PRETTY_FUNCTION__, name);
+      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
-   * No resources are owned by `test_node`; the destructor performs no
-   * explicit clean-up. If tracing is enabled, the node name is output
-   * for diagnostic purposes.
-   */
-  test_node::~test_node ()
-  {
+    }
+
+    /**
+     * @details
+     * No resources are owned by `test_node`; the destructor performs no
+     * explicit clean-up. If tracing is enabled, the node name is output
+     * for diagnostic purposes.
+     */
+    test_node::~test_node ()
+    {
 #if defined(MICRO_OS_PLUS_TRACE) \
     && defined(MICRO_OS_PLUS_TRACE_MICRO_TEST_PLUS_CONSTRUCTORS)
 #if defined(__GNUC__)
@@ -108,29 +114,29 @@ namespace micro_os_plus::micro_test_plus
 #pragma clang diagnostic ignored "-Wunsafe-buffer-usage-in-libc-call"
 #endif
 #endif
-    trace::printf ("%s '%s'\n", __PRETTY_FUNCTION__, name_);
+      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
-   * The constructor initialises a new instance of the `runnable_base` class
-   * with the specified name. It sets up the internal state required for
-   * managing test cases within the suite. If tracing is enabled, the function
-   * signature is output for diagnostic purposes. The default test suite does
-   * not require explicit registration, ensuring seamless integration within
-   * the µTest++ framework and supporting organised test management across all
-   * files and folders.
-   */
-  runnable_base::runnable_base (const char* name, class runner& runner,
-                                size_t own_index)
-      : test_node{ name }, runner_{ runner }, own_index_{ own_index }
-  {
+    }
+
+    // ========================================================================
+
+    /**
+     * @details
+     * The constructor initialises a new instance of the `runnable_base` class
+     * with the specified name. It sets up the internal state required for
+     * managing test cases within the suite. If tracing is enabled, the
+     * function signature is output for diagnostic purposes. The default test
+     * suite does not require explicit registration, ensuring seamless
+     * integration within the µTest++ framework and supporting organised test
+     * management across all files and folders.
+     */
+    runnable_base::runnable_base (const char* name, class runner& runner,
+                                  size_t own_index)
+        : test_node{ name }, runner_{ runner }, own_index_{ own_index }
+    {
 #if defined(MICRO_OS_PLUS_TRACE) \
     && defined(MICRO_OS_PLUS_TRACE_MICRO_TEST_PLUS_CONSTRUCTORS)
 #if defined(__GNUC__)
@@ -139,22 +145,22 @@ namespace micro_os_plus::micro_test_plus
 #pragma clang diagnostic ignored "-Wunsafe-buffer-usage-in-libc-call"
 #endif
 #endif
-    trace::printf ("%s '%s' %zu\n", __PRETTY_FUNCTION__, name, own_index_);
+      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
-   * The destructor releases any resources associated with the
-   * `runnable_base` instance. It ensures that the test suite is properly
-   * cleaned up after execution, supporting robust and reliable test management
-   * across all files and folders within the µTest++ framework.
-   */
-  runnable_base::~runnable_base ()
-  {
+    }
+
+    /**
+     * @details
+     * The destructor releases any resources associated with the
+     * `runnable_base` instance. It ensures that the test suite is properly
+     * cleaned up after execution, supporting robust and reliable test
+     * management across all files and folders within the µTest++ framework.
+     */
+    runnable_base::~runnable_base ()
+    {
 #if defined(MICRO_OS_PLUS_TRACE) \
     && defined(MICRO_OS_PLUS_TRACE_MICRO_TEST_PLUS_CONSTRUCTORS)
 #if defined(__GNUC__)
@@ -163,60 +169,60 @@ namespace micro_os_plus::micro_test_plus
 #pragma clang diagnostic ignored "-Wunsafe-buffer-usage-in-libc-call"
 #endif
 #endif
-    trace::printf ("%s '%s'\n", __PRETTY_FUNCTION__, name_);
+      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
 
-    // children_subtests_ holds unique_ptrs; destroyed automatically.
-  }
-
-  /**
-   * @details
-   * Delegates immediately to `runner_.reporter()`, returning the
-   * reporter associated with the owning runner instance.
-   */
-  [[nodiscard]] reporter&
-  runnable_base::reporter (void) const noexcept
-  {
-    return runner_.reporter ();
-  }
-
-  /**
-   * @details
-   * Delegates immediately to `runner_.abort()`, passing the supplied
-   * source location so that the error message identifies the call site
-   * before the process is terminated via `::abort()`.
-   */
-  [[noreturn]] void
-  runnable_base::abort (const reflection::source_location& sl)
-  {
-    runner_.abort (sl);
-  }
-
-  /**
-   * @details
-   * Transfers ownership of @p child_test into `children_subtests_` and
-   * immediately invokes `subtest::run()` on the newly stored subtest.
-   * The parent's executed-subtest counter is then incremented. The
-   * child's check counters are intentionally not merged into the parent
-   * totals; each subtest reports only its own counters. The child's
-   * totals are, however, accumulated into @p suite so that the suite
-   * summary reflects all checks performed by its subtests.
-   */
-  void
-  runnable_base::after_subtest_create_ (
-      std::unique_ptr<class subtest> child_test, suite& suite)
-  {
-    // Transfer ownership into the vector.
-    children_subtests_.push_back (std::move (child_test));
-
-    // Run the child test case immediately.
-    class subtest& subtest = *children_subtests_.back ();
-    subtest.run ();
-
-    // This test executed one more subtest.
+      // children_subtests_ holds unique_ptrs; destroyed automatically.
+    }
+
+    /**
+     * @details
+     * Delegates immediately to `runner_.reporter()`, returning the
+     * reporter associated with the owning runner instance.
+     */
+    [[nodiscard]] reporter&
+    runnable_base::reporter (void) const noexcept
+    {
+      return runner_.reporter ();
+    }
+
+    /**
+     * @details
+     * Delegates immediately to `runner_.abort()`, passing the supplied
+     * source location so that the error message identifies the call site
+     * before the process is terminated via `::abort()`.
+     */
+    [[noreturn]] void
+    runnable_base::abort (const reflection::source_location& sl)
+    {
+      runner_.abort (sl);
+    }
+
+    /**
+     * @details
+     * Transfers ownership of @p child_test into `children_subtests_` and
+     * immediately invokes `subtest::run()` on the newly stored subtest.
+     * The parent's executed-subtest counter is then incremented. The
+     * child's check counters are intentionally not merged into the parent
+     * totals; each subtest reports only its own counters. The child's
+     * totals are, however, accumulated into @p suite so that the suite
+     * summary reflects all checks performed by its subtests.
+     */
+    void
+    runnable_base::after_subtest_create_ (
+        std::unique_ptr<class subtest> child_test, suite& suite)
+    {
+      // Transfer ownership into the vector.
+      children_subtests_.push_back (std::move (child_test));
+
+      // Run the child test case immediately.
+      class subtest& subtest = *children_subtests_.back ();
+      subtest.run ();
+
+      // This test executed one more subtest.
 #if defined(MICRO_OS_PLUS_TRACE) \
     && defined(MICRO_OS_PLUS_TRACE_MICRO_TEST_PLUS_CONSTRUCTORS)
 #if defined(__GNUC__)
@@ -225,15 +231,15 @@ namespace micro_os_plus::micro_test_plus
 #pragma clang diagnostic ignored "-Wunsafe-buffer-usage-in-libc-call"
 #endif
 #endif
-    trace::printf ("%s subtest '%s' executed one more subtest\n",
-                   __PRETTY_FUNCTION__, name ());
+      trace::printf ("%s subtest '%s' executed one more subtest\n",
+                     __PRETTY_FUNCTION__, name ());
 #if defined(__GNUC__)
 #pragma GCC diagnostic pop
 #endif
 #endif // MICRO_OS_PLUS_TRACE_MICRO_TEST_PLUS_CONSTRUCTORS
-    totals ().increment_executed_subtests ();
-    // Do not accumulate the totals from the child test into the current test
-    // totals, each subtest shows only its counters.
+      totals ().increment_executed_subtests ();
+      // Do not accumulate the totals from the child test into the current test
+      // totals, each subtest shows only its counters.
 
 #if defined(MICRO_OS_PLUS_TRACE) \
     && defined(MICRO_OS_PLUS_TRACE_MICRO_TEST_PLUS_CONSTRUCTORS)
@@ -243,23 +249,24 @@ namespace micro_os_plus::micro_test_plus
 #pragma clang diagnostic ignored "-Wunsafe-buffer-usage-in-libc-call"
 #endif
 #endif
-    trace::printf ("%s suite '%s' totals\n", __PRETTY_FUNCTION__,
-                   suite.name ());
+      trace::printf ("%s suite '%s' totals\n", __PRETTY_FUNCTION__,
+                     suite.name ());
 #if defined(__GNUC__)
 #pragma GCC diagnostic pop
 #endif
 #endif // MICRO_OS_PLUS_TRACE_MICRO_TEST_PLUS_CONSTRUCTORS
 
-    // Accumulate the totals from the child test into the suite totals.
-    suite.totals () += subtest.totals ();
-  }
+      // Accumulate the totals from the child test into the suite totals.
+      suite.totals () += subtest.totals ();
+    }
+  } // namespace detail
 
   // ==========================================================================
 
   /**
    * @details
    * The destructor releases any resources associated with the
-   * `test` instance. If tracing is enabled, it outputs the
+   * `subtest` instance. If tracing is enabled, it outputs the
    * function signature for diagnostic purposes. This ensures that the test
    * suite is properly cleaned up after execution, supporting robust and
    * reliable test management across all files and folders within the µTest++

package/src/timings.cpp

@@ -35,13 +35,13 @@
 
 // ----------------------------------------------------------------------------
 
+#include <cassert>
+
 #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 <cassert>
+#include "micro-os-plus/micro-test-plus/timings.h"
 
 // ----------------------------------------------------------------------------
 
@@ -56,7 +56,7 @@
 
 // ============================================================================
 
-namespace micro_os_plus::micro_test_plus
+namespace micro_os_plus::micro_test_plus::detail
 {
   // --------------------------------------------------------------------------
 
@@ -205,5 +205,6 @@ namespace micro_os_plus::micro_test_plus
   }
 
   // --------------------------------------------------------------------------
+} // namespace micro_os_plus::micro_test_plus::detail
 
-} // namespace micro_os_plus::micro_test_plus
+// ----------------------------------------------------------------------------

package/src/utility.cpp

@@ -38,7 +38,7 @@
 #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/micro-test-plus/utility.h"
 
 // ----------------------------------------------------------------------------