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

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

@@ -60,193 +60,174 @@ namespace micro_os_plus::micro_test_plus
 {
   // --------------------------------------------------------------------------
 
-  /**
-   * @brief Aggregated pass/fail/subtest counters for a node in the test tree.
-   *
-   * @details
-   * `runner_totals` records three counters that are maintained throughout a
-   * test session:
-   * - the number of checks that passed (`successful_checks_`),
-   * - the number of checks that failed (`failed_checks_`), and
-   * - the number of subtests that were executed (`executed_subtests_`).
-   *
-   * Every `test_node`-derived object (`runner`, `suite`, `subtest`) owns a
-   * `runner_totals` member and accumulates its counts in place. At the end
-   * of each suite or session the operator `+=` propagates the child totals
-   * up to the parent node.
-   *
-   * The class is non-copyable and non-movable to prevent accidental
-   * duplication of live counters.
-   *
-   * @headerfile micro-test-plus.h <micro-os-plus/micro-test-plus.h>
-   */
-  class runner_totals
+  namespace detail
   {
-  public:
-    /**
-     * @brief Default constructor. All counters are zero-initialised.
-     */
-    runner_totals () = default;
-
-    /**
-     * @brief Deleted copy constructor to prevent copying.
-     */
-    runner_totals (const runner_totals&) = delete;
-
-    /**
-     * @brief Deleted move constructor to prevent moving.
-     */
-    runner_totals (runner_totals&&) = delete;
-
-    /**
-     * @brief Deleted copy assignment operator to prevent copying.
-     */
-    runner_totals&
-    operator= (const runner_totals&) = delete;
-
-    /**
-     * @brief Deleted move assignment operator to prevent moving.
-     */
-    runner_totals&
-    operator= (runner_totals&&) = delete;
-
-    /**
-     * @brief Accumulates the totals from another instance into this one.
-     *
-     * @param other The instance whose totals are to be added.
-     * @return Reference to this instance.
-     */
-    runner_totals&
-    operator+= (const runner_totals& other) noexcept;
-
-    /**
-     * @brief Increments the successful-checks counter.
-     *
-     * @param count The number of successful checks to add (default 1).
-     * @par Returns
-     *   Nothing.
-     */
-    void
-    increment_successful_checks (size_t count = 1) noexcept
-    {
-      successful_checks_ += count;
-    }
-
-    /**
-     * @brief Increments the failed-checks counter.
-     *
-     * @param count The number of failed checks to add (default 1).
-     * @par Returns
-     *   Nothing.
-     */
-    void
-    increment_failed_checks (size_t count = 1) noexcept
-    {
-      failed_checks_ += count;
-    }
-
-    /**
-     * @brief Increments the executed-subtests counter.
-     *
-     * @param count The number of subtests to add (default 1).
-     * @par Returns
-     *   Nothing.
-     */
-    void
-    increment_executed_subtests (size_t count = 1) noexcept
-    {
-      executed_subtests_ += count;
-    }
+    // ========================================================================
 
     /**
-     * @brief Returns the number of checks that passed.
+     * @brief Aggregated pass/fail/subtest counters for a node in the test
+     * tree.
      *
-     * @par Parameters
-     *   None.
-     * @return The cumulative count of successful checks.
-     */
-    [[nodiscard]] size_t
-    successful_checks () const noexcept
-    {
-      return successful_checks_;
-    }
-
-    /**
-     * @brief Returns the number of checks that failed.
+     * @details
+     * `runner_totals` records three counters that are maintained throughout a
+     * test session:
+     * - the number of checks that passed (`successful_checks_`),
+     * - the number of checks that failed (`failed_checks_`), and
+     * - the number of subtests that were executed (`executed_subtests_`).
      *
-     * @par Parameters
-     *   None.
-     * @return The cumulative count of failed checks.
-     */
-    [[nodiscard]] size_t
-    failed_checks () const noexcept
-    {
-      return failed_checks_;
-    }
-
-    /**
-     * @brief Returns the total number of checks executed.
+     * Every `test_node`-derived object (`runner`, `suite`, `subtest`) owns a
+     * `runner_totals` member and accumulates its counts in place. At the end
+     * of each suite or session the operator `+=` propagates the child totals
+     * up to the parent node.
      *
-     * @par Parameters
-     *   None.
-     * @return The sum of successful and failed checks.
-     */
-    [[nodiscard]] size_t
-    executed_checks () const noexcept
-    {
-      return successful_checks_ + failed_checks_;
-    }
-
-    /**
-     * @brief Returns the number of subtests that were executed.
+     * The class is non-copyable and non-movable to prevent accidental
+     * duplication of live counters.
      *
-     * @par Parameters
-     *   None.
-     * @return The cumulative count of executed subtests.
+     * @headerfile micro-test-plus.h <micro-os-plus/micro-test-plus.h>
      */
-    [[nodiscard]] size_t
-    executed_subtests () const noexcept
+    class runner_totals
     {
-      return executed_subtests_;
-    }
-
-    /**
-     * @brief Checks whether all executed checks were successful.
-     *
-     * @par Parameters
-     *	None.
-     * @retval true  No checks failed.
-     * @retval false At least one check failed.
-     *
-     * @details
-     * A runner with no checks at all is considered successful, as it
-     * did not fail any check.
-     */
-    [[nodiscard]] bool
-    was_successful (void) const noexcept
-    {
-      return failed_checks_ == 0;
-    }
-
-  protected:
-    /**
-     * @brief Total number of successful checks.
-     */
-    size_t successful_checks_ = 0;
-
-    /**
-     * @brief Total number of failed checks.
-     */
-    size_t failed_checks_ = 0;
-
-    /**
-     * @brief Total number of tests executed.
-     */
-    size_t executed_subtests_ = 0;
-  };
+    public:
+      /**
+       * @brief Default constructor. All counters are zero-initialised.
+       */
+      runner_totals () = default;
+
+      /**
+       * @brief Deleted copy constructor to prevent copying.
+       */
+      runner_totals (const runner_totals&) = delete;
+
+      /**
+       * @brief Deleted move constructor to prevent moving.
+       */
+      runner_totals (runner_totals&&) = delete;
+
+      /**
+       * @brief Deleted copy assignment operator to prevent copying.
+       */
+      runner_totals&
+      operator= (const runner_totals&)
+          = delete;
+
+      /**
+       * @brief Deleted move assignment operator to prevent moving.
+       */
+      runner_totals&
+      operator= (runner_totals&&)
+          = delete;
+
+      /**
+       * @brief Accumulates the totals from another instance into this one.
+       *
+       * @param other The instance whose totals are to be added.
+       * @return Reference to this instance.
+       */
+      runner_totals&
+      operator+= (const runner_totals& other) noexcept;
+
+      /**
+       * @brief Increments the successful-checks counter.
+       *
+       * @param count The number of successful checks to add (default 1).
+       * @par Returns
+       *   Nothing.
+       */
+      void
+      increment_successful_checks (size_t count = 1) noexcept;
+
+      /**
+       * @brief Increments the failed-checks counter.
+       *
+       * @param count The number of failed checks to add (default 1).
+       * @par Returns
+       *   Nothing.
+       */
+      void
+      increment_failed_checks (size_t count = 1) noexcept;
+
+      /**
+       * @brief Increments the executed-subtests counter.
+       *
+       * @param count The number of subtests to add (default 1).
+       * @par Returns
+       *   Nothing.
+       */
+      void
+      increment_executed_subtests (size_t count = 1) noexcept;
+
+      /**
+       * @brief Returns the number of checks that passed.
+       *
+       * @par Parameters
+       *   None.
+       * @return The cumulative count of successful checks.
+       */
+      [[nodiscard]] size_t
+      successful_checks () const noexcept;
+
+      /**
+       * @brief Returns the number of checks that failed.
+       *
+       * @par Parameters
+       *   None.
+       * @return The cumulative count of failed checks.
+       */
+      [[nodiscard]] size_t
+      failed_checks () const noexcept;
+
+      /**
+       * @brief Returns the total number of checks executed.
+       *
+       * @par Parameters
+       *   None.
+       * @return The sum of successful and failed checks.
+       */
+      [[nodiscard]] size_t
+      executed_checks () const noexcept;
+
+      /**
+       * @brief Returns the number of subtests that were executed.
+       *
+       * @par Parameters
+       *   None.
+       * @return The cumulative count of executed subtests.
+       */
+      [[nodiscard]] size_t
+      executed_subtests () const noexcept;
+
+      /**
+       * @brief Checks whether all executed checks were successful.
+       *
+       * @par Parameters
+       *	None.
+       * @retval true  No checks failed.
+       * @retval false At least one check failed.
+       */
+      [[nodiscard]] bool
+      was_successful (void) const noexcept;
+
+    protected:
+      /**
+       * @brief Total number of successful checks.
+       */
+      size_t successful_checks_ = 0;
+
+      /**
+       * @brief Total number of failed checks.
+       */
+      size_t failed_checks_ = 0;
+
+      /**
+       * @brief Total number of tests executed.
+       */
+      size_t executed_subtests_ = 0;
+    };
+
+    // ------------------------------------------------------------------------
+  } // namespace detail
 
   // --------------------------------------------------------------------------
-
 } // namespace micro_os_plus::micro_test_plus
 
 #if defined(__GNUC__)
@@ -257,6 +238,11 @@ namespace micro_os_plus::micro_test_plus
 
 #endif // __cplusplus
 
+// ============================================================================
+// Templates & constexpr implementations.
+
+#include "inlines/runner-totals-inlines.h"
+
 // ----------------------------------------------------------------------------
 
 #endif // MICRO_TEST_PLUS_TEST_RUNNER_TOTALS_H_

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

@@ -53,10 +53,11 @@
 
 #include <functional>
 #include <memory>
+#include <string>
 
-#include "reporter.h"
 #include "timings.h"
 #include "test.h"
+#include "reflection.h"
 
 // ----------------------------------------------------------------------------
 
@@ -78,6 +79,12 @@ namespace micro_os_plus::micro_test_plus
 {
   // --------------------------------------------------------------------------
 
+  class suite;
+  class top_suite;
+  class reporter;
+
+  // ==========================================================================
+
   /**
    * @ingroup micro-test-plus-runners
    * @brief The test runner for the µTest++ framework.
@@ -100,14 +107,24 @@ namespace micro_os_plus::micro_test_plus
    *
    * @headerfile micro-test-plus.h <micro-os-plus/micro-test-plus.h>
    */
-  class runner : public test_node
+  class runner : public detail::test_node
   {
   public:
     /**
-     * @brief Default constructor for the runner class.
+     * @brief Constructor for the runner class.
      *
-     * @details
-     * The rule of five is enforced to prevent accidental copying or moving.
+     * @par Parameters
+     *   None.
+     */
+    runner (void);
+
+    /**
+     * @brief Deprecated constructor for the runner class.
+     *
+     * @param [in] top_suite_name The name given to the implicit top suite.
+     * Defaults to an empty string.
+     *
+     * @deprecated Use the anonymous constructor.
      */
     runner (const char* top_suite_name);
 
@@ -125,13 +142,15 @@ namespace micro_os_plus::micro_test_plus
      * @brief Deleted copy assignment operator to prevent copying.
      */
     runner&
-    operator= (const runner&) = delete;
+    operator= (const runner&)
+        = delete;
 
     /**
      * @brief Deleted move assignment operator to prevent moving.
      */
     runner&
-    operator= (runner&&) = delete;
+    operator= (runner&&)
+        = delete;
 
     /**
      * @brief Destructor for the runner class.
@@ -143,10 +162,12 @@ namespace micro_os_plus::micro_test_plus
      *
      * @param argc The argument count from main().
      * @param argv The argument vector from main().
+     * @param top_suite_name The name given to the implicit top suite. Defaults
+     * to an empty string.
      * @return Reference to the top-level test suite.
      */
     class suite&
-    initialise (int argc, char* argv[]);
+    initialise (int argc, char* argv[], const char* top_suite_name = "");
 
     /**
      * @brief Returns 0 if all tests were successful, 1 otherwise.
@@ -195,11 +216,6 @@ namespace micro_os_plus::micro_test_plus
     /**
      * @brief Returns the total count of registered test suites.
      *
-     * @details
-     * The base implementation counts only the dynamically registered child
-     * suites plus the implicit top suite. `static_runner` overrides this
-     * method to also include statically registered suites.
-     *
      * @par Parameters
      *	 None.
      * @return The total number of test suites managed by this runner.
@@ -212,14 +228,10 @@ namespace micro_os_plus::micro_test_plus
      *
      * @par Parameters
      *	 None.
-     * @par Returns
-     *   Reference to the test reporter.
+     * @return Reference to the test reporter.
      */
     [[nodiscard]] class reporter&
-    reporter (void) const noexcept
-    {
-      return *reporter_;
-    }
+    reporter (void) const noexcept;
 
     /**
      * @brief Gets the timings for this runner.
@@ -228,11 +240,8 @@ namespace micro_os_plus::micro_test_plus
      *	 None.
      * @return A reference to the timestamps instance.
      */
-    [[nodiscard]] timestamps&
-    timings () noexcept
-    {
-      return timings_;
-    }
+    [[nodiscard]] detail::timestamps&
+    timings () noexcept;
 
     /**
      * @brief Gets the timings for this runner (const overload).
@@ -241,11 +250,8 @@ namespace micro_os_plus::micro_test_plus
      *	 None.
      * @return A const reference to the timestamps instance.
      */
-    [[nodiscard]] const timestamps&
-    timings () const noexcept
-    {
-      return timings_;
-    }
+    [[nodiscard]] const detail::timestamps&
+    timings () const noexcept;
 
     /**
      * @brief Returns the count of test suites.
@@ -261,11 +267,6 @@ namespace micro_os_plus::micro_test_plus
     /**
      * @brief Runs all registered test suites.
      *
-     * @details
-     * The base implementation runs all dynamically registered child suites.
-     * `static_runner` overrides this method to additionally run all
-     * statically registered suites.
-     *
      * @par Parameters
      *	 None.
      */
@@ -307,7 +308,12 @@ namespace micro_os_plus::micro_test_plus
     /**
      * @brief Timings for this runner.
      */
-    timestamps timings_;
+    detail::timestamps timings_;
+
+    /**
+     * @brief Owned storage for the implicit top-suite name.
+     */
+    std::string top_suite_name_;
   };
 
   // ==========================================================================
@@ -338,10 +344,21 @@ namespace micro_os_plus::micro_test_plus
   class static_runner final : public runner
   {
   public:
+    /**
+     * @brief Constructor for the runner class.
+     *
+     * @par Parameters
+     *   None.
+     */
+    static_runner (void);
+
     /**
      * @brief Constructs the static runner with a top-suite name.
      *
      * @param top_suite_name The name of the implicit top-level suite.
+     * Defaults to an empty string.
+     *
+     * @deprecated Use the anonymous constructor.
      */
     static_runner (const char* top_suite_name);
 
@@ -359,13 +376,15 @@ namespace micro_os_plus::micro_test_plus
      * @brief Deleted copy assignment operator to prevent copying.
      */
     static_runner&
-    operator= (const static_runner&) = delete;
+    operator= (const static_runner&)
+        = delete;
 
     /**
      * @brief Deleted move assignment operator to prevent moving.
      */
     static_runner&
-    operator= (static_runner&&) = delete;
+    operator= (static_runner&&)
+        = delete;
 
     /**
      * @brief Destructor for the static_runner class.
@@ -408,11 +427,6 @@ namespace micro_os_plus::micro_test_plus
     /**
      * @brief Runs all child suites, including statically registered ones.
      *
-     * @details
-     * Overrides `runner::run_suites_()` to first invoke the base
-     * implementation (dynamic suites), then iterate over all statically
-     * registered suites and run them.
-     *
      * @par Parameters
      *	 None.
      */
@@ -446,6 +460,11 @@ namespace micro_os_plus::micro_test_plus
 
 #endif // __cplusplus
 
+// ============================================================================
+// Templates & constexpr implementations.
+
+#include "inlines/runner-inlines.h"
+
 // ----------------------------------------------------------------------------
 
 #endif // MICRO_TEST_PLUS_TEST_RUNNER_H_