@micro-os-plus/micro-test-plus 3.2.0 → 3.2.3

package/src/test-reporter.cpp

@@ -1,17 +1,44 @@
 /*
- * This file is part of the µOS++ distribution.
- *   (https://github.com/micro-os-plus/)
- * Copyright (c) 2021 Liviu Ionescu.
+ * This file is part of the µOS++ project (https://micro-os-plus.github.io/).
+ * 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,
- * which can be obtained from <https://www.boost.org/LICENSE_1_0.txt>.
+ * which can be obtained from https://www.boost.org/LICENSE_1_0.txt.
+ */
+
+// ----------------------------------------------------------------------------
+
+/**
+ * @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.
  */
 
 // ----------------------------------------------------------------------------
@@ -26,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
@@ -34,6 +62,14 @@ namespace micro_os_plus::micro_test_plus
 {
   // --------------------------------------------------------------------------
 
+  /**
+   * @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)
   {
@@ -43,6 +79,18 @@ namespace micro_os_plus::micro_test_plus
 
   // --------------------------------------------------------------------------
 
+  /**
+   * @details
+   * This method outputs the prefix for a passing test result, applying the
+   * appropriate colour formatting and symbols to clearly indicate success. If
+   * the output occurs within a test case, additional indentation is applied
+   * for readability. The prefix includes a tick symbol (`✓`) and, if provided,
+   * an associated message. Colour formatting is reset after the prefix to
+   * maintain consistent output style across all test cases and folders.
+   *
+   * The prefix/suffix methods help shorten the code
+   * generated by the template methods.
+   */
   void
   test_reporter::output_pass_prefix_ (std::string& message)
   {
@@ -59,6 +107,21 @@ namespace micro_os_plus::micro_test_plus
       }
   }
 
+  /**
+   * @details
+   * The `endl` function acts as a stream manipulator for the `test_reporter`,
+   * inserting a line ending into the output buffer and flushing the current
+   * content if necessary. This ensures that test report output is clearly
+   * separated and formatted, improving readability and professionalism in the
+   * presentation of test results.
+   *
+   * Using `endl` in conjunction with the `test_reporter` output operators
+   * provides a familiar and convenient mechanism for managing line breaks,
+   * similar to standard C++ stream manipulators.
+   *
+   * The prefix/suffix methods help shorten the code
+   * generated by the template methods.
+   */
   void
   test_reporter::output_pass_suffix_ (void)
   {
@@ -67,6 +130,17 @@ namespace micro_os_plus::micro_test_plus
     flush ();
   }
 
+  /**
+   * @details
+   * This method outputs the prefix for a failing test result, applying the
+   * appropriate colour formatting and symbols to clearly indicate failure. If
+   * the output occurs within a test case, additional indentation is applied
+   * for readability. The prefix includes a cross symbol (`✗`), an optional
+   * message, and the label "FAILED". The source location is appended in
+   * parentheses, showing the file or folder name and line number where the
+   * failure occurred. Colour formatting is reset after the prefix to maintain
+   * consistent output style across all test cases and folders.
+   */
   void
   test_reporter::output_fail_prefix_ (
       std::string& message, const reflection::source_location& location)
@@ -98,6 +172,15 @@ namespace micro_os_plus::micro_test_plus
 #pragma GCC diagnostic pop
   }
 
+  /**
+   * @details
+   * This method outputs the suffix for a failing test result by closing the
+   * location information, appending an "aborted..." message if the test was
+   * aborted, and then adding a newline to the test output. The output stream
+   * is flushed to ensure immediate visibility. This approach guarantees that
+   * failure results are clearly separated, promptly reported, and easily
+   * distinguishable across all test cases and folders.
+   */
   void
   test_reporter::output_fail_suffix_ (bool abort)
   {
@@ -111,6 +194,15 @@ namespace micro_os_plus::micro_test_plus
     flush ();
   }
 
+  /**
+   * @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&))
   {
@@ -119,6 +211,14 @@ namespace micro_os_plus::micro_test_plus
     return *this;
   }
 
+  /**
+   * @details
+   * This method appends a newline character to the internal output buffer of
+   * the `test_reporter` and immediately flushes the stream. This ensures that
+   * each line of test output is clearly separated and promptly displayed,
+   * enhancing the readability and organisation of test results across all test
+   * cases and folders.
+   */
   void
   test_reporter::endline (void)
   {
@@ -126,12 +226,27 @@ namespace micro_os_plus::micro_test_plus
     flush ();
   }
 
+  /**
+   * @details
+   * This method flushes the output buffer of the `test_reporter` by
+   * synchronising it with the standard output stream. This guarantees that all
+   * pending test output is immediately written and visible, ensuring prompt
+   * and reliable reporting of test results across all test cases and folders.
+   */
   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)
   {
@@ -139,6 +254,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)
   {
@@ -146,6 +268,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)
   {
@@ -153,6 +283,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)
   {
@@ -160,6 +298,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)
   {
@@ -167,6 +313,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)
   {
@@ -174,6 +327,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)
   {
@@ -182,6 +343,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)
   {
@@ -190,6 +359,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)
   {
@@ -198,6 +375,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)
   {
@@ -206,6 +391,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)
   {
@@ -213,6 +406,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)
   {
@@ -221,6 +422,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)
   {
@@ -229,6 +438,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)
   {
@@ -237,6 +454,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)
   {
@@ -245,6 +470,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)
   {
@@ -253,6 +486,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)
   {
@@ -261,6 +502,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)
   {
@@ -268,6 +517,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)
   {
@@ -276,6 +534,17 @@ namespace micro_os_plus::micro_test_plus
     return *this;
   }
 
+  /**
+   * @details
+   * This method marks the beginning of a test case, setting the internal state
+   * to indicate that test output is now within a test case context. If there
+   * is pending output and the verbosity level is set to verbose, it ensures
+   * that output is properly separated and displayed, adding an empty line if
+   * necessary. The output buffer is cleared and the stream is flushed to
+   * guarantee that all previous output is visible before the new test case
+   * begins. This approach enhances the clarity and organisation of test
+   * results across all test cases and folders.
+   */
   void
   test_reporter::begin_test_case ([[maybe_unused]] const char* name)
   {
@@ -296,6 +565,18 @@ namespace micro_os_plus::micro_test_plus
     flush ();
   }
 
+  /**
+   * @details
+   * This method marks the end of a test case, summarising its outcome and
+   * outputting the results with appropriate formatting and colour coding. If
+   * any checks have failed, a failure message is displayed, including the
+   * number of successful and failed checks. For passing test cases, a success
+   * message is shown with the total number of checks. The output is adjusted
+   * according to the verbosity level, and additional spacing is managed for
+   * clarity. The output buffer is cleared and the stream is flushed to ensure
+   * all results are immediately visible, supporting clear and organised
+   * reporting across all test cases and folders.
+   */
   void
   test_reporter::end_test_case ([[maybe_unused]] const char* name)
   {
@@ -307,6 +588,10 @@ namespace micro_os_plus::micro_test_plus
               {
                 printf ("\n");
               }
+#pragma GCC diagnostic push
+#if defined(__clang__)
+#pragma clang diagnostic ignored "-Wunsafe-buffer-usage-in-libc-call"
+#endif
             printf ("  • %s - test case started\n", name);
             output ();
             printf (
@@ -318,6 +603,7 @@ namespace micro_os_plus::micro_test_plus
                     ? "check"
                     : "checks",
                 current_test_suite->current_test_case.failed_checks);
+#pragma GCC diagnostic pop
             add_empty_line = true;
           }
         else
@@ -328,6 +614,10 @@ namespace micro_os_plus::micro_test_plus
               }
             if (verbosity == verbosity::verbose)
               {
+#pragma GCC diagnostic push
+#if defined(__clang__)
+#pragma clang diagnostic ignored "-Wunsafe-buffer-usage-in-libc-call"
+#endif
                 printf ("  • %s - test case started\n", name);
                 output ();
                 printf (
@@ -338,11 +628,15 @@ namespace micro_os_plus::micro_test_plus
                             == 1
                         ? "check"
                         : "checks");
-
+#pragma GCC diagnostic pop
                 add_empty_line = true;
               }
             else
               {
+#pragma GCC diagnostic push
+#if defined(__clang__)
+#pragma clang diagnostic ignored "-Wunsafe-buffer-usage-in-libc-call"
+#endif
                 printf (
                     "  %s✓%s %s - test case passed (%d %s)\n", colors_.pass,
                     colors_.none, name,
@@ -351,6 +645,7 @@ namespace micro_os_plus::micro_test_plus
                             == 1
                         ? "check"
                         : "checks");
+#pragma GCC diagnostic pop
 
                 add_empty_line = false;
               }
@@ -363,6 +658,16 @@ namespace micro_os_plus::micro_test_plus
     is_in_test_case_ = false;
   }
 
+  /**
+   * @details
+   * This method marks the beginning of a test suite, ensuring that output is
+   * properly separated and clearly presented. If there is pending output, the
+   * stream is flushed and an empty line is added for clarity. For silent or
+   * quiet verbosity levels, output is suppressed. Otherwise, a message
+   * indicating the start of the test suite is displayed. This approach
+   * enhances the organisation and readability of test results across all test
+   * cases and folders.
+   */
   void
   test_reporter::begin_test_suite (const char* name)
   {
@@ -378,11 +683,28 @@ namespace micro_os_plus::micro_test_plus
         return;
       }
 
+#pragma GCC diagnostic push
+#if defined(__clang__)
+#pragma clang diagnostic ignored "-Wunsafe-buffer-usage-in-libc-call"
+#endif
     printf ("• %s - test suite started\n", name);
+#pragma GCC diagnostic pop
 
     add_empty_line = true;
   }
 
+  /**
+   * @details
+   * This method marks the end of a test suite, summarising the overall results
+   * and presenting them with appropriate formatting and colour coding. If the
+   * suite contains test cases and the verbosity is not set to quiet, an empty
+   * line is added for clarity. For suites with no failed checks and at least
+   * one successful check, a success message is displayed, including the number
+   * of checks and test cases. Otherwise, a failure message is shown, detailing
+   * the number of successful and failed checks, as well as the total number of
+   * test cases. The output is immediately flushed to ensure prompt and
+   * organised reporting across all test cases and folders.
+   */
   void
   test_reporter::end_test_suite (test_suite_base& suite)
   {
@@ -400,15 +722,24 @@ namespace micro_os_plus::micro_test_plus
     // Also fail if none passed.
     if (suite.failed_checks () == 0 && suite.successful_checks () != 0)
       {
+#pragma GCC diagnostic push
+#if defined(__clang__)
+#pragma clang diagnostic ignored "-Wunsafe-buffer-usage-in-libc-call"
+#endif
         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");
+#pragma GCC diagnostic pop
       }
     else
       {
+#pragma GCC diagnostic push
+#if defined(__clang__)
+#pragma clang diagnostic ignored "-Wunsafe-buffer-usage-in-libc-call"
+#endif
         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,
@@ -416,10 +747,20 @@ namespace micro_os_plus::micro_test_plus
                 suite.successful_checks () == 1 ? "check" : "checks",
                 suite.failed_checks (), suite.test_cases (),
                 suite.test_cases () == 1 ? "case" : "cases");
+#pragma GCC diagnostic pop
       }
     flush ();
   }
 
+  /**
+   * @details
+   * This method writes the contents of the internal output buffer to the
+   * standard output stream without appending a newline character. After
+   * outputting the buffer, it is cleared to prepare for subsequent output.
+   * This approach ensures that test results are presented promptly and
+   * efficiently, supporting clear and organised reporting across all test
+   * cases and folders.
+   */
   void
   test_reporter::output (void)
   {