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

package/include/micro-os-plus/micro-test-plus/{test-reporter-basic.h → reporter-human.h}

@@ -17,18 +17,18 @@
 
 /**
  * @file
- * @brief C++ header file with declarations for the µTest++ basic test
+ * @brief C++ header file with declarations for the µTest++ human test
  * reporter.
  *
  * @details
- * This header provides the declaration for `test_reporter_basic`, the default
- * concrete implementation of the `test_reporter` abstract interface. It
+ * This header provides the declaration for `reporter_human`, the default
+ * concrete implementation of the `reporter` abstract interface. It
  * formats and presents test results using `printf`-based standard output,
  * accumulating output in an internal string buffer and supporting
  * colour-coded diagnostics and multiple verbosity levels.
  *
  * Users who require custom output behaviour (e.g. redirecting to a serial
- * port on bare-metal targets) may derive a new class from `test_reporter`
+ * port on bare-metal targets) may derive a new class from `reporter`
  * instead of using this class.
  *
  * All definitions reside within the `micro_os_plus::micro_test_plus`
@@ -52,7 +52,8 @@
 
 // ----------------------------------------------------------------------------
 
-#include "test-reporter.h"
+#include "reporter.h"
+#include "reflection.h"
 
 // ----------------------------------------------------------------------------
 
@@ -64,22 +65,30 @@
 #endif
 #endif
 
+// ============================================================================
+
 namespace micro_os_plus::micro_test_plus
 {
   // --------------------------------------------------------------------------
 
+  class runner;
+  class suite;
+  class subtest;
+
+  // ==========================================================================
+
   /**
-   * @brief Basic (standard output) implementation of `test_reporter`.
+   * @brief Human (standard output) implementation of `reporter`.
    *
    * @details
-   * `test_reporter_basic` provides the default concrete implementation of the
-   * `test_reporter` abstract interface, formatting and presenting test results
+   * `reporter_human` provides the default concrete implementation of the
+   * `reporter` abstract interface, formatting and presenting test results
    * using `printf`-based output. It accumulates output in an internal string
    * buffer and writes it to the standard output stream, supporting
    * colour-coded diagnostics and multiple verbosity levels.
    *
    * Users who require custom output behaviour (e.g. redirecting to a serial
-   * port on bare-metal targets) may derive a new class from `test_reporter`
+   * port on bare-metal targets) may derive a new class from `reporter`
    * and supply an instance via the `reporter` global pointer before calling
    * `initialize()`.
    *
@@ -89,186 +98,183 @@ namespace micro_os_plus::micro_test_plus
    *
    * @headerfile micro-test-plus.h <micro-os-plus/micro-test-plus.h>
    */
-  class test_reporter_basic final : public test_reporter
+  class reporter_human final : public reporter
   {
   public:
     /**
-     * @brief Constructor for the test_reporter_basic class.
+     * @brief Constructor for the reporter_human class.
      *
-     * @details
-     * The rule of five is enforced to prevent accidental copying or moving.
+     * @param argvs Owning pointer to the command-line arguments vector;
+     * the reporter takes ownership via move.
      */
-    test_reporter_basic ();
+    reporter_human (std::unique_ptr<std::vector<std::string_view>> argvs);
 
     /**
      * @brief Deleted copy constructor to prevent copying.
      */
-    test_reporter_basic (const test_reporter_basic&) = delete;
+    reporter_human (const reporter_human&) = delete;
 
     /**
      * @brief Deleted move constructor to prevent moving.
      */
-    test_reporter_basic (test_reporter_basic&&) = delete;
+    reporter_human (reporter_human&&) = delete;
 
     /**
      * @brief Deleted copy assignment operator to prevent copying.
      */
-    test_reporter_basic&
-    operator= (const test_reporter_basic&)
+    reporter_human&
+    operator= (const reporter_human&)
         = delete;
 
     /**
      * @brief Deleted move assignment operator to prevent moving.
      */
-    test_reporter_basic&
-    operator= (test_reporter_basic&&)
+    reporter_human&
+    operator= (reporter_human&&)
         = delete;
 
     /**
-     * @brief Destructor for the test_reporter_basic class.
+     * @brief Destructor for the reporter_human class.
      */
-    ~test_reporter_basic () override = default;
+    ~reporter_human () override;
 
-    /**
-     * @brief Inserts a line ending into the output buffer.
-     *
-     * @par Parameters
-     *	 None.
-     * @par Returns
-     *   Nothing.
-     */
-    void
-    endline (void) override;
+    // ------------------------------------------------------------------------
 
     /**
-     * @brief Mark the beginning of a test case.
+     * @brief Output operator for the `indent_t` manipulator.
      *
-     * @param name The name of the test case.
-     * @par Returns
-     *   Nothing.
+     * @param m The indentation manipulator produced by `indent(n)`.
+     * @return Reference to the current reporter instance.
      */
-    void
-    begin_test_case (const char* name) override;
+    reporter_human&
+    operator<< (detail::indent_t m);
+
+    // Bring base class operator<< overloads into scope to prevent name hiding.
+    using reporter::operator<<;
+
+    // ------------------------------------------------------------------------
 
     /**
-     * @brief Mark the end of a test case.
+     * @brief Mark the beginning of a test session.
      *
-     * @param name The name of the test case.
+     * @param runner Reference to the test runner.
      * @par Returns
      *   Nothing.
      */
     void
-    end_test_case (const char* name) override;
+    begin_session (runner& runner) override;
 
     /**
-     * @brief Mark the beginning of a test suite.
+     * @brief Mark the end of a test session.
      *
-     * @param name The name of the test suite.
+     * @param runner Reference to the test runner.
      * @par Returns
      *   Nothing.
      */
     void
-    begin_test_suite (const char* name) override;
+    end_session (runner& runner) override;
 
     /**
-     * @brief Mark the end of a test suite.
+     * @brief Mark the beginning of a suite.
      *
-     * @param suite Reference to the test suite base.
+     * @param suite Reference to the suite.
      * @par Returns
      *   Nothing.
      */
-    void
-    end_test_suite (test_suite_base& suite) override;
+    virtual void
+    begin_suite (suite& suite) override;
 
     /**
-     * @brief Mark the beginning of a test.
+     * @brief Mark the end of a test suite.
      *
-     * @param test_suites_count The number of test suites, or zero if unknown.
+     * @param suite Reference to the test suite.
      * @par Returns
      *   Nothing.
      */
-    void
-    begin_test (size_t test_suites_count) override;
+    virtual void
+    end_suite (suite& suite) override;
 
     /**
-     * @brief Mark the end of a test.
+     * @brief Mark the beginning of a subtest.
      *
-     * @param runner Reference to the test runner.
+     * @param subtest Reference to the subtest.
      * @par Returns
      *   Nothing.
      */
-    void
-    end_test (test_runner& runner) override;
+    virtual void
+    begin_subtest (subtest& subtest) override;
 
     /**
-     * @brief Flush the current buffered content.
+     * @brief Mark the end of a subtest.
      *
-     * @par Parameters
-     *	 None.
+     * @param subtest Reference to the subtest.
      * @par Returns
      *   Nothing.
      */
-    void
-    flush (void) override;
+    virtual void
+    end_subtest (subtest& subtest) override;
 
     /**
-     * @brief Output the current buffered content.
+     * @brief Returns an empty comment prefix string.
      *
      * @par Parameters
      *	 None.
-     * @par Returns
-     *   Nothing.
+     * @return An empty string, as the human-readable format does not
+     * use a comment prefix.
      */
-    void
-    output (void) override;
+    virtual const char*
+    get_comment_prefix (void) override;
 
   protected:
     /**
      * @brief Outputs the prefix for a passing condition.
      *
      * @param message The message to display.
+     * @param subtest The subtest that owns this check.
      * @par Returns
      *   Nothing.
      */
     void
-    output_pass_prefix_ (std::string& message) override;
+    output_pass_prefix_ (std::string& message, subtest& subtest) override;
 
     /**
      * @brief Outputs the suffix for a passing condition.
      *
-     * @par Parameters
-     *	 None.
+     * @param subtest The subtest that owns this check.
      * @par Returns
      *   Nothing.
      */
     void
-    output_pass_suffix_ (void) override;
+    output_pass_suffix_ (subtest& subtest) override;
 
     /**
      * @brief Outputs the prefix for a failing condition.
      *
      * @param message The message to display.
-     * @param hasExpression Whether the failure is associated with an
+     * @param has_expression Whether the failure is associated with an
      * expression.
      * @param location The source location of the failure.
+     * @param subtest The subtest that owns this check.
      * @par Returns
      *   Nothing.
      */
     void
-    output_fail_prefix_ (std::string& message, const bool hasExpression,
-                         const reflection::source_location& location) override;
+    output_fail_prefix_ (std::string& message, const bool has_expression,
+                         const reflection::source_location& location,
+                         subtest& subtest) override;
 
     /**
      * @brief Outputs the suffix for a failing condition.
      *
      * @param location The source location of the failure.
      * @param abort Whether to abort execution after failure.
+     * @param subtest The subtest that owns this check.
      * @par Returns
      *   Nothing.
      */
     void
     output_fail_suffix_ (const reflection::source_location& location,
-                         bool abort) override;
+                         bool abort, subtest& subtest) override;
   };
 
   // --------------------------------------------------------------------------

package/include/micro-os-plus/micro-test-plus/{test-reporter-tap.h → reporter-tap.h}

@@ -20,8 +20,8 @@
  * @brief C++ header file with declarations for the µTest++ TAP test reporter.
  *
  * @details
- * This header provides the declaration for `test_reporter_tap`, a concrete
- * implementation of the `test_reporter` abstract interface that formats test
+ * This header provides the declaration for `reporter_tap`, a concrete
+ * implementation of the `reporter` abstract interface that formats test
  * results according to the Test Anything Protocol (TAP).
  *
  * All definitions reside within the `micro_os_plus::micro_test_plus`
@@ -45,7 +45,8 @@
 
 // ----------------------------------------------------------------------------
 
-#include "test-reporter.h"
+#include "reporter.h"
+#include "reflection.h"
 
 // ----------------------------------------------------------------------------
 
@@ -57,21 +58,29 @@
 #endif
 #endif
 
+// ============================================================================
+
 namespace micro_os_plus::micro_test_plus
 {
   // --------------------------------------------------------------------------
 
+  class runner;
+  class suite;
+  class subtest;
+
+  // ==========================================================================
+
   /**
-   * @brief TAP (Test Anything Protocol) implementation of `test_reporter`.
+   * @brief TAP (Test Anything Protocol) implementation of `reporter`.
    *
    * @details
-   * `test_reporter_tap` provides a concrete implementation of the
-   * `test_reporter` abstract interface that formats test results according to
+   * `reporter_tap` provides a concrete implementation of the
+   * `reporter` abstract interface that formats test results according to
    * the Test Anything Protocol (TAP). It accumulates output in an internal
    * string buffer and writes it to the standard output stream.
    *
    * Users who require custom output behaviour (e.g. redirecting to a serial
-   * port on bare-metal targets) may derive a new class from `test_reporter`
+   * port on bare-metal targets) may derive a new class from `reporter`
    * and supply an instance via the `reporter` global pointer before calling
    * `initialize()`.
    *
@@ -81,186 +90,183 @@ namespace micro_os_plus::micro_test_plus
    *
    * @headerfile micro-test-plus.h <micro-os-plus/micro-test-plus.h>
    */
-  class test_reporter_tap final : public test_reporter
+  class reporter_tap final : public reporter
   {
   public:
     /**
-     * @brief Default constructor for the test_reporter_tap class.
+     * @brief Constructor for the reporter_tap class.
      *
-     * @details
-     * The rule of five is enforced to prevent accidental copying or moving.
+     * @param argvs Owning pointer to the command-line arguments vector;
+     * the reporter takes ownership via move.
      */
-    test_reporter_tap () = default;
+    reporter_tap (std::unique_ptr<std::vector<std::string_view>> argvs);
 
     /**
      * @brief Deleted copy constructor to prevent copying.
      */
-    test_reporter_tap (const test_reporter_tap&) = delete;
+    reporter_tap (const reporter_tap&) = delete;
 
     /**
      * @brief Deleted move constructor to prevent moving.
      */
-    test_reporter_tap (test_reporter_tap&&) = delete;
+    reporter_tap (reporter_tap&&) = delete;
 
     /**
      * @brief Deleted copy assignment operator to prevent copying.
      */
-    test_reporter_tap&
-    operator= (const test_reporter_tap&)
+    reporter_tap&
+    operator= (const reporter_tap&)
         = delete;
 
     /**
      * @brief Deleted move assignment operator to prevent moving.
      */
-    test_reporter_tap&
-    operator= (test_reporter_tap&&)
+    reporter_tap&
+    operator= (reporter_tap&&)
         = delete;
 
     /**
-     * @brief Destructor for the test_reporter_tap class.
+     * @brief Destructor for the reporter_tap class.
      */
-    ~test_reporter_tap () override = default;
+    ~reporter_tap () override;
+
+    // ------------------------------------------------------------------------
 
     /**
-     * @brief Inserts a line ending into the output buffer.
+     * @brief Output operator for the `indent_t` manipulator.
      *
-     * @par Parameters
-     *	 None.
-     * @par Returns
-     *   Nothing.
+     * @param m The indentation manipulator produced by `indent(n)`.
+     * @return Reference to the current reporter instance.
      */
-    void
-    endline (void) override;
+    reporter_tap&
+    operator<< (detail::indent_t m);
+
+    // Bring base class operator<< overloads into scope to prevent name hiding.
+    using reporter::operator<<;
+
+    // ------------------------------------------------------------------------
 
     /**
-     * @brief Mark the beginning of a test case.
+     * @brief Mark the beginning of a test session.
      *
-     * @param name The name of the test case.
+     * @param runner Reference to the test runner.
      * @par Returns
      *   Nothing.
      */
     void
-    begin_test_case (const char* name) override;
+    begin_session (runner& runner) override;
 
     /**
-     * @brief Mark the end of a test case.
+     * @brief Mark the end of a test session.
      *
-     * @param name The name of the test case.
+     * @param runner Reference to the test runner.
      * @par Returns
      *   Nothing.
      */
     void
-    end_test_case (const char* name) override;
+    end_session (runner& runner) override;
 
     /**
      * @brief Mark the beginning of a test suite.
      *
-     * @param name The name of the test suite.
+     * @param suite Reference to the test suite.
      * @par Returns
      *   Nothing.
      */
-    void
-    begin_test_suite (const char* name) override;
+    virtual void
+    begin_suite (suite& suite) override;
 
     /**
      * @brief Mark the end of a test suite.
      *
-     * @param suite Reference to the test suite base.
-     * @par Returns
-     *   Nothing.
-     */
-    void
-    end_test_suite (test_suite_base& suite) override;
-
-    /**
-     * @brief Mark the beginning of a test.
-     *
-     * @param test_suites_count The number of test suites, or zero if unknown.
+     * @param suite Reference to the test suite.
      * @par Returns
      *   Nothing.
      */
-    void
-    begin_test (size_t test_suites_count) override;
+    virtual void
+    end_suite (suite& suite) override;
 
     /**
-     * @brief Mark the end of a test.
+     * @brief Mark the beginning of a subtest.
      *
-     * @param runner Reference to the test runner.
+     * @param subtest Reference to the subtest.
      * @par Returns
      *   Nothing.
      */
-    void
-    end_test (test_runner& runner) override;
+    virtual void
+    begin_subtest (subtest& subtest) override;
 
     /**
-     * @brief Flush the current buffered content.
+     * @brief Mark the end of a subtest.
      *
-     * @par Parameters
-     *	 None.
+     * @param subtest Reference to the subtest.
      * @par Returns
      *   Nothing.
      */
-    void
-    flush (void) override;
+    virtual void
+    end_subtest (subtest& subtest) override;
 
     /**
-     * @brief Output the current buffered content.
+     * @brief Returns the TAP comment prefix string `"# "`.
      *
      * @par Parameters
      *	 None.
-     * @par Returns
-     *   Nothing.
+     * @return The string `"# "`, used to prefix comment lines in TAP
+     * output.
      */
-    void
-    output (void) override;
+    virtual const char*
+    get_comment_prefix (void) override;
 
   protected:
     /**
      * @brief Outputs the prefix for a passing condition.
      *
      * @param message The message to display.
+     * @param subtest The subtest that owns this check.
      * @par Returns
      *   Nothing.
      */
     void
-    output_pass_prefix_ (std::string& message) override;
+    output_pass_prefix_ (std::string& message, subtest& subtest) override;
 
     /**
      * @brief Outputs the suffix for a passing condition.
      *
-     * @par Parameters
-     *	 None.
+     * @param subtest The subtest that owns this check.
      * @par Returns
      *   Nothing.
      */
     void
-    output_pass_suffix_ (void) override;
+    output_pass_suffix_ (subtest& subtest) override;
 
     /**
      * @brief Outputs the prefix for a failing condition.
      *
      * @param message The message to display.
-     * @param hasExpression Whether the failure is associated with an
+     * @param has_expression Whether the failure is associated with an
      * expression.
      * @param location The source location of the failure.
+     * @param subtest The subtest that owns this check.
      * @par Returns
      *   Nothing.
      */
     void
-    output_fail_prefix_ (std::string& message, const bool hasExpression,
-                         const reflection::source_location& location) override;
+    output_fail_prefix_ (std::string& message, const bool has_expression,
+                         const reflection::source_location& location,
+                         subtest& subtest) override;
 
     /**
      * @brief Outputs the suffix for a failing condition.
      *
      * @param location The source location of the failure.
      * @param abort Whether to abort execution after failure.
+     * @param subtest The subtest that owns this check.
      * @par Returns
      *   Nothing.
      */
     void
     output_fail_suffix_ (const reflection::source_location& location,
-                         bool abort) override;
+                         bool abort, subtest& subtest) override;
   };
 
   // --------------------------------------------------------------------------