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

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

@@ -0,0 +1,233 @@
+/*
+ * 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.
+ *
+ * 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.
+ */
+
+// ----------------------------------------------------------------------------
+
+/**
+ * @file
+ * @brief C++ header file with declarations for the µTest++ reflection
+ * utilities.
+ *
+ * @details
+ * This header provides the declarations for the reflection utilities used
+ * within the µTest++ framework. It defines interfaces for obtaining source
+ * location information and extracting type names at compile time, supporting
+ * advanced diagnostics and reporting capabilities.
+ *
+ * The reflection utilities include a local implementation of `source_location`
+ * for environments lacking C++20 standard support, as well as functions for
+ * extracting concise type names using compiler-specific macros such as
+ * `__PRETTY_FUNCTION__`. These facilities enable precise identification of
+ * code locations and types in test reports, enhancing the clarity and
+ * professionalism of diagnostic output.
+ *
+ * All definitions reside within the
+ * `micro_os_plus::micro_test_plus::reflection` namespace, ensuring clear
+ * separation from user code and minimising the risk of naming conflicts.
+ *
+ * The header files are organised within the
+ * `include/micro-os-plus/micro-test-plus` folder to maintain a structured and
+ * modular codebase.
+ *
+ * This file is intended solely for internal use within the framework and
+ * should not be included directly by user code.
+ */
+
+#ifndef MICRO_TEST_PLUS_REFLECTION_H_
+#define MICRO_TEST_PLUS_REFLECTION_H_
+
+// ----------------------------------------------------------------------------
+
+#ifdef __cplusplus
+
+// ----------------------------------------------------------------------------
+
+#include <string_view>
+
+#if defined(__cpp_lib_source_location)
+#include <source_location>
+#endif
+
+// ----------------------------------------------------------------------------
+
+#if defined(__GNUC__)
+#pragma GCC diagnostic push
+#pragma GCC diagnostic ignored "-Wpadded"
+#pragma GCC diagnostic ignored "-Waggregate-return"
+#if defined(__clang__)
+#pragma clang diagnostic ignored "-Wc++98-compat"
+#pragma clang diagnostic ignored "-Wunknown-warning-option"
+#endif
+#endif
+
+namespace micro_os_plus::micro_test_plus
+{
+  // --------------------------------------------------------------------------
+
+  /**
+   * @namespace micro_os_plus::micro_test_plus::reflection
+   * @brief Reflection utilities for the µTest++ testing framework.
+   *
+   * @details
+   * The `reflection` namespace provides facilities for obtaining source
+   * location information and type names at compile time, thereby supporting
+   * advanced reporting and diagnostics within the µTest++ framework.
+   *
+   * It includes a local implementation of `source_location` for environments
+   * lacking C++20 standard support, as well as utilities for extracting
+   * concise type names from compiler-specific macros such as
+   * `__PRETTY_FUNCTION__`.
+   *
+   * All definitions within this namespace are intended to facilitate advanced
+   * reflection and reporting capabilities.
+   */
+  namespace reflection
+  {
+    // ------------------------------------------------------------------------
+
+#if defined(__cpp_lib_source_location)
+    /**
+     * @brief Alias for source location information.
+     *
+     * @details
+     * The `source_location` type provides access to source code location
+     * details, such as file name and line number, for enhanced diagnostics and
+     * reporting within the µTest++ framework. When C++20 standard support is
+     * available, this alias refers to `std::source_location`; otherwise, a
+     * local implementation is used to ensure consistent functionality across
+     * all supported environments. This abstraction enables precise
+     * identification of code locations in test reports, supporting clear and
+     * professional diagnostics across all files and folders.
+     */
+    using source_location = std::source_location;
+#else
+    /**
+     * @brief Local implementation of source location information for
+     * diagnostics.
+     *
+     * @details
+     * This class provides a lightweight, constexpr-compatible alternative to
+     * `std::source_location` for environments lacking C++20 standard support.
+     *
+     * It enables retrieval of the file name and line number at the point of
+     * invocation, supporting enhanced diagnostics and reporting within the
+     * µTest++ framework.
+     *
+     * The static `current()` method captures the current source location,
+     * using compiler built-ins where available, or defaulting to `"unknown"`
+     * and zero otherwise.
+     *
+     * @since 3.0.0
+     *
+     * @headerfile micro-test-plus.h <micro-os-plus/micro-test-plus.h>
+     */
+    class source_location
+    {
+    public:
+      /**
+       * @brief Obtain the current source location.
+       *
+       * @param file The file name (automatically provided by the compiler).
+       * @param line The line number (automatically provided by the compiler).
+       * @return A `source_location` instance with the captured information.
+       */
+      [[nodiscard]] static constexpr source_location
+      current (
+#if (__has_builtin(__builtin_FILE) and __has_builtin(__builtin_LINE))
+          const char* file = __builtin_FILE (),
+          unsigned int line = __builtin_LINE ()
+#else
+          const char* file = "unknown", unsigned int line = {}
+#endif
+              ) noexcept;
+
+      /**
+       * @brief Retrieve the file name associated with this source location.
+       *
+       * @par Parameters
+       *	 None.
+       * @return The file name as a constant character pointer.
+       */
+      [[nodiscard]] constexpr auto
+      file_name (void) const noexcept;
+
+      /**
+       * @brief Retrieve the line number associated with this source location.
+       *
+       * @par Parameters
+       *	 None.
+       * @return The line number as an unsigned integer.
+       */
+      [[nodiscard]] constexpr auto
+      line (void) const noexcept;
+
+    private:
+      /**
+       * @brief The file name where the source location was captured.
+       */
+      const char* file_{ "unknown" };
+
+      /**
+       * @brief The line number where the source location was captured.
+       */
+      unsigned int line_{};
+    };
+
+#endif
+
+    /**
+     * @brief Extract a short type or function name from a fully qualified
+     * name.
+     *
+     * @param name The fully qualified name as a C-string.
+     * @return A pointer to the short name within the input string.
+     */
+    const char*
+    short_name (const char* name);
+
+    // TODO: update for the new namespaces.
+
+    /**
+     * @brief Extract the type name from the `__PRETTY_FUNCTION__` macro.
+     *
+     * @tparam T The type whose name is to be extracted.
+     *
+     * @par Parameters
+     *	 None.
+     * @return A `std::string_view` containing the extracted type name.
+     */
+    template <class T>
+    [[nodiscard]] constexpr auto
+    type_name (void) -> std::string_view;
+
+    // ------------------------------------------------------------------------
+  } // namespace reflection
+
+  // --------------------------------------------------------------------------
+} // namespace micro_os_plus::micro_test_plus
+
+#if defined(__GNUC__)
+#pragma GCC diagnostic pop
+#endif
+
+// ----------------------------------------------------------------------------
+
+#endif // __cplusplus
+
+// ----------------------------------------------------------------------------
+
+#endif // MICRO_TEST_PLUS_REFLECTION_H_
+
+// ----------------------------------------------------------------------------

package/include/micro-os-plus/micro-test-plus/test-reporter-basic.h

@@ -0,0 +1,289 @@
+/*
+ * 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.
+ *
+ * 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.
+ */
+
+// ----------------------------------------------------------------------------
+
+/**
+ * @file
+ * @brief C++ header file with declarations for the µTest++ basic test
+ * reporter.
+ *
+ * @details
+ * This header provides the declaration for `test_reporter_basic`, the default
+ * concrete implementation of the `test_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`
+ * instead of using this class.
+ *
+ * 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.
+ *
+ * The header files are organised within the
+ * `include/micro-os-plus/micro-test-plus` folder to maintain a structured and
+ * modular codebase.
+ *
+ * This file is intended solely for internal use within the framework and
+ * should not be included directly by user code.
+ */
+
+#ifndef MICRO_TEST_PLUS_TEST_REPORTER_BASIC_H_
+#define MICRO_TEST_PLUS_TEST_REPORTER_BASIC_H_
+
+// ----------------------------------------------------------------------------
+
+#ifdef __cplusplus
+
+// ----------------------------------------------------------------------------
+
+#include "test-reporter.h"
+
+// ----------------------------------------------------------------------------
+
+#if defined(__GNUC__)
+#pragma GCC diagnostic push
+#pragma GCC diagnostic ignored "-Wpadded"
+#if defined(__clang__)
+#pragma clang diagnostic ignored "-Wc++98-compat"
+#endif
+#endif
+
+namespace micro_os_plus::micro_test_plus
+{
+  // --------------------------------------------------------------------------
+
+  /**
+   * @brief Basic (standard output) implementation of `test_reporter`.
+   *
+   * @details
+   * `test_reporter_basic` provides the default concrete implementation of the
+   * `test_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`
+   * and supply an instance via the `reporter` global pointer before calling
+   * `initialize()`.
+   *
+   * All members and methods are defined within the
+   * `micro_os_plus::micro_test_plus` namespace, ensuring clear separation from
+   * user code and minimising the risk of naming conflicts.
+   *
+   * @headerfile micro-test-plus.h <micro-os-plus/micro-test-plus.h>
+   */
+  class test_reporter_basic final : public test_reporter
+  {
+  public:
+    /**
+     * @brief Constructor for the test_reporter_basic class.
+     *
+     * @details
+     * The rule of five is enforced to prevent accidental copying or moving.
+     */
+    test_reporter_basic ();
+
+    /**
+     * @brief Deleted copy constructor to prevent copying.
+     */
+    test_reporter_basic (const test_reporter_basic&) = delete;
+
+    /**
+     * @brief Deleted move constructor to prevent moving.
+     */
+    test_reporter_basic (test_reporter_basic&&) = delete;
+
+    /**
+     * @brief Deleted copy assignment operator to prevent copying.
+     */
+    test_reporter_basic&
+    operator= (const test_reporter_basic&)
+        = delete;
+
+    /**
+     * @brief Deleted move assignment operator to prevent moving.
+     */
+    test_reporter_basic&
+    operator= (test_reporter_basic&&)
+        = delete;
+
+    /**
+     * @brief Destructor for the test_reporter_basic class.
+     */
+    ~test_reporter_basic () override = default;
+
+    /**
+     * @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.
+     *
+     * @param name The name of the test case.
+     * @par Returns
+     *   Nothing.
+     */
+    void
+    begin_test_case (const char* name) override;
+
+    /**
+     * @brief Mark the end of a test case.
+     *
+     * @param name The name of the test case.
+     * @par Returns
+     *   Nothing.
+     */
+    void
+    end_test_case (const char* name) override;
+
+    /**
+     * @brief Mark the beginning of a test suite.
+     *
+     * @param name The name of the test suite.
+     * @par Returns
+     *   Nothing.
+     */
+    void
+    begin_test_suite (const char* name) 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.
+     * @par Returns
+     *   Nothing.
+     */
+    void
+    begin_test (size_t test_suites_count) override;
+
+    /**
+     * @brief Mark the end of a test.
+     *
+     * @param runner Reference to the test runner.
+     * @par Returns
+     *   Nothing.
+     */
+    void
+    end_test (test_runner& runner) override;
+
+    /**
+     * @brief Flush the current buffered content.
+     *
+     * @par Parameters
+     *	 None.
+     * @par Returns
+     *   Nothing.
+     */
+    void
+    flush (void) override;
+
+    /**
+     * @brief Output the current buffered content.
+     *
+     * @par Parameters
+     *	 None.
+     * @par Returns
+     *   Nothing.
+     */
+    void
+    output (void) override;
+
+  protected:
+    /**
+     * @brief Outputs the prefix for a passing condition.
+     *
+     * @param message The message to display.
+     * @par Returns
+     *   Nothing.
+     */
+    void
+    output_pass_prefix_ (std::string& message) override;
+
+    /**
+     * @brief Outputs the suffix for a passing condition.
+     *
+     * @par Parameters
+     *	 None.
+     * @par Returns
+     *   Nothing.
+     */
+    void
+    output_pass_suffix_ (void) override;
+
+    /**
+     * @brief Outputs the prefix for a failing condition.
+     *
+     * @param message The message to display.
+     * @param hasExpression Whether the failure is associated with an
+     * expression.
+     * @param location The source location of the failure.
+     * @par Returns
+     *   Nothing.
+     */
+    void
+    output_fail_prefix_ (std::string& message, const bool hasExpression,
+                         const reflection::source_location& location) 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.
+     * @par Returns
+     *   Nothing.
+     */
+    void
+    output_fail_suffix_ (const reflection::source_location& location,
+                         bool abort) override;
+  };
+
+  // --------------------------------------------------------------------------
+} // namespace micro_os_plus::micro_test_plus
+
+#if defined(__GNUC__)
+#pragma GCC diagnostic pop
+#endif
+
+// ----------------------------------------------------------------------------
+
+#endif // __cplusplus
+
+// ----------------------------------------------------------------------------
+
+#endif // MICRO_TEST_PLUS_TEST_REPORTER_BASIC_H_
+
+// ----------------------------------------------------------------------------