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

package/src/test-runner.cpp

@@ -1,12 +1,12 @@
 /*
  * This file is part of the µOS++ project (https://micro-os-plus.github.io/).
- * Copyright (c) 2021 Liviu Ionescu. All rights reserved.
+ * 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.
+ * 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.
+ * 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,
@@ -15,6 +15,29 @@
 
 // ----------------------------------------------------------------------------
 
+/**
+ * @file
+ * @brief C++ source file with implementations for the µTest++ test runner
+ * methods.
+ *
+ * @details
+ * This source file contains the core implementations for the test runner
+ * facilities of the µTest++ framework. It provides the logic for initialising
+ * the test environment, registering and managing test suites, handling
+ * command-line arguments, orchestrating test execution, and determining the
+ * overall test result. The implementation supports automated discovery and
+ * execution of test suites, flexible verbosity control, and robust mechanisms
+ * for aborting test execution in critical scenarios.
+ *
+ * All definitions reside within the `micro_os_plus::micro_test_plus`
+ * namespace, ensuring clear separation from user code and minimising the risk
+ * of naming conflicts.
+ *
+ * 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
@@ -22,6 +45,7 @@
 #include <micro-os-plus/micro-test-plus.h>
 
 #include <stdio.h>
+#include <stdlib.h>
 #include <vector>
 
 // ----------------------------------------------------------------------------
@@ -37,6 +61,15 @@ 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.
+   */
   test_runner::test_runner ()
   {
 #if defined(MICRO_OS_PLUS_TRACE_MICRO_TEST_PLUS)
@@ -48,6 +81,18 @@ namespace micro_os_plus::micro_test_plus
 #if defined(__clang__)
 #pragma clang diagnostic ignored "-Wunsafe-buffer-usage"
 #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.
+   */
   void
   test_runner::initialize (int argc, char* argv[], const char* name)
   {
@@ -55,6 +100,14 @@ namespace micro_os_plus::micro_test_plus
     printf ("%s\n", __PRETTY_FUNCTION__);
 #endif // MICRO_OS_PLUS_TRACE_MICRO_TEST_PLUS
 
+#if defined(_WIN32) || defined(CLOCK_MONOTONIC)
+#if defined(_WIN32)
+    timespec_get (&begin_time, TIME_UTC);
+#else
+    clock_gettime (CLOCK_MONOTONIC, &begin_time);
+#endif
+#endif
+
     argc_ = argc;
     argv_ = argv;
 
@@ -76,6 +129,7 @@ namespace micro_os_plus::micro_test_plus
 #endif // !defined(MICRO_OS_PLUS_INCLUDE_STARTUP)
 
     verbosity_t verbosity = verbosity::normal;
+    const char* reporter_name = "tap";
     for (int i = 0; i < argc; ++i)
       {
         if (strcmp (argv[i], "--verbose") == 0)
@@ -90,10 +144,27 @@ namespace micro_os_plus::micro_test_plus
           {
             verbosity = verbosity::silent;
           }
+        else if (strncmp (argv[i], "--reporter=", 11) == 0)
+          {
+            reporter_name = argv[i] + 11;
+          }
       }
 
-    // Pass the verbosity to the reporter.
-    reporter.verbosity = verbosity;
+    // Initialize and configure the reporter.
+    if (strcmp (reporter_name, "basic") == 0)
+      {
+        reporter = new test_reporter_basic ();
+      }
+    else if (strcmp (reporter_name, "tap") == 0)
+      {
+        reporter = new test_reporter_tap ();
+      }
+    else
+      {
+        fprintf (stderr, "error: unknown reporter '%s'\n", reporter_name);
+        exit (1);
+      }
+    reporter->verbosity = verbosity;
 
     // ------------------------------------------------------------------------
 
@@ -133,11 +204,12 @@ namespace micro_os_plus::micro_test_plus
 
     // ------------------------------------------------------------------------
 
-    default_test_suite_ = new test_suite_base (default_suite_name_);
-    current_test_suite = default_test_suite_;
+    default_test_suite = new test_suite_base (default_suite_name_);
+    current_test_suite = default_test_suite;
 
     // Deferred to first test case or test suite end, to allow various
     // initialisations to display their messages.
+    // reporter->begin_test (test_suites_count ());
     // default_test_suite_->begin_test_suite ();
   }
 #pragma GCC diagnostic pop
@@ -147,32 +219,62 @@ namespace micro_os_plus::micro_test_plus
   {
     bool was_successful = true;
 
-    if (!default_test_suite_->unused ())
+    if (!default_test_suite->unused ())
       {
-        default_test_suite_->end_test_suite ();
-        was_successful = default_test_suite_->was_successful ();
+        default_test_suite->end_test_suite ();
+        was_successful = default_test_suite->was_successful ();
+
+        totals.successful_checks += default_test_suite->successful_checks ();
+        totals.failed_checks += default_test_suite->failed_checks ();
+        totals.test_cases_count += default_test_suite->test_cases_count ();
       }
 
-    if (suites_ != nullptr)
+    if (test_suites != nullptr)
       {
-        for (auto suite : *suites_)
+        for (auto test_suite : *test_suites)
           {
-            current_test_suite = suite;
+            current_test_suite = test_suite;
+
+            test_suite->begin_test_suite ();
+            test_suite->run ();
+            test_suite->end_test_suite ();
 
-            suite->begin_test_suite ();
-            suite->run ();
-            suite->end_test_suite ();
+            was_successful &= test_suite->was_successful ();
 
-            was_successful &= suite->was_successful ();
+            totals.successful_checks += test_suite->successful_checks ();
+            totals.failed_checks += test_suite->failed_checks ();
+            totals.test_cases_count += test_suite->test_cases_count ();
           }
-        if (reporter.verbosity != verbosity::silent)
+        if (reporter->verbosity != verbosity::silent)
           {
             // printf ("\n");
           }
       }
+
+#if defined(_WIN32) || defined(CLOCK_MONOTONIC)
+#if defined(_WIN32)
+    timespec_get (&end_time, TIME_UTC);
+#else
+    clock_gettime (CLOCK_MONOTONIC, &end_time);
+#endif
+#endif
+
+    reporter->end_test (*this);
+
     return was_successful ? 0 : 1;
   }
 
+  /**
+   * @details
+   * This method registers a new test suite with the test runner. If the
+   * internal collection of test suites has not yet been created, it is
+   * initialised at this point. The provided test suite is then added to the
+   * collection, enabling the framework to manage and execute multiple test
+   * suites across different files and folders within the project.
+   *
+   * Called by test suite constructors to register themselves with the
+   * runner, enabling automatic management and execution.
+   */
   void
   test_runner::register_test_suite (test_suite_base* suite)
   {
@@ -180,13 +282,23 @@ namespace micro_os_plus::micro_test_plus
     printf ("%s\n", __PRETTY_FUNCTION__);
 #endif // MICRO_OS_PLUS_TRACE_MICRO_TEST_PLUS
 
-    if (suites_ == nullptr)
+    if (test_suites == nullptr)
       {
-        suites_ = new std::vector<test_suite_base*> ();
+        test_suites = new std::vector<test_suite_base*> ();
       }
-    suites_->push_back (suite);
+    test_suites->push_back (suite);
+    suite->index = test_suites->size () + 1;
   }
 
+  /**
+   * @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.
+   */
   void
   test_runner::abort (void)
   {

package/src/test-suite.cpp

@@ -1,12 +1,12 @@
 /*
  * This file is part of the µOS++ project (https://micro-os-plus.github.io/).
- * Copyright (c) 2021 Liviu Ionescu. All rights reserved.
+ * 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.
+ * 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.
+ * 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,
@@ -15,6 +15,34 @@
 
 // ----------------------------------------------------------------------------
 
+/**
+ * @file
+ * @brief C++ source file with implementations for the µTest++ test suite
+ * methods.
+ *
+ * @details
+ * This source file contains the core implementations for the test suite
+ * facilities of the µTest++ framework. It provides the logic for constructing,
+ * registering, and managing test suites and their associated test cases. The
+ * implementation covers initialisation and clean-up routines, execution of
+ * test suites and test cases, tracking of successful and failed checks, and
+ * integration with the test reporter for structured output.
+ *
+ * The design ensures that test suites are non-copyable and non-movable,
+ * maintaining unique ownership and consistent state. Flexible support for
+ * callable objects enables a wide range of test suite definitions,
+ * facilitating expressive and maintainable test organisation across embedded
+ * and general C++ projects.
+ *
+ * All definitions reside within the `micro_os_plus::micro_test_plus`
+ * namespace, ensuring clear separation from user code and minimising the risk
+ * of naming conflicts.
+ *
+ * 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
@@ -34,6 +62,16 @@ namespace micro_os_plus::micro_test_plus
 {
   // --------------------------------------------------------------------------
 
+  /**
+   * @details
+   * The constructor initialises a new instance of the `test_suite_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.
+   */
   test_suite_base::test_suite_base (const char* name)
   {
 #if defined(MICRO_OS_PLUS_TRACE_MICRO_TEST_PLUS)
@@ -44,10 +82,26 @@ namespace micro_os_plus::micro_test_plus
     // The default test suite needs no registration.
   }
 
+  /**
+   * @details
+   * The destructor releases any resources associated with the
+   * `test_suite_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.
+   */
   test_suite_base::~test_suite_base ()
   {
   }
 
+  /**
+   * @details
+   * This method executes the test suite by invoking its associated callable
+   * object. If tracing is enabled, the function signature is output for
+   * diagnostic purposes. The method ensures that all test cases grouped within
+   * the suite are executed in an organised manner, supporting comprehensive
+   * and structured testing across all files and folders within the µTest++
+   * framework.
+   */
   void
   test_suite_base::run ()
   {
@@ -56,46 +110,108 @@ namespace micro_os_plus::micro_test_plus
 #endif // MICRO_OS_PLUS_TRACE_MICRO_TEST_PLUS
   }
 
+  /**
+   * @details
+   * This method marks the beginning of a test suite's execution. It resets the
+   * deferred begin flag and notifies the test reporter to start the suite,
+   * passing the suite's name. This ensures that test suite output is clearly
+   * delineated and properly initialised, supporting organised and readable
+   * reporting across all test cases and folders.
+   */
   void
   test_suite_base::begin_test_suite (void)
   {
+#if defined(_WIN32) || defined(CLOCK_MONOTONIC)
+#if defined(_WIN32)
+    timespec_get (&begin_time, TIME_UTC);
+#else
+    clock_gettime (CLOCK_MONOTONIC, &begin_time);
+#endif
+#endif
+
     process_deferred_begin = false;
 
-    reporter.begin_test_suite (name_);
+    reporter->begin_test_suite (name_);
   }
 
+  /**
+   * @details
+   * This method marks the end of a test suite's execution. If the suite's
+   * start was deferred, it ensures the suite is properly begun before
+   * finalising. The method then notifies the test reporter to conclude the
+   * suite, passing a reference to the suite instance. This guarantees that all
+   * results are accurately summarised and reported, supporting clear and
+   * organised test management across all test cases and folders.
+   */
   void
   test_suite_base::end_test_suite (void)
   {
     if (process_deferred_begin)
       {
+        reporter->begin_test (runner.test_suites_count ());
+
         begin_test_suite ();
       }
-    reporter.end_test_suite (*this);
+
+#if defined(_WIN32) || defined(CLOCK_MONOTONIC)
+#if defined(_WIN32)
+    timespec_get (&end_time, TIME_UTC);
+#else
+    clock_gettime (CLOCK_MONOTONIC, &end_time);
+#endif
+#endif
+    reporter->end_test_suite (*this);
   }
 
+  /**
+   * @details
+   * This method marks the beginning of a test case within the suite. If the
+   * start of the suite was deferred, it ensures the suite is properly begun
+   * before proceeding. The method sets the current test case name, increments
+   * the total number of test cases, resets the current test case statistics,
+   * and notifies the test reporter to begin the test case. This approach
+   * guarantees that each test case is clearly identified, accurately tracked,
+   * and properly reported across all test cases and folders.
+   */
   void
   test_suite_base::begin_test_case (const char* name)
   {
     if (process_deferred_begin)
       {
+        reporter->begin_test (runner.test_suites_count ());
+
         begin_test_suite ();
       }
 
     test_case_name_ = name;
-    ++test_cases_;
+    ++test_cases_count_;
 
     current_test_case = {};
 
-    reporter.begin_test_case (test_case_name_);
+    reporter->begin_test_case (test_case_name_);
   }
 
+  /**
+   * @details
+   * This method marks the end of a test case within the suite. It notifies the
+   * test reporter to conclude the test case, passing the current test case
+   * name. This ensures that the results of the test case are accurately
+   * finalised and clearly reported, supporting organised and reliable test
+   * management across all test cases and folders.
+   */
   void
   test_suite_base::end_test_case (void)
   {
-    reporter.end_test_case (test_case_name_);
+    reporter->end_test_case (test_case_name_);
   }
 
+  /**
+   * @details
+   * This method increments the count of successful checks for the test suite
+   * and the current test case. It ensures that each passing assertion is
+   * accurately recorded, supporting precise tracking and reporting of test
+   * outcomes across all test cases and folders.
+   */
   void
   test_suite_base::increment_successful (void)
   {
@@ -103,6 +219,13 @@ namespace micro_os_plus::micro_test_plus
     ++current_test_case.successful_checks;
   }
 
+  /**
+   * @details
+   * This method increments the count of failed checks for the test suite and
+   * the current test case. It ensures that each failing assertion is
+   * accurately recorded, supporting precise tracking and reporting of test
+   * outcomes across all test cases and folders.
+   */
   void
   test_suite_base::increment_failed (void)
   {
@@ -110,8 +233,49 @@ namespace micro_os_plus::micro_test_plus
     ++current_test_case.failed_checks;
   }
 
+#if defined(_WIN32) || defined(CLOCK_MONOTONIC)
+  /**
+   * @details
+   * Subtracts `begin_time` from `end_time` using monotonic clock arithmetic,
+   * handling the nanosecond borrow correctly, then splits the result into
+   * whole milliseconds and the sub-millisecond remainder expressed in
+   * microseconds (0–999).
+   */
+#pragma GCC diagnostic push
+#pragma GCC diagnostic ignored "-Wshadow"
+  void
+  test_suite_base::compute_elapsed_time (timespec& begin_time,
+                                         timespec& end_time,
+                                         long& milliseconds,
+                                         long& microseconds)
+  {
+    long long delta_ns = end_time.tv_nsec - begin_time.tv_nsec;
+    long long delta_s = end_time.tv_sec - begin_time.tv_sec;
+    if (delta_ns < 0)
+      {
+        delta_ns += 1000000000LL;
+        --delta_s;
+      }
+
+    // Split into milliseconds and microseconds.
+    const long long total_us = delta_s * 1000000LL + delta_ns / 1000LL;
+    milliseconds = static_cast<long> (total_us / 1000LL);
+    microseconds = static_cast<long> (total_us % 1000LL);
+  }
+#pragma GCC diagnostic pop
+
+#endif
+
   // ==========================================================================
 
+  /**
+   * @details
+   * This method executes the test suite by invoking the stored callable object
+   * associated with the suite. It ensures that all test cases registered
+   * within the suite are executed in sequence, supporting comprehensive and
+   * structured testing across all files and folders within the µTest++
+   * framework.
+   */
   void
   test_suite::run (void)
   {
@@ -119,6 +283,14 @@ namespace micro_os_plus::micro_test_plus
     callable_ ();
   }
 
+  /**
+   * @details
+   * The destructor releases any resources associated with the `test_suite`
+   * 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++ framework.
+   */
   test_suite::~test_suite ()
   {
 #if defined(MICRO_OS_PLUS_TRACE_MICRO_TEST_PLUS)