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

package/src/test-reporter.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 reporter
+ * methods.
+ *
+ * @details
+ * This source file contains the core implementations for the test reporting
+ * facilities of the µTest++ framework. It provides the logic for formatting
+ * and outputting test results, including operator overloads for a wide range
+ * of value types, containers, and comparison expressions, as well as
+ * structured output for logical and exception-related assertions.
+ *
+ * The test reporter is responsible for presenting test outcomes in a clear,
+ * consistent, and expressive manner, supporting both value and pointer
+ * semantics, and providing detailed diagnostics for both successful and failed
+ * test cases. Special attention is given to formatting, colour highlighting,
+ * and extensibility, enabling professional and readable test reports suitable
+ * for embedded and general C++ development.
+ *
+ * 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
@@ -25,6 +53,7 @@
 
 #pragma GCC diagnostic ignored "-Waggregate-return"
 #if defined(__clang__)
+#pragma clang diagnostic ignored "-Wunknown-warning-option"
 #pragma clang diagnostic ignored "-Wc++98-compat"
 #pragma clang diagnostic ignored "-Wc++98-compat-pedantic"
 #endif
@@ -33,83 +62,34 @@ namespace micro_os_plus::micro_test_plus
 {
   // --------------------------------------------------------------------------
 
-  test_reporter&
-  endl (test_reporter& stream)
-  {
-    reporter.endline ();
-    return stream;
-  }
+  test_reporter::~test_reporter () = default;
 
   // --------------------------------------------------------------------------
 
-  void
-  test_reporter::output_pass_prefix_ (std::string& message)
-  {
-    *this << colors_.pass;
-    if (is_in_test_case_)
-      {
-        *this << "  ";
-      }
-    *this << "  ✓ ";
-    *this << colors_.none;
-    if (!message.empty ())
-      {
-        *this << message.c_str ();
-      }
-  }
-
-  void
-  test_reporter::output_pass_suffix_ (void)
-  {
-    *this << endl;
-
-    flush ();
-  }
-
-  void
-  test_reporter::output_fail_prefix_ (
-      std::string& message, const reflection::source_location& location)
-  {
-    *this << colors_.fail;
-    if (is_in_test_case_)
-      {
-        *this << "  ";
-      }
-    *this << "  ✗ ";
-    *this << colors_.none;
-    if (!message.empty ())
-      {
-        *this << message.c_str ();
-        *this << " ";
-      }
-    *this << colors_.fail << "FAILED" << colors_.none;
-#pragma GCC diagnostic push
-#if defined(__clang__)
-#pragma clang diagnostic ignored "-Wsign-conversion"
-#elif defined(__GNUC__)
-#pragma GCC diagnostic ignored "-Wnarrowing"
-#pragma GCC diagnostic ignored "-Wsign-conversion"
-#endif
-    *this << " (" << reflection::short_name (location.file_name ()) << ":"
-          << type_traits::genuine_integral_value<unsigned int>{
-               location.line ()
-             };
-#pragma GCC diagnostic pop
-  }
-
-  void
-  test_reporter::output_fail_suffix_ (bool abort)
+  /**
+   * @details
+   * The `endl` function inserts a newline character into the specified
+   * `test_reporter` stream and flushes its output buffer. This operation
+   * ensures that each test output line is clearly separated and immediately
+   * visible, facilitating the readability and clarity of test results across
+   * all test cases and folders within the µTest++ framework.
+   */
+  test_reporter&
+  endl (test_reporter& stream)
   {
-    *this << ")";
-    if (abort)
-      {
-        *this << " aborted...";
-      }
-    *this << endl;
-
-    flush ();
+    reporter->endline ();
+    return stream;
   }
 
+  /**
+   * @details
+   * This operator overload enables manipulators, such as `endl`, to be used
+   * with the `test_reporter` stream in a manner similar to standard C++
+   * streams. When a manipulator function is passed, it is invoked with the
+   * current `test_reporter` instance, allowing for seamless integration of
+   * stream operations and improved readability of test output across all test
+   * cases and folders.
+   */
   test_reporter&
   test_reporter::operator<< (test_reporter& (*func) (test_reporter&))
   {
@@ -118,19 +98,14 @@ namespace micro_os_plus::micro_test_plus
     return *this;
   }
 
-  void
-  test_reporter::endline (void)
-  {
-    out_.append ("\n");
-    flush ();
-  }
-
-  void
-  test_reporter::flush (void)
-  {
-    fflush (stdout); // Sync STDOUT.
-  }
-
+  /**
+   * @details
+   * This operator overload appends the contents of the provided
+   * `std::string_view` to the internal output buffer of the `test_reporter`.
+   * It enables seamless streaming of string data into the reporter, supporting
+   * clear and efficient formatting of test output across all test cases and
+   * folders.
+   */
   test_reporter&
   test_reporter::operator<< (std::string_view sv)
   {
@@ -138,6 +113,13 @@ namespace micro_os_plus::micro_test_plus
     return *this;
   }
 
+  /**
+   * @details
+   * This operator overload appends the specified character to the internal
+   * output buffer of the `test_reporter`. It enables efficient streaming of
+   * individual characters into the reporter, supporting precise and flexible
+   * formatting of test output across all test cases and folders.
+   */
   test_reporter&
   test_reporter::operator<< (char c)
   {
@@ -145,6 +127,14 @@ namespace micro_os_plus::micro_test_plus
     return *this;
   }
 
+  /**
+   * @details
+   * This operator overload appends the contents of the provided C-style string
+   * to the internal output buffer of the `test_reporter`. It enables efficient
+   * streaming of string literals and character arrays into the reporter,
+   * supporting clear and flexible formatting of test output across all test
+   * cases and folders.
+   */
   test_reporter&
   test_reporter::operator<< (const char* s)
   {
@@ -152,6 +142,14 @@ namespace micro_os_plus::micro_test_plus
     return *this;
   }
 
+  /**
+   * @details
+   * This operator overload appends the contents of the provided modifiable
+   * C-style string to the internal output buffer of the `test_reporter`. It
+   * enables efficient streaming of mutable string data into the reporter,
+   * supporting clear and flexible formatting of test output across all test
+   * cases and folders.
+   */
   test_reporter&
   test_reporter::operator<< (char* s)
   {
@@ -159,6 +157,14 @@ namespace micro_os_plus::micro_test_plus
     return *this;
   }
 
+  /**
+   * @details
+   * This operator overload appends the string representation of the specified
+   * boolean value to the internal output buffer of the `test_reporter`. It
+   * enables clear and direct streaming of boolean results into the reporter,
+   * supporting precise and readable formatting of test output across all test
+   * cases and folders.
+   */
   test_reporter&
   test_reporter::operator<< (bool v)
   {
@@ -166,6 +172,13 @@ namespace micro_os_plus::micro_test_plus
     return *this;
   }
 
+  /**
+   * @details
+   * This operator overload appends the string "nullptr" to the internal output
+   * buffer of the `test_reporter`. It enables clear and explicit streaming of
+   * null pointer values into the reporter, supporting precise and readable
+   * formatting of test output across all test cases and folders.
+   */
   test_reporter&
   test_reporter::operator<< (std::nullptr_t)
   {
@@ -173,6 +186,14 @@ namespace micro_os_plus::micro_test_plus
     return *this;
   }
 
+  /**
+   * @details
+   * This operator overload appends the string representation of the specified
+   * signed character to the internal output buffer of the `test_reporter`. It
+   * enables precise and readable streaming of character values into the
+   * reporter, supporting clear formatting of test output across all test cases
+   * and folders.
+   */
   test_reporter&
   test_reporter::operator<< (signed char c)
   {
@@ -181,6 +202,14 @@ namespace micro_os_plus::micro_test_plus
     return *this;
   }
 
+  /**
+   * @details
+   * This operator overload appends the string representation of the specified
+   * unsigned character to the internal output buffer of the `test_reporter`.
+   * It enables precise and readable streaming of unsigned character values
+   * into the reporter, supporting clear formatting of test output across all
+   * test cases and folders.
+   */
   test_reporter&
   test_reporter::operator<< (unsigned char c)
   {
@@ -189,6 +218,14 @@ namespace micro_os_plus::micro_test_plus
     return *this;
   }
 
+  /**
+   * @details
+   * This operator overload appends the string representation of the specified
+   * signed short integer to the internal output buffer of the `test_reporter`.
+   * It enables precise and readable streaming of signed short values into the
+   * reporter, supporting clear formatting of test output across all test cases
+   * and folders.
+   */
   test_reporter&
   test_reporter::operator<< (signed short v)
   {
@@ -197,6 +234,14 @@ namespace micro_os_plus::micro_test_plus
     return *this;
   }
 
+  /**
+   * @details
+   * This operator overload appends the string representation of the specified
+   * unsigned short integer to the internal output buffer of the
+   * `test_reporter`. It enables precise and readable streaming of unsigned
+   * short values into the reporter, supporting clear formatting of test output
+   * across all test cases and folders.
+   */
   test_reporter&
   test_reporter::operator<< (unsigned short v)
   {
@@ -205,6 +250,14 @@ namespace micro_os_plus::micro_test_plus
     return *this;
   }
 
+  /**
+   * @details
+   * This operator overload appends the string representation of the specified
+   * signed integer to the internal output buffer of the `test_reporter`. It
+   * enables precise and readable streaming of signed integer values into the
+   * reporter, supporting clear formatting of test output across all test cases
+   * and folders.
+   */
   test_reporter&
   test_reporter::operator<< (signed int v)
   {
@@ -212,6 +265,14 @@ namespace micro_os_plus::micro_test_plus
     return *this;
   }
 
+  /**
+   * @details
+   * This operator overload appends the string representation of the specified
+   * unsigned integer to the internal output buffer of the `test_reporter`. It
+   * enables precise and readable streaming of unsigned integer values into the
+   * reporter, supporting clear formatting of test output across all test cases
+   * and folders.
+   */
   test_reporter&
   test_reporter::operator<< (unsigned int v)
   {
@@ -220,6 +281,14 @@ namespace micro_os_plus::micro_test_plus
     return *this;
   }
 
+  /**
+   * @details
+   * This operator overload appends the string representation of the specified
+   * signed long integer to the internal output buffer of the `test_reporter`.
+   * It enables precise and readable streaming of signed long values into the
+   * reporter, supporting clear formatting of test output across all test cases
+   * and folders.
+   */
   test_reporter&
   test_reporter::operator<< (signed long v)
   {
@@ -228,6 +297,14 @@ namespace micro_os_plus::micro_test_plus
     return *this;
   }
 
+  /**
+   * @details
+   * This operator overload appends the string representation of the specified
+   * unsigned long integer to the internal output buffer of the
+   * `test_reporter`. It enables precise and readable streaming of unsigned
+   * long values into the reporter, supporting clear formatting of test output
+   * across all test cases and folders.
+   */
   test_reporter&
   test_reporter::operator<< (unsigned long v)
   {
@@ -236,6 +313,14 @@ namespace micro_os_plus::micro_test_plus
     return *this;
   }
 
+  /**
+   * @details
+   * This operator overload appends the string representation of the specified
+   * signed long long integer to the internal output buffer of the
+   * `test_reporter`. It enables precise and readable streaming of signed long
+   * long values into the reporter, supporting clear formatting of test output
+   * across all test cases and folders.
+   */
   test_reporter&
   test_reporter::operator<< (signed long long v)
   {
@@ -244,6 +329,14 @@ namespace micro_os_plus::micro_test_plus
     return *this;
   }
 
+  /**
+   * @details
+   * This operator overload appends the string representation of the specified
+   * unsigned long long integer to the internal output buffer of the
+   * `test_reporter`. It enables precise and readable streaming of unsigned
+   * long long values into the reporter, supporting clear formatting of test
+   * output across all test cases and folders.
+   */
   test_reporter&
   test_reporter::operator<< (unsigned long long v)
   {
@@ -252,6 +345,14 @@ namespace micro_os_plus::micro_test_plus
     return *this;
   }
 
+  /**
+   * @details
+   * This operator overload appends the string representation of the specified
+   * floating-point value to the internal output buffer of the `test_reporter`,
+   * followed by the character 'f' to indicate a float type. It enables precise
+   * and readable streaming of float values into the reporter, supporting clear
+   * formatting of test output across all test cases and folders.
+   */
   test_reporter&
   test_reporter::operator<< (float v)
   {
@@ -260,6 +361,14 @@ namespace micro_os_plus::micro_test_plus
     return *this;
   }
 
+  /**
+   * @details
+   * This operator overload appends the string representation of the specified
+   * double-precision floating-point value to the internal output buffer of the
+   * `test_reporter`. It enables precise and readable streaming of double
+   * values into the reporter, supporting clear formatting of test output
+   * across all test cases and folders.
+   */
   test_reporter&
   test_reporter::operator<< (double v)
   {
@@ -267,6 +376,15 @@ namespace micro_os_plus::micro_test_plus
     return *this;
   }
 
+  /**
+   * @details
+   * This operator overload appends the string representation of the specified
+   * long double-precision floating-point value to the internal output buffer
+   * of the `test_reporter`, followed by the character 'l' to indicate a long
+   * double type. It enables precise and readable streaming of long double
+   * values into the reporter, supporting clear formatting of test output
+   * across all test cases and folders.
+   */
   test_reporter&
   test_reporter::operator<< (long double v)
   {
@@ -275,157 +393,6 @@ namespace micro_os_plus::micro_test_plus
     return *this;
   }
 
-  void
-  test_reporter::begin_test_case ([[maybe_unused]] const char* name)
-  {
-    is_in_test_case_ = true;
-
-    if (!out_.empty () && (verbosity == verbosity::verbose))
-      {
-        if (add_empty_line)
-          {
-            printf ("\n");
-          }
-        output ();
-        add_empty_line = true;
-      }
-
-    out_.clear ();
-
-    flush ();
-  }
-
-  void
-  test_reporter::end_test_case ([[maybe_unused]] const char* name)
-  {
-    if (verbosity == verbosity::normal || verbosity == verbosity::verbose)
-      {
-        if (current_test_suite->current_test_case.failed_checks > 0)
-          {
-            if (true /* add_empty_line */)
-              {
-                printf ("\n");
-              }
-            printf ("  • %s - test case started\n", name);
-            output ();
-            printf (
-                "  %s✗%s %s - test case %sFAILED%s (%d %s passed, %d "
-                "failed)\n",
-                colors_.fail, colors_.none, name, colors_.fail, colors_.none,
-                current_test_suite->current_test_case.successful_checks,
-                current_test_suite->current_test_case.successful_checks == 1
-                    ? "check"
-                    : "checks",
-                current_test_suite->current_test_case.failed_checks);
-            add_empty_line = true;
-          }
-        else
-          {
-            if (add_empty_line)
-              {
-                printf ("\n");
-              }
-            if (verbosity == verbosity::verbose)
-              {
-                printf ("  • %s - test case started\n", name);
-                output ();
-                printf (
-                    "  %s✓%s %s - test case passed (%d %s)\n", colors_.pass,
-                    colors_.none, name,
-                    current_test_suite->current_test_case.successful_checks,
-                    current_test_suite->current_test_case.successful_checks
-                            == 1
-                        ? "check"
-                        : "checks");
-
-                add_empty_line = true;
-              }
-            else
-              {
-                printf (
-                    "  %s✓%s %s - test case passed (%d %s)\n", colors_.pass,
-                    colors_.none, name,
-                    current_test_suite->current_test_case.successful_checks,
-                    current_test_suite->current_test_case.successful_checks
-                            == 1
-                        ? "check"
-                        : "checks");
-
-                add_empty_line = false;
-              }
-          }
-      }
-
-    out_.clear ();
-    flush ();
-
-    is_in_test_case_ = false;
-  }
-
-  void
-  test_reporter::begin_test_suite (const char* name)
-  {
-    if (add_empty_line)
-      {
-        flush ();
-        printf ("\n");
-      }
-
-    if (verbosity == verbosity::silent || verbosity == verbosity::quiet)
-      {
-        add_empty_line = false;
-        return;
-      }
-
-    printf ("• %s - test suite started\n", name);
-
-    add_empty_line = true;
-  }
-
-  void
-  test_reporter::end_test_suite (test_suite_base& suite)
-  {
-    if (verbosity == verbosity::silent)
-      {
-        return;
-      }
-
-    if (suite.test_cases () > 0 && verbosity != verbosity::quiet)
-      {
-        printf ("\n");
-        add_empty_line = true;
-      }
-
-    // Also fail if none passed.
-    if (suite.failed_checks () == 0 && suite.successful_checks () != 0)
-      {
-        printf ("%s✓%s %s - test suite passed (%d %s in %d test %s)\n",
-                colors_.pass, colors_.none, suite.name (),
-                suite.successful_checks (),
-                suite.successful_checks () == 1 ? "check" : "checks",
-                suite.test_cases (),
-                suite.test_cases () == 1 ? "case" : "cases");
-      }
-    else
-      {
-        printf ("%s✗%s %s - test suite %sFAILED%s (%d %s passed, %d failed, "
-                "in %d test %s)\n",
-                colors_.fail, colors_.none, suite.name (), colors_.fail,
-                colors_.none, suite.successful_checks (),
-                suite.successful_checks () == 1 ? "check" : "checks",
-                suite.failed_checks (), suite.test_cases (),
-                suite.test_cases () == 1 ? "case" : "cases");
-      }
-    flush ();
-  }
-
-  void
-  test_reporter::output (void)
-  {
-    printf ("%s", out_.c_str ()); // No `\n` here.
-    out_.clear ();
-  }
-
   // --------------------------------------------------------------------------
 } // namespace micro_os_plus::micro_test_plus