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

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

@@ -54,12 +54,13 @@
 
 // ----------------------------------------------------------------------------
 
-// #include <functional>
+#include <cstdio>
 #include <string_view>
 #include <string>
+#include <memory>
+#include <vector>
 
 #include "type-traits.h"
-#include "test-suite.h"
 #include "detail.h"
 
 // ----------------------------------------------------------------------------
@@ -74,16 +75,18 @@
 #endif
 #endif
 
+// =============================================================================
+
 namespace micro_os_plus::micro_test_plus
 {
   // --------------------------------------------------------------------------
 
   /**
-   * @struct colors
+   * @struct colours
    * @brief Colours used to highlight pass and fail results in test reports.
    *
    * @details
-   * The `colors` structure defines ANSI escape sequences for terminal output,
+   * The `colours` structure defines ANSI escape sequences for terminal output,
    * enabling colour-coded highlighting of test outcomes. The `pass` member
    * specifies the colour for successful results (typically green), while the
    * `fail` member specifies the colour for failed results (typically red). The
@@ -93,27 +96,29 @@ namespace micro_os_plus::micro_test_plus
    * by making it immediately apparent which tests have passed or failed,
    * thereby improving the overall user experience when reviewing test results.
    *
-   * @var colors::none
+   * @var colours::none
    * ANSI escape sequence to reset the terminal colour to default.
-   * @var colors::pass
+   * @var colours::pass
    * ANSI escape sequence to set the terminal colour for passing results
    * (green).
-   * @var colors::fail
+   * @var colours::fail
    * ANSI escape sequence to set the terminal colour for failing results (red).
    *
    * @headerfile micro-test-plus.h <micro-os-plus/micro-test-plus.h>
    */
-  struct colors
+  struct colours
   {
-    const char* none = ""; /**< @brief Default colour. */
-    const char* pass = ""; /**< @brief Green colour. */
-    const char* fail = ""; /**< @brief Red colour. */
+    const char* none = ""; /**< @brief Terminal colour reset sequence. */
+    const char* pass
+        = ""; /**< @brief Terminal colour sequence for passing tests. */
+    const char* fail
+        = ""; /**< @brief Terminal colour sequence for failing tests. */
   };
 
-  const colors colors_red_green = {
-    "\033[0m", /**< @brief Default colour. */
-    "\033[32m", /**< @brief Green colour. */
-    "\033[31m" /**< @brief Red colour. */
+  inline constexpr colours colours_red_green = {
+    "\033[0m", /**< @brief Terminal colour reset sequence. */
+    "\033[32m", /**< @brief Green colour sequence for passing tests. */
+    "\033[31m" /**< @brief Red colour sequence for failing tests. */
   };
 
   /**
@@ -139,43 +144,50 @@ namespace micro_os_plus::micro_test_plus
                    detail. */
   };
 
-  /**
-   * @brief Type alias for the verbosity enumeration used in test reporting.
-   *
-   * @details
-   * The `verbosity_t` type alias provides a convenient shorthand for referring
-   * to the `verbosity` enumeration, which defines the available levels of
-   * detail for test output within the reporting system.
-   *
-   * Using this alias improves code readability and consistency throughout the
-   * framework, especially when specifying or configuring verbosity levels for
-   * test reporters.
-   */
-  typedef verbosity verbosity_t;
-
-  // Forward definition.
-  class test_reporter;
+  // Forward definitions.
+  class reporter;
+  class runner;
 
   /**
    * @brief Output stream manipulator for ending a line in test reports.
    *
-   * @param stream Reference to the `test_reporter` instance.
-   * @return Reference to the same `test_reporter` instance, enabling chaining
+   * @param stream Reference to the `reporter` instance.
+   * @return Reference to the same `reporter` instance, enabling chaining
    * of output operations.
    */
-  test_reporter&
-  endl (test_reporter& stream);
+  reporter&
+  endl (reporter& stream);
 
-  // Requires events::assertion_* for  and detailed operators.
+  /**
+   * @brief Parameterised stream manipulator for outputting indentation.
+   *
+   * @details
+   * Holds the indentation level; used with `operator<<` on `reporter`
+   * so that `*this << indent(n) << "text"` works naturally in chains.
+   */
+  struct indent_t
+  {
+    size_t level; /**< @brief Number of four-space indentation levels. */
+  };
 
-  class test_runner;
+  /**
+   * @brief Factory function that creates an `indent_t` manipulator.
+   *
+   * @param level The number of four-space indentation levels.
+   * @return An `indent_t` value for use with `operator<<`.
+   */
+  [[nodiscard]] inline indent_t
+  indent (size_t level)
+  {
+    return { level };
+  }
 
   /**
    * @brief Reporter to display test results, including operand values and
    * types for failures.
    *
    * @details
-   * The `test_reporter` class is responsible for formatting and presenting
+   * The `reporter` class is responsible for formatting and presenting
    * test results within the µTest++ framework. It provides a comprehensive
    * suite of output operators for a wide range of data types, containers, and
    * comparator expressions, enabling detailed and informative reporting of
@@ -187,7 +199,7 @@ namespace micro_os_plus::micro_test_plus
    * output to distinguish between successful and failed tests, thereby
    * enhancing the clarity and professionalism of test reports.
    *
-   * The `test_reporter` also offers methods for reporting the commencement and
+   * The `reporter` also offers methods for reporting the commencement and
    * completion of test cases and suites, as well as for handling pass and fail
    * conditions. Additional features include output stream manipulators,
    * support for exception-related expressions, and configurable formatting
@@ -199,196 +211,184 @@ namespace micro_os_plus::micro_test_plus
    *
    * @headerfile micro-test-plus.h <micro-os-plus/micro-test-plus.h>
    */
-  class test_reporter
+  class reporter
   {
   public:
     /**
-     * @brief Default constructor for the test_reporter class.
+     * @brief Constructor for the reporter class.
+     *
+     * @details
+     * Parses the command-line arguments to determine the desired verbosity
+     * level and applies it to the reporter. The `--verbose`, `--quiet`, and
+     * `--silent` options are recognised.
+     *
+     * @param argvs Owning pointer to the command-line arguments vector;
+     * the reporter takes ownership via move.
      */
-    virtual ~test_reporter ();
+    reporter (std::unique_ptr<std::vector<std::string_view>> argvs);
 
     /**
-     * @brief Selects the appropriate colour code based on a condition.
-     *
-     * @param cond Boolean value indicating pass (true) or fail (false).
-     * @return The corresponding ANSI colour code as a string.
-     *
-     * @details
-     * Returns the ANSI colour code for pass or fail, depending on the boolean
-     * condition provided.
+     * @brief Virtual destructor for the reporter class.
      */
-    [[nodiscard]] inline auto
-    color (const bool cond)
-    {
-      return cond ? colors_.pass : colors_.fail;
-    }
+    virtual ~reporter ();
 
     /**
      * @brief Output operator for std::string_view.
      *
      * @param sv The string view to output.
-     * @return Reference to the current test_reporter instance.
+     * @return Reference to the current reporter instance.
      */
-    test_reporter&
+    reporter&
     operator<< (std::string_view sv);
 
     /**
      * @brief Output operator for a single character.
      *
      * @param c The character to output.
-     * @return Reference to the current test_reporter instance.
+     * @return Reference to the current reporter instance.
      */
-    test_reporter&
+    reporter&
     operator<< (char c);
 
     /**
      * @brief Output operator for a constant character string.
      *
      * @param s The string to output.
-     * @return Reference to the current test_reporter instance.
+     * @return Reference to the current reporter instance.
      */
-    test_reporter&
+    reporter&
     operator<< (const char* s);
 
-    /**
-     * @brief Output operator for a mutable character string.
-     *
-     * @param s The string to output.
-     * @return Reference to the current test_reporter instance.
-     */
-    test_reporter&
-    operator<< (char* s);
-
     /**
      * @brief Output operator for boolean values.
      *
      * @param v The boolean value to output.
-     * @return Reference to the current test_reporter instance.
+     * @return Reference to the current reporter instance.
      */
-    test_reporter&
+    reporter&
     operator<< (bool v);
 
     /**
      * @brief Output operator for nullptr.
-     * @return Reference to the current test_reporter instance.
+     * @return Reference to the current reporter instance.
      */
-    test_reporter& operator<< (std::nullptr_t);
+    reporter& operator<< (std::nullptr_t);
 
     /**
      * @brief Output operator for signed char values.
      *
      * @param c The signed char value to output.
-     * @return Reference to the current test_reporter instance.
+     * @return Reference to the current reporter instance.
      */
-    test_reporter&
+    reporter&
     operator<< (signed char c);
 
     /**
      * @brief Output operator for unsigned char values.
      *
      * @param c The unsigned char value to output.
-     * @return Reference to the current test_reporter instance.
+     * @return Reference to the current reporter instance.
      */
-    test_reporter&
+    reporter&
     operator<< (unsigned char c);
 
     /**
      * @brief Output operator for signed short values.
      *
      * @param v The signed short value to output.
-     * @return Reference to the current test_reporter instance.
+     * @return Reference to the current reporter instance.
      */
-    test_reporter&
+    reporter&
     operator<< (signed short v);
 
     /**
      * @brief Output operator for unsigned short values.
      *
      * @param v The unsigned short value to output.
-     * @return Reference to the current test_reporter instance.
+     * @return Reference to the current reporter instance.
      */
-    test_reporter&
+    reporter&
     operator<< (unsigned short v);
 
     /**
      * @brief Output operator for signed int values.
      *
      * @param v The signed int value to output.
-     * @return Reference to the current test_reporter instance.
+     * @return Reference to the current reporter instance.
      */
-    test_reporter&
+    reporter&
     operator<< (signed int v);
 
     /**
      * @brief Output operator for unsigned int values.
      *
      * @param v The unsigned int value to output.
-     * @return Reference to the current test_reporter instance.
+     * @return Reference to the current reporter instance.
      */
-    test_reporter&
+    reporter&
     operator<< (unsigned int v);
 
     /**
      * @brief Output operator for signed long values.
      *
      * @param v The signed long value to output.
-     * @return Reference to the current test_reporter instance.
+     * @return Reference to the current reporter instance.
      */
-    test_reporter&
+    reporter&
     operator<< (signed long v);
 
     /**
      * @brief Output operator for unsigned long values.
      *
      * @param v The unsigned long value to output.
-     * @return Reference to the current test_reporter instance.
+     * @return Reference to the current reporter instance.
      */
-    test_reporter&
+    reporter&
     operator<< (unsigned long v);
 
     /**
      * @brief Output operator for signed long long values.
      *
      * @param v The signed long long value to output.
-     * @return Reference to the current test_reporter instance.
+     * @return Reference to the current reporter instance.
      */
-    test_reporter&
+    reporter&
     operator<< (signed long long v);
 
     /**
      * @brief Output operator for unsigned long long values.
      *
      * @param v The unsigned long long value to output.
-     * @return Reference to the current test_reporter instance.
+     * @return Reference to the current reporter instance.
      */
-    test_reporter&
+    reporter&
     operator<< (unsigned long long v);
 
     /**
      * @brief Output operator for float values.
      *
      * @param v The float value to output.
-     * @return Reference to the current test_reporter instance.
+     * @return Reference to the current reporter instance.
      */
-    test_reporter&
+    reporter&
     operator<< (float v);
 
     /**
      * @brief Output operator for double values.
      *
      * @param v The double value to output.
-     * @return Reference to the current test_reporter instance.
+     * @return Reference to the current reporter instance.
      */
-    test_reporter&
+    reporter&
     operator<< (double v);
 
     /**
      * @brief Output operator for long double values.
      *
      * @param v The long double value to output.
-     * @return Reference to the current test_reporter instance.
+     * @return Reference to the current reporter instance.
      */
-    test_reporter&
+    reporter&
     operator<< (long double v);
 
     /**
@@ -397,20 +397,20 @@ namespace micro_os_plus::micro_test_plus
      * @tparam T The type of the pointer.
      *
      * @param v The pointer value to output.
-     * @return Reference to the current test_reporter instance.
+     * @return Reference to the current reporter instance.
      */
     template <typename T>
-    test_reporter&
+    reporter&
     operator<< (T* v);
 
     /**
      * @brief Output operator to display the endl.
      *
      * @param func Function pointer to the stream manipulator.
-     * @return Reference to the current test_reporter instance.
+     * @return Reference to the current reporter instance.
      */
-    test_reporter&
-    operator<< (test_reporter& (*func) (test_reporter&));
+    reporter&
+    operator<< (reporter& (*func) (reporter&));
 
     // ------------------------------------------------------------------------
     // Specific operators.
@@ -421,10 +421,11 @@ namespace micro_os_plus::micro_test_plus
      * @tparam T The type with a getter method.
      *
      * @param t The object to output.
-     * @return Reference to the current test_reporter instance.
+     * @return Reference to the current reporter instance.
      */
     template <class T>
-    test_reporter&
+      requires type_traits::is_op<T>
+    reporter&
     operator<< (const T& t);
 
     /**
@@ -434,10 +435,10 @@ namespace micro_os_plus::micro_test_plus
      * @tparam T The underlying integral type.
      *
      * @param v The strongly-typed integral value to output.
-     * @return Reference to the current test_reporter instance.
+     * @return Reference to the current reporter instance.
      */
     template <class T>
-    test_reporter&
+    reporter&
     operator<< (const type_traits::genuine_integral_value<T>& v);
 
     /**
@@ -446,14 +447,13 @@ namespace micro_os_plus::micro_test_plus
      * @tparam T The container type.
      *
      * @param t The container to output.
-     * @return Reference to the current test_reporter instance.
+     * @return Reference to the current reporter instance.
      */
-    template <class T,
-              type_traits::requires_t<type_traits::is_container_v<T>
-                                      and not type_traits::has_npos_v<T>>
-              = 0>
-    test_reporter&
-    operator<< (T&& t);
+    template <class T>
+      requires (type_traits::container_like<T>
+                and not type_traits::has_npos<T>)
+    reporter&
+    operator<< (const T& t);
 
     /**
      * @brief Output operator to display eq() expressions.
@@ -462,10 +462,10 @@ namespace micro_os_plus::micro_test_plus
      * @tparam Rhs_T The right-hand side type.
      *
      * @param op The equality comparator expression.
-     * @return Reference to the current test_reporter instance.
+     * @return Reference to the current reporter instance.
      */
     template <class Lhs_T, class Rhs_T>
-    test_reporter&
+    reporter&
     operator<< (const detail::eq_<Lhs_T, Rhs_T>& op);
 
     /**
@@ -475,10 +475,10 @@ namespace micro_os_plus::micro_test_plus
      * @tparam Rhs_T The right-hand side type.
      *
      * @param op The inequality comparator expression.
-     * @return Reference to the current test_reporter instance.
+     * @return Reference to the current reporter instance.
      */
     template <class Lhs_T, class Rhs_T>
-    test_reporter&
+    reporter&
     operator<< (const detail::ne_<Lhs_T, Rhs_T>& op);
 
     /**
@@ -488,10 +488,10 @@ namespace micro_os_plus::micro_test_plus
      * @tparam Rhs_T The right-hand side type.
      *
      * @param op The greater-than comparator expression.
-     * @return Reference to the current test_reporter instance.
+     * @return Reference to the current reporter instance.
      */
     template <class Lhs_T, class Rhs_T>
-    test_reporter&
+    reporter&
     operator<< (const detail::gt_<Lhs_T, Rhs_T>& op);
 
     /**
@@ -501,10 +501,10 @@ namespace micro_os_plus::micro_test_plus
      * @tparam Rhs_T The right-hand side type.
      *
      * @param op The greater-than-or-equal-to comparator expression.
-     * @return Reference to the current test_reporter instance.
+     * @return Reference to the current reporter instance.
      */
     template <class Lhs_T, class Rhs_T>
-    test_reporter&
+    reporter&
     operator<< (const detail::ge_<Lhs_T, Rhs_T>& op);
 
     /**
@@ -514,10 +514,10 @@ namespace micro_os_plus::micro_test_plus
      * @tparam Rhs_T The right-hand side type.
      *
      * @param op The less-than comparator expression.
-     * @return Reference to the current test_reporter instance.
+     * @return Reference to the current reporter instance.
      */
     template <class Lhs_T, class Rhs_T>
-    test_reporter&
+    reporter&
     operator<< (const detail::lt_<Rhs_T, Lhs_T>& op);
 
     /**
@@ -527,10 +527,10 @@ namespace micro_os_plus::micro_test_plus
      * @tparam Rhs_T The right-hand side type.
      *
      * @param op The less-than-or-equal-to comparator expression.
-     * @return Reference to the current test_reporter instance.
+     * @return Reference to the current reporter instance.
      */
     template <class Lhs_T, class Rhs_T>
-    test_reporter&
+    reporter&
     operator<< (const detail::le_<Rhs_T, Lhs_T>& op);
 
     /**
@@ -540,10 +540,10 @@ namespace micro_os_plus::micro_test_plus
      * @tparam Rhs_T The right-hand side type.
      *
      * @param op The logical conjunction (AND) expression.
-     * @return Reference to the current test_reporter instance.
+     * @return Reference to the current reporter instance.
      */
     template <class Lhs_T, class Rhs_T>
-    test_reporter&
+    reporter&
     operator<< (const detail::and_<Lhs_T, Rhs_T>& op);
 
     /**
@@ -553,10 +553,10 @@ namespace micro_os_plus::micro_test_plus
      * @tparam Rhs_T The right-hand side type.
      *
      * @param op The logical disjunction (OR) expression.
-     * @return Reference to the current test_reporter instance.
+     * @return Reference to the current reporter instance.
      */
     template <class Lhs_T, class Rhs_T>
-    test_reporter&
+    reporter&
     operator<< (const detail::or_<Lhs_T, Rhs_T>& op);
 
     /**
@@ -565,10 +565,10 @@ namespace micro_os_plus::micro_test_plus
      * @tparam T The operand type.
      *
      * @param op The logical negation expression.
-     * @return Reference to the current test_reporter instance.
+     * @return Reference to the current reporter instance.
      */
     template <class T>
-    test_reporter&
+    reporter&
     operator<< (const detail::not_<T>& op);
 
 #if defined(__cpp_exceptions)
@@ -580,10 +580,10 @@ namespace micro_os_plus::micro_test_plus
      * @tparam Exception_T The exception type.
      *
      * @param op The throws comparator expression.
-     * @return Reference to the current test_reporter instance.
+     * @return Reference to the current reporter instance.
      */
     template <class Expr_T, class Exception_T>
-    test_reporter&
+    reporter&
     operator<< (const detail::throws_<Expr_T, Exception_T>& op);
 
     /**
@@ -592,10 +592,10 @@ namespace micro_os_plus::micro_test_plus
      * @tparam Expr_T The expression type.
      *
      * @param op The throws comparator expression.
-     * @return Reference to the current test_reporter instance.
+     * @return Reference to the current reporter instance.
      */
     template <class Expr_T>
-    test_reporter&
+    reporter&
     operator<< (const detail::throws_<Expr_T, void>& op);
 
     /**
@@ -604,13 +604,15 @@ namespace micro_os_plus::micro_test_plus
      * @tparam Expr_T The expression type.
      *
      * @param op The nothrow comparator expression.
-     * @return Reference to the current test_reporter instance.
+     * @return Reference to the current reporter instance.
      */
     template <class Expr_T>
-    test_reporter&
+    reporter&
     operator<< (const detail::nothrow_<Expr_T>& op);
 #endif
 
+    // ------------------------------------------------------------------------
+
     /**
      * @brief Inserts a line ending into the output buffer.
      *
@@ -619,9 +621,35 @@ namespace micro_os_plus::micro_test_plus
      * @par Returns
      *   Nothing.
      */
-    virtual void
-    endline (void)
-        = 0;
+    void
+    endline (void);
+
+    /**
+     * @brief Output the current buffered content.
+     *
+     * @note Public because `deferred_reporter_base` calls this
+     *   from its destructor when aborting, after the subtest
+     *   instance is no longer accessible via the normal
+     *   reporting path.
+     *
+     * @par Parameters
+     *	 None.
+     * @par Returns
+     *   Nothing.
+     */
+    void
+    write_buffer_to_stdout (void);
+
+    /**
+     * @brief Flush the current buffered content.
+     *
+     * @par Parameters
+     *	 None.
+     * @par Returns
+     *   Nothing.
+     */
+    void
+    flush (void);
 
     // ------------------------------------------------------------------------
 
@@ -632,12 +660,13 @@ namespace micro_os_plus::micro_test_plus
      *
      * @param expr The evaluated expression.
      * @param message The message to display.
+     * @param subtest The subtest that owns this check.
      * @par Returns
      *   Nothing.
      */
     template <class Expr_T>
     void
-    pass (Expr_T& expr, std::string& message);
+    pass (Expr_T& expr, std::string& message, subtest& subtest);
 
     /**
      * @brief Report a failed condition.
@@ -648,141 +677,157 @@ namespace micro_os_plus::micro_test_plus
      * @param abort Whether to abort execution after failure.
      * @param message The message to display.
      * @param location The source location of the failure.
+     * @param subtest The subtest that owns this check.
      * @par Returns
      *   Nothing.
      */
     template <class Expr_T>
     void
     fail (Expr_T& expr, bool abort, std::string& message,
-          const reflection::source_location& location);
+          const reflection::source_location& location, subtest& subtest);
+
+    // ------------------------------------------------------------------------
 
     /**
-     * @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.
      */
     virtual void
-    begin_test_case (const char* name)
-        = 0;
+    begin_session (runner& runner) = 0;
 
     /**
-     * @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.
      */
     virtual void
-    end_test_case (const char* name)
-        = 0;
+    end_session (runner& runner) = 0;
 
     /**
      * @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.
      */
     virtual void
-    begin_test_suite (const char* name)
-        = 0;
+    begin_suite (suite& suite) = 0;
 
     /**
      * @brief Mark the end of a test suite.
      *
-     * @param suite Reference to the test suite base.
+     * @param suite Reference to the test suite.
      * @par Returns
      *   Nothing.
      */
     virtual void
-    end_test_suite (test_suite_base& suite)
-        = 0;
+    end_suite (suite& suite) = 0;
 
     /**
-     * @brief Mark the beginning of a test.
+     * @brief Mark the beginning of a subtest.
      *
-     * @param test_suites_count The number of test suites.
+     * @param subtest Reference to the subtest.
      * @par Returns
      *   Nothing.
      */
     virtual void
-    begin_test (size_t test_suites_count)
-        = 0;
+    begin_subtest (subtest& subtest) = 0;
 
     /**
-     * @brief Mark the end of a test.
+     * @brief Mark the end of a subtest.
      *
-     * @param runner Reference to the test runner.
+     * @param subtest Reference to the subtest.
      * @par Returns
      *   Nothing.
      */
     virtual void
-    end_test (test_runner& runner)
-        = 0;
+    end_subtest (subtest& subtest) = 0;
 
     /**
-     * @brief Flush the current buffered content.
+     * @brief Returns the comment-prefix string used by this reporter format.
+     *
+     * @details
+     * Human reporters return an empty string; TAP reporters return `"# "`
+     * so that diagnostic lines conform to the TAP specification.
      *
      * @par Parameters
      *	 None.
-     * @par Returns
-     *   Nothing.
+     * @return A null-terminated prefix string.
      */
-    virtual void
-    flush (void)
-        = 0;
+    virtual const char*
+    get_comment_prefix (void) = 0;
 
     /**
-     * @brief Output the current buffered content.
+     * @brief Returns the current verbosity level.
      *
      * @par Parameters
      *	 None.
-     * @par Returns
-     *   Nothing.
+     * @return The active `verbosity` value.
      */
-    virtual void
-    output (void)
-        = 0;
+    auto
+    verbosity () const -> micro_test_plus::verbosity
+    {
+      return verbosity_;
+    }
+
+    // ------------------------------------------------------------------------
 
+  protected:
     /**
-     * @brief Controls whether to add an empty line between successful test
-     * cases.
+     * @brief Selects the appropriate colour code based on a condition.
+     *
+     * @param cond Boolean value indicating pass (true) or fail (false).
+     * @return The corresponding ANSI colour code as a string.
      *
      * @details
-     * Used to nicely format the output.
+     * Returns the ANSI colour code for pass or fail, depending on the boolean
+     * condition provided.
      */
-    bool add_empty_line{ true };
+    [[nodiscard]] inline auto
+    colour_ (const bool cond) const
+    {
+      return cond ? colours_.pass : colours_.fail;
+    }
+
+    void
+    write_buffer_to_file_ (void);
 
     /**
-     * @brief The verbosity level for test reporting.
+     * @brief Appends informational (non-result) text to the output buffer.
+     *
+     * @par Parameters
+     *   None.
+     * @par Returns
+     *   Nothing.
      */
-    verbosity_t verbosity{};
+    void
+    write_info_ (void);
 
-  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.
      */
     virtual void
-    output_pass_prefix_ (std::string& message)
-        = 0;
+    output_pass_prefix_ (std::string& message, subtest& subtest) = 0;
 
     /**
      * @brief Outputs the suffix for a passing condition.
      *
-     * @par Parameters
-     *	 None.
+     * @param subtest The subtest that owns this check.
      * @par Returns
      *   Nothing.
      */
     virtual void
-    output_pass_suffix_ (void)
-        = 0;
+    output_pass_suffix_ (subtest& subtest) = 0;
 
     /**
      * @brief Outputs the prefix for a failing condition.
@@ -791,41 +836,92 @@ namespace micro_os_plus::micro_test_plus
      * @param hasExpression 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.
      */
     virtual void
     output_fail_prefix_ (std::string& message, const bool hasExpression,
-                         const reflection::source_location& location)
-        = 0;
+                         const reflection::source_location& location,
+                         subtest& subtest) = 0;
 
     /**
      * @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.
      */
     virtual void
     output_fail_suffix_ (const reflection::source_location& location,
-                         bool abort)
-        = 0;
+                         bool abort, subtest& subtest) = 0;
+
+    /**
+     * @brief Appends the string representation of a numeric value to a
+     * buffer, using `std::to_chars` for allocation-free, locale-independent
+     * formatting.
+     *
+     * @tparam T The numeric type to format.
+     *
+     * @param buffer The string to append to.
+     * @param v The value to format.
+     * @par Returns
+     *   Nothing.
+     */
+    template <class T>
+    static void
+    append_number_ (std::string& buffer, T v);
+
+  protected:
+    /**
+     * @brief The verbosity level for test reporting.
+     */
+    enum verbosity verbosity_ = verbosity::normal;
 
     /**
      * @brief ANSI colour codes for output formatting.
      */
-    colors colors_{};
+    colours colours_{};
 
     /**
      * @brief Internal output buffer for accumulating report content.
      */
-    std::string out_{};
+    std::string buffer_{};
+
+    /**
+     * @brief Controls whether to add an empty line between successful test
+     * cases.
+     *
+     * @details
+     * Used to nicely format the output.
+     */
+    bool add_empty_line_{ true };
+
+    /**
+     * @brief Optional file path for redirecting test report output.
+     *
+     * @details
+     * When non-null, `write_buffer_to_file_()` writes accumulated output
+     * to this path in addition to (or instead of) standard output.
+     */
+    const char* output_file_path_{ nullptr };
+
+    /**
+     * @brief Optional output file for redirecting test report output.
+     *
+     * @details
+     * When non-null, all output is written to this file instead of
+     * standard output. The reporter does not own the file; the caller
+     * is responsible for its lifetime.
+     */
+    FILE* output_file_{ nullptr };
 
     /**
-     * @brief Indicates whether the reporter is currently within a test case.
+     * @brief Owns the command-line arguments passed to the test runner.
      */
-    bool is_in_test_case_ = false;
+    std::unique_ptr<std::vector<std::string_view>> argvs_{};
   };
 
   // --------------------------------------------------------------------------