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

package/meson.build

@@ -1,13 +1,13 @@
 # -----------------------------------------------------------------------------
 #
 # This file is part of the µOS++ project (https://micro-os-plus.github.io/).
-# Copyright (c) 2022 Liviu Ionescu. All rights reserved.
+# Copyright (c) 2022-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.
 #
 # -----------------------------------------------------------------------------
 

package/package.json

@@ -1,31 +1,11 @@
 {
   "name": "@micro-os-plus/micro-test-plus",
-  "version": "3.2.2",
+  "version": "3.2.3",
   "description": "A source code library with µTest++, a lightweight testing framework for embedded platforms",
-  "main": "",
-  "scripts": {
-    "generate-top-commons": "bash node_modules/@xpack/npm-packages-helper/maintenance-scripts/generate-top-commons.sh --micro-os-plus",
-    "npm-install": "npm install",
-    "npm-link-helpers": "npm link @xpack/npm-packages-helper @xpack/docusaurus-template-liquid",
-    "npm-outdated": "npm outdated",
-    "npm-pack": "npm pack",
-    "npm-link": "npm link",
-    "npm-version-patch": "npm version patch",
-    "npm-version-minor": "npm version minor",
-    "git-log": "git log --pretty='%cd * %h %s' --date=short",
-    "git-pull-helper": "git -C ${HOME}/Work/micro-os-plus/build-helper-xpack.git pull",
-    "deep-clean": "del-cli node_modules package-lock.json *.tgz",
-    "postversion": "git push origin --all && git push origin --tags"
-  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/micro-os-plus/micro-test-plus-xpack.git"
   },
-  "bugs": {
-    "url": "https://github.com/micro-os-plus/micro-test-plus-xpack/issues"
-  },
-  "homepage": "https://micro-os-plus.github.io/micro-test-plus-xpack/",
-  "homepagePreview": "https://micro-os-plus.github.io/micro-test-plus-xpack-webpreview/",
   "keywords": [
     "xpack",
     "micro-os-plus",
@@ -39,23 +19,38 @@
     "url": "https://github.com/ilg-ul"
   },
   "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/micro-os-plus/micro-test-plus-xpack/issues"
+  },
+  "homepage": "https://micro-os-plus.github.io/micro-test-plus-xpack/",
+  "homepagePreview": "https://micro-os-plus.github.io/micro-test-plus-xpack-webpreview/",
+  "$dependenciesUrls": {
+    "del-cli": "https://www.npmjs.com/package/del-cli",
+    "json": "https://www.npmjs.com/package/json",
+    "liquidjs": "https://www.npmjs.com/package/liquidjs"
+  },
   "dependencies": {},
-  "$devDependenciesUrls": [
-    "https://www.npmjs.com/package/del-cli",
-    "https://www.npmjs.com/package/json",
-    "https://www.npmjs.com/package/liquidjs"
-  ],
   "devDependencies": {
-    "del-cli": "^6.0.0",
+    "@xpack/npm-packages-helper": "github:xpack/npm-packages-helper",
+    "del-cli": "^7.0.0",
     "json": "^11.0.0",
-    "liquidjs": "^10.19.1"
+    "liquidjs": "^10.25.0"
+  },
+  "scripts": {
+    "generate-top-commons": "bash node_modules/@xpack/npm-packages-helper/maintenance-scripts/generate-top-commons.sh --micro-os-plus",
+    "npm-install": "npm install",
+    "npm-link-helpers": "npm link @xpack/npm-packages-helper",
+    "npm-outdated": "npm outdated",
+    "npm-ci": "npm ci",
+    "npm-pack": "npm pack",
+    "npm-link": "npm link",
+    "git-log": "git log --pretty='%cd * %h %s' --date=short",
+    "git-pull-helper": "git -C ${HOME}/Work/micro-os-plus/build-helper-xpack.git pull",
+    "deep-clean": "del-cli node_modules package-lock.json *.tgz",
+    "postversion": "git push origin --all && git push origin --tags"
   },
   "xpack": {
-    "minimumXpmRequired": "0.20.8",
-    "dependencies": {},
-    "devDependencies": {},
-    "properties": {},
-    "buildConfigurations": {}
+    "minimumXpmRequired": "0.20.8"
   },
   "topConfig": {
     "descriptiveName": "µTest++ Testing Framework",
@@ -63,6 +58,6 @@
     "useDoxygen": "true"
   },
   "engines": {
-    "node": " >=18.0.0"
+    "node": ">=20.0"
   }
 }

package/src/micro-test-plus.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,31 @@
 
 // ----------------------------------------------------------------------------
 
+/**
+ * @file
+ * @brief C++ source file with implementations for the µTest++ methods.
+ *
+ * @details
+ * This source file contains the core implementations for the µTest++ testing
+ * framework, including initialisation and shutdown routines, utility
+ * functions, and the management of global framework state. It provides the
+ * logic for setting up the test environment, registering and executing test
+ * suites, reporting results, and supporting utility operations such as file
+ * name extraction and pattern-based string matching.
+ *
+ * All definitions are contained within the `micro_os_plus::micro_test_plus`
+ * namespace and its nested namespaces, ensuring clear separation from user
+ * code and minimising the risk of naming conflicts.
+ *
+ * The implementation is optimised for embedded environments, avoiding heavy
+ * dependencies and providing lightweight, efficient mechanisms for test
+ * execution and reporting.
+ *
+ * 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
@@ -42,15 +67,15 @@ namespace micro_os_plus::micro_test_plus
 
   /**
    * @details
-   * All tests include a default test suite, which runs the test cases
-   * defined in the main function.
-   *
-   * This function forwards the process arguments to the test framework
-   * and initialises the runner.
-   *
-   * The name is used to identify the default test suite.
+   * The `initialize` function sets up the µTest++ testing framework, preparing
+   * it for test execution. It processes command-line arguments, configures the
+   * test environment, and establishes the default test suite name. This
+   * function should be called at the beginning of the test programme,
+   * typically from the `main()` function, to ensure proper initialisation of
+   * all framework components.
    *
-   * The arguments can be used to control the verbosity level.
+   * The provided arguments may be used to configure verbosity or other
+   * run-time options for the test session.
    */
   void
   initialize (int argc, char* argv[], const char* name)
@@ -63,15 +88,21 @@ namespace micro_os_plus::micro_test_plus
 
   /**
    * @details
-   * In addition to the test cases defined in `main()`, there can be
-   * more separate **test suites**, defined as static objects in the same
-   * file or in other files,
-   * and self-registered via the static constructors mechanism.
+   * In addition to the test cases defined in `main()`, additional test suites
+   * may be declared as static objects either within the same file or in other
+   * files, and are automatically registered via the static constructors
+   * mechanism.
    *
-   * This function triggers the execution of the globally
-   * registered test suites
-   * (if any) and returns the test result as the process exit code
-   * (0 = success).
+   * The `exit_code` function finalises the execution of all registered test
+   * suites and test cases within the µTest++ framework, and returns an
+   * appropriate exit code to the operating system. This function should be
+   * called at the end of the test program, typically from the `main()`
+   * function, to ensure that all results are properly reported and the correct
+   * status is communicated.
+   *
+   * The returned value indicates the overall success or failure of the test
+   * run, allowing integration with build systems and continuous integration
+   * environments.
    */
   int
   exit_code (void)
@@ -84,6 +115,15 @@ namespace micro_os_plus::micro_test_plus
   namespace reflection
   {
 
+    /**
+     * @details
+     * This function extracts the short name from a given file path by locating
+     * the final folder separator ('/'). If a separator is found, it returns a
+     * pointer to the character immediately following it, effectively providing
+     * the file or folder name. If no separator is present, the original input
+     * string is returned. This utility is useful for reporting concise file or
+     * folder names in test output.
+     */
     const char*
     short_name (const char* name)
     {
@@ -107,20 +147,23 @@ namespace micro_os_plus::micro_test_plus
 #pragma clang diagnostic push
 #pragma clang diagnostic ignored "-Wdocumentation"
 #endif
-    /**
-     * @details
-     * For tests comparing strings, in addition to exact matches,
-     * it is also possible to check matches with patterns like `*`
-     * (for any characters) and `?` (for a single character)
-     *
-     * @par Examples
-     * ```cpp
-     * namespace mt = micro_os_plus::micro_test_plus;
-     *
-     * mt::expect (mt::utility::is_match ("abc", "a?c")) << "abc matches a?c";
-     * mt::expect (mt::utility::is_match ("abc", "a*c")) << "abc matches a*c";
-     * ```
-     */
+/**
+ * @details
+ * This function enables pattern-based string comparison for tests, supporting
+ * both exact matches and wildcard patterns. The pattern may include `*` to
+ * match any sequence of characters and `?` to match any single character. This
+ * allows for flexible validation of string content in test assertions,
+ * accommodating variable or partially known values.
+ *
+ * @par Examples
+ *
+ * @code{.cpp}
+ * namespace mt = micro_os_plus::micro_test_plus;
+ *
+ * mt::expect (mt::utility::is_match ("abc", "a?c")) << "abc matches a?c";
+ * mt::expect (mt::utility::is_match ("abc", "a*c")) << "abc matches a*c";
+ * @endcode
+ */
 #if defined(__clang__)
 #pragma clang diagnostic pop
 #endif
@@ -163,6 +206,15 @@ namespace micro_os_plus::micro_test_plus
 
   namespace detail
   {
+    /**
+     * @details
+     * This constructor updates the current test suite's statistics based on
+     * the outcome of the test expression. If the evaluated value is true, the
+     * count of successful tests is incremented; otherwise, the count of failed
+     * tests is incremented. The source location is recorded for reporting
+     * purposes, enabling precise identification of the test case within the
+     * relevant file or folder.
+     */
     deferred_reporter_base::deferred_reporter_base (
         bool value, const reflection::source_location location)
         : value_{ value }, location_{ location }
@@ -177,6 +229,14 @@ namespace micro_os_plus::micro_test_plus
         }
     }
 
+    /**
+     * @details
+     * The destructor ensures that if an abort condition is set and the test
+     * expression has failed, the test output is flushed and the process is
+     * terminated. This mechanism guarantees immediate feedback and halts
+     * further execution upon critical test failures, aiding in rapid
+     * identification and resolution of issues during test runs.
+     */
     deferred_reporter_base::~deferred_reporter_base ()
     {
 #if 0 // defined(MICRO_OS_PLUS_TRACE_MICRO_TEST_PLUS)
@@ -204,9 +264,45 @@ namespace micro_os_plus::micro_test_plus
 #endif
 
   // Static instances;
+  /**
+   * @brief Global instance of `test_runner`.
+   *
+   * @details
+   * This global instance of `test_runner` manages the lifecycle of test suites
+   * and test cases within the µTest++ framework. It is responsible for
+   * initialising the test environment, registering test suites, executing
+   * tests, and collecting results. By maintaining a single shared runner, the
+   * framework ensures consistent test execution and reporting across all test
+   * cases and folders.
+   */
   test_runner runner;
+
+  /**
+   * @brief Global instance of `test_reporter`.
+   *
+   * @details
+   * This global instance of `test_reporter` is responsible for collecting,
+   * formatting, and outputting the results of test execution within the
+   * µTest++ framework. It manages the reporting of test outcomes, including
+   * successes and failures, and ensures that all relevant information is
+   * presented clearly to the user. By maintaining a single shared reporter,
+   * the framework provides consistent and centralised reporting across all
+   * test cases and folders.
+   */
   test_reporter reporter;
 
+  /**
+   * @brief Global pointer references the currently active test suite.
+   *
+   * @details
+   * This global pointer references the currently active test suite within the
+   * µTest++ framework. It is used to track and update the state of the test
+   * suite during test execution, including recording test results and
+   * statistics. By maintaining a pointer to the current test suite, the
+   * framework ensures accurate association of test outcomes with their
+   * respective suites, supporting clear and organised reporting across all
+   * test cases and folders.
+   */
   test_suite_base* current_test_suite;
 
 #if defined(__GNUC__)