orionis 0.432.0__py3-none-any.whl → 0.435.0__py3-none-any.whl

orionis/test/core/unit_test.py

@@ -51,81 +51,68 @@ class UnitTest(IUnitTest):
 
     Advanced unit testing manager for the Orionis framework.
 
-    This class offers a robust and extensible solution for discovering, executing, and reporting unit tests with high configurability. It supports both sequential and parallel execution modes, filtering by test name or tags, and provides detailed result tracking including execution times, error messages, and tracebacks.
-
-    Key features:
-    - Flexible test discovery from folders or modules, with pattern and tag filtering.
-    - Rich result reporting: console output, persistent storage (SQLite or JSON), and web-based reports.
-    - Dependency injection for test methods via the application context.
-    - Customizable verbosity, fail-fast, and exception handling options.
-    - Designed for easy integration into CI/CD pipelines and adaptable to diverse project requirements.
-
-    Orionis UnitTest is ideal for teams seeking enhanced traceability, reliability, and visibility in automated testing, with capabilities that go beyond standard unittest frameworks.
+    This class provides mechanisms for discovering, executing, and reporting unit tests with extensive configurability. It supports sequential and parallel execution, test filtering by name or tags, and detailed result tracking including execution times, error messages, and tracebacks.
+
+    Attributes
+    ----------
+    __app : Optional[IApplication]
+        Application instance for dependency injection.
+    __verbosity : Optional[int]
+        Verbosity level for test output.
+    __execution_mode : Optional[str]
+        Execution mode for tests ('SEQUENTIAL' or 'PARALLEL').
+    __max_workers : Optional[int]
+        Maximum number of workers for parallel execution.
+    __fail_fast : Optional[bool]
+        Whether to stop on first failure.
+    __throw_exception : Optional[bool]
+        Whether to raise exceptions on test failures.
+    __persistent : Optional[bool]
+        Whether to persist test results.
+    __persistent_driver : Optional[str]
+        Persistence driver ('sqlite' or 'json').
+    __web_report : Optional[bool]
+        Whether to generate a web report.
+    __folder_path : Optional[str]
+        Folder path for test discovery.
+    __base_path : Optional[str]
+        Base directory for test discovery.
+    __pattern : Optional[str]
+        File name pattern for test discovery.
+    __test_name_pattern : Optional[str]
+        Pattern for filtering test names.
+    __tags : Optional[List[str]]
+        Tags for filtering tests.
+    __module_name : Optional[str]
+        Module name for test discovery.
+    __loader : unittest.TestLoader
+        Loader for discovering tests.
+    __suite : unittest.TestSuite
+        Test suite containing discovered tests.
+    __discovered_tests : List
+        List of discovered test metadata.
+    __printer : Optional[TestPrinter]
+        Utility for printing test results.
+    __output_buffer : Optional[str]
+        Buffer for capturing standard output.
+    __error_buffer : Optional[str]
+        Buffer for capturing error output.
+    __result : Optional[dict]
+        Result summary of the test execution.
     """
 
     def __init__(
         self
     ) -> None:
         """
-        Initialize a new UnitTest instance with default configuration and internal state.
+        Initialize a UnitTest instance with default configuration and internal state.
 
-        This constructor sets up all internal attributes required for test discovery, execution,
-        result reporting, and configuration management. It prepares the instance for further
-        configuration and use, but does not perform any test discovery or execution itself.
-
-        Attributes
-        ----------
-        __app : Optional[IApplication]
-            The application instance used for dependency injection in test cases.
-        __verbosity : Optional[int]
-            Verbosity level for test output (None until configured).
-        __execution_mode : Optional[str]
-            Test execution mode, e.g., 'SEQUENTIAL' or 'PARALLEL' (None until configured).
-        __max_workers : Optional[int]
-            Maximum number of worker threads/processes for parallel execution (None until configured).
-        __fail_fast : Optional[bool]
-            If True, stops execution upon the first test failure (None until configured).
-        __throw_exception : Optional[bool]
-            If True, raises exceptions on test failures (None until configured).
-        __persistent : Optional[bool]
-            If True, enables persistent storage for test results (None until configured).
-        __persistent_driver : Optional[str]
-            The driver to use for persistence, e.g., 'sqlite' or 'json' (None until configured).
-        __web_report : Optional[bool]
-            If True, enables web-based reporting of test results (None until configured).
-        __folder_path : Optional[str]
-            Relative folder path for test discovery (None until set).
-        __base_path : Optional[str]
-            Base directory for test discovery (None until set).
-        __pattern : Optional[str]
-            File name pattern to match test files (None until set).
-        __test_name_pattern : Optional[str]
-            Pattern to filter test names (None until set).
-        __tags : Optional[List[str]]
-            List of tags to filter tests (None until set).
-        __module_name : Optional[str]
-            Name of the module for test discovery (None until set).
-        __loader : unittest.TestLoader
-            Loader for discovering tests.
-        __suite : unittest.TestSuite
-            Test suite containing discovered tests.
-        __discovered_tests : List
-            List of discovered test metadata.
-        __printer : Optional[TestPrinter]
-            Utility for printing test results to the console.
-        __output_buffer : Optional[str]
-            Buffer for capturing standard output during tests.
-        __error_buffer : Optional[str]
-            Buffer for capturing error output during tests.
-        __result : Optional[dict]
-            Result summary of the test execution.
+        Sets up all internal attributes required for test discovery, execution, result reporting, and configuration management. Does not perform test discovery or execution.
 
         Returns
         -------
         None
-            This constructor does not return a value.
         """
-
         # Application instance for dependency injection (set via __setApp)
         self.__app: Optional[IApplication] = None
 
@@ -181,42 +168,38 @@ class UnitTest(IUnitTest):
         web_report: bool
     ) -> 'UnitTest':
         """
-        Configures the UnitTest instance with the main execution and reporting parameters.
-
-        This method sets all relevant options for running unit tests in Orionis, including execution mode
-        (sequential or parallel), verbosity level, maximum number of workers, result persistence, exception
-        handling, and web report generation.
+        Configure the UnitTest instance with execution and reporting parameters.
 
         Parameters
         ----------
-        verbosity : int | VerbosityMode
-            Verbosity level for test output. Can be an integer or a VerbosityMode enum member.
-        execution_mode : str | ExecutionMode
-            Test execution mode ('SEQUENTIAL' or 'PARALLEL'), as a string or ExecutionMode enum.
+        verbosity : int or VerbosityMode
+            Verbosity level for test output.
+        execution_mode : str or ExecutionMode
+            Execution mode ('SEQUENTIAL' or 'PARALLEL').
         max_workers : int
-            Maximum number of threads/processes for parallel execution. Must be between 1 and the maximum allowed by Workers.
+            Maximum number of workers for parallel execution.
         fail_fast : bool
-            If True, stops execution on the first failure.
+            Whether to stop on the first failure.
         print_result : bool
-            If True, prints results to the console.
+            Whether to print results to the console.
         throw_exception : bool
-            If True, raises exceptions on test failures.
+            Whether to raise exceptions on test failures.
         persistent : bool
-            If True, enables result persistence.
+            Whether to enable result persistence.
         persistent_driver : str or PersistentDrivers
-            Persistence driver to use ('sqlite' or 'json').
+            Persistence driver ('sqlite' or 'json').
         web_report : bool
-            If True, enables web report generation.
+            Whether to enable web report generation.
 
         Returns
         -------
         UnitTest
-            The configured UnitTest instance, allowing method chaining.
+            The configured UnitTest instance.
 
         Raises
         ------
         OrionisTestValueError
-            If any parameter is invalid or does not meet the expected requirements.
+            If any parameter is invalid.
         """
 
         # Validate and assign parameters using specialized validators
@@ -249,48 +232,29 @@ class UnitTest(IUnitTest):
         """
         Discover and add unit tests from a specified folder to the test suite.
 
-        This method searches for test files within a given folder, using a file name pattern,
-        and optionally filters discovered tests by test name pattern and tags. All matching
-        tests are added to the internal test suite. The method also records metadata about
-        the discovery process, such as the folder path and the number of tests found.
-
         Parameters
         ----------
         base_path : str or Path
-            The base directory from which the folder path is resolved.
+            Base directory for resolving the folder path.
         folder_path : str
-            The relative path to the folder containing test files, relative to `base_path`.
+            Relative path to the folder containing test files.
         pattern : str
-            The file name pattern to match test files (e.g., 'test_*.py').
+            File name pattern to match test files.
         test_name_pattern : str, optional
-            A regular expression pattern to filter test names. Only tests whose names match
-            this pattern will be included. If None, all test names are included.
+            Regular expression pattern to filter test names.
         tags : list of str, optional
-            A list of tags to filter tests. Only tests decorated or marked with any of these
-            tags will be included. If None, no tag filtering is applied.
+            Tags to filter tests.
 
         Returns
         -------
         UnitTest
-            The current instance with the discovered tests added to the suite.
+            The current instance with discovered tests added.
 
         Raises
         ------
         OrionisTestValueError
-            If any argument is invalid, the folder does not exist, no tests are found,
-            or if there are import or discovery errors.
-
-        Notes
-        -----
-        - The method validates all input parameters using Orionis validators.
-        - The folder path is resolved relative to the provided base path.
-        - Test discovery uses Python's unittest loader.
-        - If `test_name_pattern` is provided, only tests whose names match the pattern are included.
-        - If `tags` are provided, only tests with matching tags are included.
-        - If no tests are found after filtering, an exception is raised.
-        - Metadata about the discovery (folder and test count) is appended to the internal record.
+            If arguments are invalid, folder does not exist, no tests are found, or import/discovery errors occur.
         """
-
         # Validate Parameters
         self.__base_path = ValidBasePath(base_path)
         self.__folder_path = ValidFolderPath(folder_path)
@@ -321,15 +285,17 @@ class UnitTest(IUnitTest):
             # Check for failed test imports (unittest.loader._FailedTest)
             for test in self.__flattenTestSuite(tests):
                 if test.__class__.__name__ == "_FailedTest":
+
                     # Extract the error message from the test's traceback
                     error_message = ""
                     if hasattr(test, "_exception"):
                         error_message = str(test._exception)
                     elif hasattr(test, "_outcome") and hasattr(test._outcome, "errors"):
                         error_message = str(test._outcome.errors)
+                    # Try to get error from test id or str(test)
                     else:
-                        # Try to get error from test id or str(test)
                         error_message = str(test)
+
                     raise OrionisTestValueError(
                         f"Failed to import test module: {test.id()}.\n"
                         f"Error details: {error_message}\n"
@@ -400,38 +366,22 @@ class UnitTest(IUnitTest):
         """
         Discover and add unit tests from a specified Python module to the test suite.
 
-        This method loads all unit tests defined within the given module and adds them to the internal test suite.
-        Optionally, it can filter discovered tests by a regular expression pattern applied to test names.
-
         Parameters
         ----------
         module_name : str
-            The fully qualified name of the module from which to discover tests (e.g., 'myproject.tests.test_example').
-            Must be a non-empty string and importable from the current environment.
-        test_name_pattern : str or None, optional
-            A regular expression pattern to filter test names. Only tests whose names match this pattern
-            will be included in the suite. If None, all discovered tests are included.
+            Fully qualified name of the module to discover tests from.
+        test_name_pattern : str, optional
+            Regular expression pattern to filter test names.
 
         Returns
         -------
         UnitTest
-            The current UnitTest instance with the discovered tests added, allowing method chaining.
+            The current UnitTest instance with discovered tests added.
 
         Raises
         ------
         OrionisTestValueError
-            If `module_name` is invalid, `test_name_pattern` is not a valid regex, the module cannot be imported,
-            or if no tests are found after filtering.
-        OrionisTestValueError
-            For any unexpected error during test discovery, with details about the failure.
-
-        Notes
-        -----
-        - Input parameters are validated using Orionis validators before discovery.
-        - If `test_name_pattern` is provided, only tests matching the pattern are included.
-        - Metadata about the discovery (module name and test count) is appended to the internal `__discovered_tests` list.
-        - This method is useful for dynamically loading tests from specific modules, such as in plugin architectures or
-          when tests are not organized in standard file patterns.
+            If module_name is invalid, test_name_pattern is not a valid regex, the module cannot be imported, or no tests are found.
         """
 
         # Validate input parameters
@@ -503,28 +453,16 @@ class UnitTest(IUnitTest):
         """
         Execute the test suite and return a summary of the results.
 
-        This method manages the full test execution lifecycle: it prints start and finish messages,
-        executes the test suite, captures output and error buffers, processes the results, and
-        optionally raises an exception if failures occur and exception throwing is enabled.
-
         Returns
         -------
-        Dict[str, Any]
-            A dictionary summarizing the test results, including statistics and execution time.
+        dict
+            Dictionary summarizing the test results, including statistics and execution time.
 
         Raises
         ------
         OrionisTestFailureException
-            If the test suite execution fails and `throw_exception` is set to True.
-
-        Notes
-        -----
-        - Measures total execution time in milliseconds.
-        - Uses the configured printer to display start, result, and finish messages.
-        - Captures and stores output and error buffers.
-        - Raises an exception if tests fail and exception throwing is enabled.
+            If the test suite execution fails and throw_exception is True.
         """
-
         # Record the start time in nanoseconds
         start_time = time.time_ns()
 
@@ -569,161 +507,122 @@ class UnitTest(IUnitTest):
         suite: unittest.TestSuite
     ) -> List[unittest.TestCase]:
         """
-        Recursively flattens a (potentially nested) unittest.TestSuite into a list of unique unittest.TestCase instances.
-
-        This method traverses the provided test suite, which may contain nested suites or individual test cases,
-        and collects all unique TestCase instances into a flat list. It ensures that each test case appears only once
-        in the resulting list, based on a short identifier derived from the test's id. This is particularly useful
-        for operations that require direct access to all test cases, such as filtering, counting, or custom execution.
+        Recursively flattens a unittest.TestSuite into a list of unique unittest.TestCase instances.
 
         Parameters
         ----------
         suite : unittest.TestSuite
-            The test suite to flatten. This can be a single suite, a nested suite, or a suite containing test cases.
+            The test suite to be flattened.
 
         Returns
         -------
         List[unittest.TestCase]
-            A flat list containing all unique unittest.TestCase instances found within the input suite.
+            A flat list containing unique unittest.TestCase instances extracted from the suite.
 
         Notes
         -----
-        - The uniqueness of test cases is determined by a "short id", which is composed of the last two segments
-          of the test's full id (typically "ClassName.methodName"). This helps avoid duplicate test cases in the result.
-        - The method uses recursion to traverse all levels of nested suites.
-        - Only objects with an 'id' attribute (i.e., test cases) are included in the result.
+        Test uniqueness is determined by a shortened test identifier (the last two components of the test id).
+        This helps avoid duplicate test cases in the returned list.
         """
+
+        # Initialize an empty list to hold unique test cases and a set to track seen test IDs
         tests = []
         seen_ids = set()
 
+        # Recursive function to flatten the test suite
         def _flatten(item):
-            """
-            Recursively process a TestSuite or test case, collecting unique test cases.
-
-            - If the item is a TestSuite, recursively process its children.
-            - If the item is a test case (has 'id'), generate a short id and add it if not already seen.
-            """
             if isinstance(item, unittest.TestSuite):
-                # Recursively flatten all sub-items in the suite
                 for sub_item in item:
                     _flatten(sub_item)
             elif hasattr(item, "id"):
-                # Generate a short id for uniqueness (e.g., "ClassName.methodName")
                 test_id = item.id()
+
+                # Use the last two components of the test id for uniqueness
                 parts = test_id.split('.')
                 if len(parts) >= 2:
                     short_id = '.'.join(parts[-2:])
                 else:
                     short_id = test_id
-                # Add the test case only if its short id has not been seen
                 if short_id not in seen_ids:
                     seen_ids.add(short_id)
                     tests.append(item)
 
-        # Start flattening from the root suite
+        # Start the flattening process
         _flatten(suite)
-
-        # Return a flat list of unique unittest.TestCase instances
         return tests
 
     def __runSuite(
         self
     ) -> Tuple[unittest.TestResult, io.StringIO, io.StringIO]:
         """
-        Executes the test suite using the configured execution mode (sequential or parallel),
-        while capturing both standard output and error streams during the test run.
-
-        This method determines the execution mode (sequential or parallel) based on the current
-        configuration and delegates the actual test execution to the appropriate internal method.
-        It ensures that all output and error messages generated during the test run are captured
-        in dedicated buffers for later inspection or reporting.
+        Executes the test suite according to the configured execution mode, capturing both standard output and error streams.
 
         Returns
         -------
-        Tuple[unittest.TestResult, io.StringIO, io.StringIO]
-            A tuple containing:
-                - result: The unittest.TestResult object with detailed information about the test run,
-                  including passed, failed, errored, and skipped tests.
-                - output_buffer: An io.StringIO object containing all captured standard output produced
-                  during the test execution.
-                - error_buffer: An io.StringIO object containing all captured standard error output
-                  produced during the test execution.
-
-        Notes
-        -----
-        - The execution mode is determined by the value of self.__execution_mode.
-        - Output and error streams are always captured, regardless of execution mode.
-        - The returned buffers can be used for further processing, logging, or displaying test output.
+        tuple
+            result : unittest.TestResult
+                The result object containing the outcomes of the executed tests.
+            output_buffer : io.StringIO
+                Buffer capturing the standard output generated during test execution.
+            error_buffer : io.StringIO
+                Buffer capturing the standard error generated during test execution.
         """
 
-        # Create buffers to capture standard output and error during test execution
+        # Initialize output and error buffers to capture test execution output
         output_buffer = io.StringIO()
         error_buffer = io.StringIO()
 
-        # Determine execution mode and run tests accordingly
+        # Run tests in parallel mode using multiple workers
         if self.__execution_mode == ExecutionMode.PARALLEL.value:
-            # Run tests in parallel mode
             result = self.__runTestsInParallel(
                 output_buffer,
                 error_buffer
             )
+
+        # Run tests sequentially
         else:
-            # Run tests sequentially (default)
             result = self.__runTestsSequentially(
                 output_buffer,
                 error_buffer
             )
 
-        # Return the test result along with the captured output and error buffers
+        # Return the result, output, and error buffers
         return result, output_buffer, error_buffer
 
     def __resolveFlattenedTestSuite(
         self
     ) -> unittest.TestSuite:
         """
-        Resolves and injects dependencies for all test cases in the suite, returning a flattened TestSuite.
+        Resolves and injects dependencies for all test cases in the current suite, returning a flattened TestSuite.
 
-        This method processes each test case in the internal suite, inspects the test method signatures,
-        and uses the application's dependency resolver to inject any required dependencies. It handles
-        decorated methods, methods without dependencies, and raises errors for unresolved dependencies.
-        The result is a new, flat unittest.TestSuite containing test cases with all dependencies resolved
-        and injected, ready for execution.
-
-        Parameters
-        ----------
-        None
+        This method iterates through all test cases in the suite, checks for failed imports, decorated methods, and unresolved dependencies.
+        For each test case, it uses reflection to determine the test method and its dependencies. If dependencies are required and can be resolved,
+        it injects them using the application's resolver. If a test method has unresolved dependencies, an exception is raised.
+        Decorated methods and failed imports are added as-is. The resulting TestSuite contains all test cases with dependencies injected where needed.
 
         Returns
         -------
         unittest.TestSuite
-            A new TestSuite containing all test cases from the original suite, with dependencies injected
-            where required. Test cases with unresolved dependencies will cause an exception to be raised.
+            A new TestSuite containing all test cases with dependencies injected as required.
 
         Raises
         ------
         OrionisTestValueError
-            If any test method has dependencies that cannot be resolved.
-
-        Notes
-        -----
-        - Decorated test methods are left unchanged and added as-is.
-        - Test methods without dependencies are added directly.
-        - Test methods with unresolved dependencies will trigger an error.
-        - The returned TestSuite is flat and contains all processed test cases.
+            If any test method has unresolved dependencies that cannot be resolved by the resolver.
         """
 
-        # Create a new test suite to hold test cases with dependencies resolved
+        # Create a new TestSuite to hold the resolved test cases
         flattened_suite = unittest.TestSuite()
 
-        # Iterate through all test cases in the original (possibly nested) suite
+        # Iterate through all test cases in the flattened suite
         for test_case in self.__flattenTestSuite(self.__suite):
 
-            # If it's a failed test, add it as-is to the flattened suite
+            # If the test case is a failed import, add it directly
             if test_case.__class__.__name__ == "_FailedTest":
                 flattened_suite.addTest(test_case)
                 continue
 
-            # Get the test method name using reflection
+            # Use reflection to get the test method name
             rf_instance = ReflectionInstance(test_case)
             method_name = rf_instance.getAttribute("_testMethodName")
 
@@ -732,30 +631,29 @@ class UnitTest(IUnitTest):
                 flattened_suite.addTest(test_case)
                 continue
 
-            # Retrieve the actual test method object from the class
+            # Retrieve the test method from the class
             test_method = getattr(test_case.__class__, method_name, None)
 
-            # Check if the test method is decorated by looking for __wrapped__ attributes
+            # Check if the method is decorated (wrapped)
             decorators = []
             if hasattr(test_method, '__wrapped__'):
                 original = test_method
                 while hasattr(original, '__wrapped__'):
-                    # Collect decorator names for informational purposes
                     if hasattr(original, '__qualname__'):
                         decorators.append(original.__qualname__)
                     elif hasattr(original, '__name__'):
                         decorators.append(original.__name__)
                     original = original.__wrapped__
 
-            # If decorators are present, add the test case as-is (do not inject dependencies)
+            # If decorators are present, add the test case as-is
             if decorators:
                 flattened_suite.addTest(test_case)
                 continue
 
-            # Attempt to extract dependency information from the test method signature
+            # Get the method's dependency signature
             signature = rf_instance.getMethodDependencies(method_name)
 
-            # If there are no dependencies to resolve, or unresolved dependencies exist, add as-is
+            # If no dependencies are required or unresolved, add the test case as-is
             if ((not signature.resolved and not signature.unresolved) or (not signature.resolved and len(signature.unresolved) > 0)):
                 flattened_suite.addTest(test_case)
                 continue
@@ -767,32 +665,25 @@ class UnitTest(IUnitTest):
                     "Please ensure all dependencies are correctly defined and available."
                 )
 
-            # All dependencies are resolved; prepare to inject them into the test method
+            # Get the original test class and method
             test_class = ReflectionInstance(test_case).getClass()
             original_method = getattr(test_class, method_name)
 
             # Resolve dependencies using the application's resolver
             params = Resolver(self.__app).resolveSignature(signature)
 
-            # Create a wrapper function that injects resolved dependencies into the test method
+            # Create a wrapper to inject resolved dependencies into the test method
             def create_test_wrapper(original_test, resolved_args: dict):
                 def wrapper(self_instance):
                     return original_test(self_instance, **resolved_args)
                 return wrapper
 
-            # Wrap the original test method with the dependency-injecting wrapper
-            wrapped_method = create_test_wrapper(original_method, params)
-
             # Bind the wrapped method to the test case instance
+            wrapped_method = create_test_wrapper(original_method, params)
             bound_method = wrapped_method.__get__(test_case, test_case.__class__)
-
-            # Replace the original test method on the test case with the wrapped version
             setattr(test_case, method_name, bound_method)
-
-            # Add the modified test case to the flattened suite
             flattened_suite.addTest(test_case)
 
-        # Return the new flattened suite with all dependencies resolved and injected
         return flattened_suite
 
     def __runTestsSequentially(
@@ -801,31 +692,45 @@ class UnitTest(IUnitTest):
         error_buffer: io.StringIO
     ) -> unittest.TestResult:
         """
-        Executes the test suite sequentially, capturing the output and error streams.
+        Executes all test cases in the test suite sequentially, capturing standard output and error streams.
 
         Parameters
         ----------
         output_buffer : io.StringIO
-            A buffer to capture the standard output during test execution.
+            Buffer to capture the standard output generated during test execution.
         error_buffer : io.StringIO
-            A buffer to capture the standard error during test execution.
+            Buffer to capture the standard error generated during test execution.
 
         Returns
         -------
         unittest.TestResult
-            The result of the test suite execution, containing information about
-            passed, failed, and skipped tests.
+            The aggregated result object containing the outcomes of all executed test cases.
+
+        Raises
+        ------
+        OrionisTestValueError
+            If an item in the suite is not a valid unittest.TestCase instance.
+
+        Notes
+        -----
+        Each test case is executed individually, and results are merged into a single result object.
+        Output and error streams are redirected for each test case to ensure complete capture.
+        The printer is used to display the result of each test immediately after execution.
         """
 
-        # Create a custom result class to capture detailed test results
+        # Initialize output and error buffers to capture test execution output
         result = None
+
+        # Iterate through all resolved test cases in the suite
         for case in self.__resolveFlattenedTestSuite():
 
+            # Ensure the test case is a valid unittest.TestCase instance
             if not isinstance(case, unittest.TestCase):
                 raise OrionisTestValueError(
                     f"Invalid test case type: Expected unittest.TestCase, got {type(case).__name__}."
                 )
 
+            # Redirect output and error streams for the current test case
             with redirect_stdout(output_buffer), redirect_stderr(error_buffer):
                 runner = unittest.TextTestRunner(
                     stream=output_buffer,
@@ -833,18 +738,19 @@ class UnitTest(IUnitTest):
                     failfast=self.__fail_fast,
                     resultclass=self.__customResultClass()
                 )
+                # Run the current test case and obtain the result
                 single_result: IOrionisTestResult = runner.run(unittest.TestSuite([case]))
 
-            # Print a concise summary for each test.
+            # Print the result of the current test case using the printer
             self.__printer.unittestResult(single_result.test_results[0])
 
-            # Merge results
+            # Merge the result of the current test case into the aggregated result
             if result is None:
                 result = single_result
             else:
                 self.__mergeTestResults(result, single_result)
 
-        # Return the result object containing test outcomes
+        # Return the aggregated result containing all test outcomes
         return result
 
     def __runTestsInParallel(
@@ -853,82 +759,72 @@ class UnitTest(IUnitTest):
         error_buffer: io.StringIO
     ) -> unittest.TestResult:
         """
-        Executes all test cases in the test suite concurrently using a thread pool,
-        aggregating their results into a single result object. Standard output and error
-        streams are redirected to the provided buffers during execution.
-
-        This method is designed to speed up test execution by running multiple test cases
-        in parallel threads, making use of the configured maximum number of workers. Each
-        test case is executed in isolation, and their results are merged into a combined
-        result object. If the `fail_fast` option is enabled and a test fails, remaining
-        tests are canceled as soon as possible.
+        Executes all test cases in the test suite concurrently using a thread pool and aggregates their results.
 
         Parameters
         ----------
         output_buffer : io.StringIO
-            Buffer to capture standard output produced during test execution.
+            Buffer to capture the standard output generated during test execution.
         error_buffer : io.StringIO
-            Buffer to capture standard error produced during test execution.
+            Buffer to capture the standard error generated during test execution.
 
         Returns
         -------
         unittest.TestResult
-            A combined result object (instance of the custom result class) containing
-            the aggregated outcomes of all executed tests, including detailed information
-            about passed, failed, errored, and skipped tests.
+            Combined result object containing the outcomes of all executed test cases.
 
         Notes
         -----
-        - Uses a custom result class to collect detailed test outcomes.
-        - If `fail_fast` is enabled and a test fails, remaining tests are canceled.
-        - Output and error streams are captured for the entire parallel execution.
+        Each test case is executed in a separate thread using a ThreadPoolExecutor.
+        Results from all threads are merged into a single result object.
+        Output and error streams are redirected for the entire parallel execution.
+        If fail-fast is enabled, execution stops as soon as a failure is detected.
         """
 
-        # Flatten the test suite to get individual test cases
+        # Resolve and flatten all test cases in the suite, injecting dependencies if needed
         test_cases = list(self.__resolveFlattenedTestSuite())
 
-        # Create a custom result instance to collect all results
+        # Get the custom result class for enhanced test tracking
         result_class = self.__customResultClass()
+
+        # Create a combined result object to aggregate all individual test results
         combined_result = result_class(io.StringIO(), descriptions=True, verbosity=self.__verbosity)
 
-        # Helper function to run a single test and return its result.
-        # Each test runs in its own thread with minimal output.
+        # Define a function to run a single test case and return its result
         def run_single_test(test):
             runner = unittest.TextTestRunner(
-                stream=io.StringIO(),  # Use a dummy stream for individual test output
+                stream=io.StringIO(),  # Use a separate buffer for each test
                 verbosity=0,
                 failfast=False,
                 resultclass=result_class
             )
-            # Run the test and return its result object
             return runner.run(unittest.TestSuite([test]))
 
-        # Redirect stdout and stderr to the provided buffers during parallel execution
+        # Redirect output and error streams for the entire parallel execution
         with redirect_stdout(output_buffer), redirect_stderr(error_buffer):
 
-            # Create a ThreadPoolExecutor to run tests in parallel
+            # Create a thread pool with the configured number of workers
             with ThreadPoolExecutor(max_workers=self.__max_workers) as executor:
 
-                # Submit all test cases to the executor
+                # Submit all test cases to the thread pool for execution
                 futures = [executor.submit(run_single_test, test) for test in test_cases]
 
-                # Process the results as they complete
+                # As each test completes, merge its result into the combined result
                 for future in as_completed(futures):
                     test_result = future.result()
-                    # Merge each individual test result into the combined result
                     self.__mergeTestResults(combined_result, test_result)
 
-                    # If fail_fast is enabled and a test failed, cancel remaining futures
+                    # If fail-fast is enabled and a failure occurs, cancel remaining tests
                     if self.__fail_fast and not combined_result.wasSuccessful():
                         for f in futures:
                             f.cancel()
                         break
 
-        # Print a concise summary for each test in the combined result
+        # Print the result of each individual test using the printer
         for test_result in combined_result.test_results:
             self.__printer.unittestResult(test_result)
 
-        # Return the combined result object containing all test outcomes
+        # Return the aggregated result containing all test outcomes
         return combined_result
 
     def __mergeTestResults(
@@ -939,42 +835,45 @@ class UnitTest(IUnitTest):
         """
         Merge the results of two unittest.TestResult objects into a single result.
 
-        This method updates the `combined_result` object by aggregating the test run counts,
-        failures, errors, skipped tests, expected failures, and unexpected successes from the
-        `individual_result` object. It also merges any custom test results stored in the
-        `test_results` attribute, if present, ensuring that all detailed test outcomes are
-        included in the combined result.
-
         Parameters
         ----------
         combined_result : unittest.TestResult
-            The TestResult object that will be updated to include the results from `individual_result`.
+            The TestResult object that will be updated with the merged results.
         individual_result : unittest.TestResult
-            The TestResult object whose results will be merged into `combined_result`.
+            The TestResult object whose results will be merged into the combined_result.
 
         Returns
         -------
         None
-            This method does not return a value. It modifies `combined_result` in place.
+            This method does not return a value. It updates combined_result in place.
 
         Notes
         -----
-        - The method aggregates all relevant test outcome lists and counters.
-        - If the `test_results` attribute exists (for custom result classes), it is also merged.
-        - This is useful for combining results from parallel or sequential test executions.
+        This method aggregates the test statistics and detailed results from individual_result into combined_result.
+        It updates the total number of tests run, and extends the lists of failures, errors, skipped tests,
+        expected failures, and unexpected successes. If the result objects contain a 'test_results' attribute,
+        this method also merges the detailed test result entries.
         """
 
-        # Aggregate the number of tests run
+        # Increment the total number of tests run
         combined_result.testsRun += individual_result.testsRun
 
-        # Extend the lists of failures, errors, skipped, expected failures, and unexpected successes
+        # Extend the list of failures with those from the individual result
         combined_result.failures.extend(individual_result.failures)
+
+        # Extend the list of errors with those from the individual result
         combined_result.errors.extend(individual_result.errors)
+
+        # Extend the list of skipped tests with those from the individual result
         combined_result.skipped.extend(individual_result.skipped)
+
+        # Extend the list of expected failures with those from the individual result
         combined_result.expectedFailures.extend(individual_result.expectedFailures)
+
+        # Extend the list of unexpected successes with those from the individual result
         combined_result.unexpectedSuccesses.extend(individual_result.unexpectedSuccesses)
 
-        # Merge custom test results if present (for enhanced result tracking)
+        # If the individual result contains detailed test results, merge them as well
         if hasattr(individual_result, 'test_results'):
             if not hasattr(combined_result, 'test_results'):
                 combined_result.test_results = []
@@ -984,46 +883,45 @@ class UnitTest(IUnitTest):
         self
     ) -> type:
         """
-        Creates a custom test result class for enhanced test tracking.
-        This method dynamically generates an `OrionisTestResult` class that extends
-        `unittest.TextTestResult`. The custom class provides advanced functionality for
-        tracking test execution details, including timings, statuses, and error information.
+        Create and return a custom test result class for enhanced test tracking.
 
         Returns
         -------
         type
-            A dynamically created class `OrionisTestResult` that overrides methods to handle
-            test results, including success, failure, error, and skipped tests. The class
-            collects detailed information about each test, such as execution time, error
-            messages, traceback, and file path.
+            A dynamically created subclass of unittest.TextTestResult that collects
+            detailed information about each test execution, including timing, status,
+            error messages, tracebacks, and metadata.
 
         Notes
         -----
-        The `OrionisTestResult` class includes the following method overrides:
-        The method uses the `this` reference to access the outer class's methods, such as
-        `_extractErrorInfo`, for extracting and formatting error information.
+        The returned class, OrionisTestResult, extends unittest.TextTestResult and
+        overrides key methods to capture additional data for each test case. This
+        includes execution time, error details, and test metadata, which are stored
+        in a list of TestResult objects for later reporting and analysis.
         """
-
-        # Use `this` to refer to the outer class instance
         this = self
 
-        # Define the custom test result class
         class OrionisTestResult(unittest.TextTestResult):
+
+            # Initialize the parent class and custom attributes for tracking results and timings
             def __init__(self, *args, **kwargs):
                 super().__init__(*args, **kwargs)
-                self.test_results = []
-                self._test_timings = {}
-                self._current_test_start = None
+                self.test_results = []              # Stores detailed results for each test
+                self._test_timings = {}             # Maps test instances to their execution time
+                self._current_test_start = None     # Tracks the start time of the current test
 
+            # Record the start time of the test
             def startTest(self, test):
                 self._current_test_start = time.time()
                 super().startTest(test)
 
+            # Calculate and store the elapsed time for the test
             def stopTest(self, test):
                 elapsed = time.time() - self._current_test_start
                 self._test_timings[test] = elapsed
                 super().stopTest(test)
 
+            # Handle a successful test case and record its result
             def addSuccess(self, test):
                 super().addSuccess(test)
                 elapsed = self._test_timings.get(test, 0.0)
@@ -1041,6 +939,7 @@ class UnitTest(IUnitTest):
                     )
                 )
 
+            # Handle a failed test case, extract error info, and record its result
             def addFailure(self, test, err):
                 super().addFailure(test, err)
                 elapsed = self._test_timings.get(test, 0.0)
@@ -1062,6 +961,7 @@ class UnitTest(IUnitTest):
                     )
                 )
 
+            # Handle a test case that raised an error, extract error info, and record its result
             def addError(self, test, err):
                 super().addError(test, err)
                 elapsed = self._test_timings.get(test, 0.0)
@@ -1083,6 +983,7 @@ class UnitTest(IUnitTest):
                     )
                 )
 
+            # Handle a skipped test case and record its result
             def addSkip(self, test, reason):
                 super().addSkip(test, reason)
                 elapsed = self._test_timings.get(test, 0.0)
@@ -1111,11 +1012,6 @@ class UnitTest(IUnitTest):
         """
         Extracts the file path and a cleaned traceback from a given traceback string.
 
-        This method analyzes a Python traceback string to determine the file path of the Python file
-        where the error occurred (typically the last file in the traceback). It also removes lines
-        related to framework internals and irrelevant noise, such as those containing 'unittest/', 
-        'lib/python', or 'site-packages', to produce a more concise and relevant traceback for reporting.
-
         Parameters
         ----------
         traceback_str : str
@@ -1123,21 +1019,23 @@ class UnitTest(IUnitTest):
 
         Returns
         -------
-        Tuple[Optional[str], Optional[str]]
-            A tuple containing:
-                - file_path (Optional[str]): The path to the Python file where the error occurred, or None if not found.
-                - clean_tb (Optional[str]): The cleaned traceback string, with framework internals and unrelated lines removed.
+        tuple
+            file_path : str or None
+                The path to the Python file where the error occurred, or None if not found.
+            clean_tb : str or None
+                The cleaned traceback string with framework internals removed, or the original traceback if no cleaning was possible.
 
         Notes
         -----
-        The cleaned traceback starts from the first occurrence of the test file path and omits lines
-        that are part of the Python standard library or third-party packages, focusing on user code.
+        This method parses the traceback string to identify the most relevant file path (typically the last Python file in the traceback).
+        It then filters out lines related to framework internals (such as 'unittest/', 'lib/python', or 'site-packages') to produce a more concise and relevant traceback.
+        The cleaned traceback starts from the first occurrence of the relevant file path.
         """
 
-        # Extract all Python file paths from the traceback string
+        # Find all Python file paths in the traceback
         file_matches = re.findall(r'File ["\'](.*?.py)["\']', traceback_str)
 
-        # Use the last file in the traceback as the most relevant (where the error occurred)
+        # Select the last file path as the most relevant one
         file_path = file_matches[-1] if file_matches else None
 
         # Split the traceback into individual lines for processing
@@ -1145,25 +1043,21 @@ class UnitTest(IUnitTest):
         clean_lines = []
         relevant_lines_started = False
 
-        # Iterate through each line in the traceback
+        # Iterate through each line to filter out framework internals
         for line in tb_lines:
 
-            # Skip lines that are part of framework internals or third-party libraries
+            # Skip lines that are part of unittest, Python standard library, or site-packages
             if any(s in line for s in ['unittest/', 'lib/python', 'site-packages']):
                 continue
 
-            # Start including lines once the relevant file path is found
+            # Start collecting lines from the first occurrence of the relevant file path
             if file_path and file_path in line and not relevant_lines_started:
                 relevant_lines_started = True
-
-            # If we've started collecting relevant lines, add them to the cleaned traceback
             if relevant_lines_started:
                 clean_lines.append(line)
 
-        # Join the cleaned lines into a single string; if none, return the original traceback
+        # Join the filtered lines to form the cleaned traceback
         clean_tb = str('\n').join(clean_lines) if clean_lines else traceback_str
-
-        # Return the file path and cleaned traceback
         return file_path, clean_tb
 
     def __generateSummary(
@@ -1172,51 +1066,31 @@ class UnitTest(IUnitTest):
         execution_time: float
     ) -> Dict[str, Any]:
         """
-        Generates a comprehensive summary of the test suite execution.
-
-        This method processes the provided unittest.TestResult object and aggregates
-        statistics such as the total number of tests, counts of passed, failed, errored,
-        and skipped tests, as well as the overall execution time and success rate.
-        It also collects detailed information for each individual test, including
-        identifiers, class and method names, status, execution time, error messages,
-        tracebacks, file paths, and docstrings.
-
-        If result persistence is enabled, the summary is saved using the configured
-        persistence driver (e.g., SQLite or JSON). If web reporting is enabled, a
-        web report is generated and linked.
+        Generates a summary dictionary of the test suite execution, including statistics,
+        timing, and detailed results for each test. Optionally persists the summary and/or
+        generates a web report if configured.
 
         Parameters
         ----------
         result : unittest.TestResult
             The result object containing details of the test execution.
         execution_time : float
-            The total execution time of the test suite in milliseconds.
+            The total execution time of the test suite in seconds.
 
         Returns
         -------
-        Dict[str, Any]
-            A dictionary containing:
-                - total_tests (int): Total number of tests executed.
-                - passed (int): Number of tests that passed.
-                - failed (int): Number of tests that failed.
-                - errors (int): Number of tests that encountered errors.
-                - skipped (int): Number of tests that were skipped.
-                - total_time (float): Total execution time in milliseconds.
-                - success_rate (float): Percentage of tests that passed.
-                - test_details (List[Dict[str, Any]]): List of dictionaries with details for each test,
-                  including id, class, method, status, execution_time, error_message, traceback,
-                  file_path, and doc_string.
-                - timestamp (str): ISO-formatted timestamp of when the summary was generated.
-
-        Side Effects
-        ------------
-        - If persistence is enabled, the summary is persisted to storage.
+        dict
+            A dictionary containing test statistics, details, and metadata.
+
+        Notes
+        -----
+        - If persistence is enabled, the summary is saved to storage.
         - If web reporting is enabled, a web report is generated.
+        - The summary includes per-test details, overall statistics, and a timestamp.
         """
 
-        test_details = []
-
         # Collect detailed information for each test result
+        test_details = []
         for test_result in result.test_results:
             rst: TestResult = test_result
             test_details.append({
@@ -1233,10 +1107,11 @@ class UnitTest(IUnitTest):
 
         # Calculate the number of passed tests
         passed = result.testsRun - len(result.failures) - len(result.errors) - len(result.skipped)
+
         # Calculate the success rate as a percentage
         success_rate = (passed / result.testsRun * 100) if result.testsRun > 0 else 100.0
 
-        # Build the summary dictionary
+        # Build the summary dictionary with all relevant statistics and details
         self.__result = {
             "total_tests": result.testsRun,
             "passed": passed,
@@ -1267,38 +1142,33 @@ class UnitTest(IUnitTest):
         """
         Generate a web-based report for the provided test results summary.
 
-        This method creates a web report for the test execution summary using the `TestingResultRender` class.
-        It determines the appropriate storage path for the report, configures persistence options based on the
-        current settings, and invokes the rendering process. After generating the report, it prints a link to
-        the web report using the configured printer.
-
         Parameters
         ----------
         summary : dict
-            The summary of test results for which the web report will be generated.
+            Summary of test results for web report generation.
 
         Returns
         -------
         None
-            This method does not return any value. The generated web report is rendered and a link to it is printed
-            to the console via the printer.
 
         Notes
         -----
-        - The storage path for the report is determined by `self.__base_path`.
-        - If result persistence is enabled and the driver is set to 'sqlite', the report is marked as persistent.
-        - The web report is generated using the `TestingResultRender` class.
-        - The method prints the link to the generated web report using the printer.
+        This method creates a web-based report for the given test results summary.
+        It uses the TestingResultRender class to generate the report, passing the storage path,
+        the summary result, and a flag indicating whether to persist the report based on the
+        persistence configuration and driver. After rendering, it prints a link to the generated
+        web report using the printer.
         """
 
-        # Create the TestingResultRender instance with the storage path and summary.
+        # Create a TestingResultRender instance with the storage path, result summary,
+        # and persistence flag (True if persistent and using sqlite driver)
         render = TestingResultRender(
             storage_path=self.__storage,
             result=summary,
             persist=self.__persistent and self.__persistent_driver == 'sqlite'
         )
 
-        # Render the web report and print the link using the printer.
+        # Print the link to the generated web report
         self.__printer.linkWebReport(render.render())
 
     def __handlePersistResults(
@@ -1308,71 +1178,51 @@ class UnitTest(IUnitTest):
         """
         Persist the test results summary using the configured persistence driver.
 
-        This method saves the provided test results summary to persistent storage, based on the
-        current configuration. Supported drivers include SQLite (using the TestLogs class) and
-        JSON file output. The storage location is determined by the configured base path.
-
         Parameters
         ----------
         summary : dict
-            The summary of test results to persist. This should include all relevant test execution
-            details, such as test counts, statuses, execution times, and individual test results.
-
-        Returns
-        -------
-        None
-            This method does not return any value. It performs persistence as a side effect.
+            The summary dictionary containing test results and metadata to be persisted.
 
         Raises
         ------
         OSError
-            If there is an error creating directories or writing files to disk.
+            If there is an error creating directories or writing files.
         OrionisTestPersistenceError
             If database operations fail or any other error occurs during persistence.
 
         Notes
         -----
-        - If `self.__persistent_driver` is set to 'sqlite', the summary is stored in an SQLite database
-          using the TestLogs class.
-        - If `self.__persistent_driver` is set to 'json', the summary is written to a timestamped JSON
-          file in the specified base path.
-        - The method ensures that the target directory exists before writing files.
-        - Any errors encountered during persistence are raised as exceptions for the caller to handle.
+        This method persists the test results summary according to the configured persistence driver.
+        If the driver is set to 'sqlite', the summary is stored in a SQLite database using the TestLogs class.
+        If the driver is set to 'json', the summary is saved as a JSON file in the specified storage directory,
+        with a filename based on the current timestamp. The method ensures that the target directory exists,
+        and handles any errors that may occur during file or database operations.
         """
-
         try:
 
+            # If the persistence driver is SQLite, store the summary in the database
             if self.__persistent_driver == PersistentDrivers.SQLITE.value:
-
-                # Persist results to SQLite database using TestLogs
                 history = TestLogs(self.__storage)
-
-                # Insert the summary into the database
                 history.create(summary)
 
+            # If the persistence driver is JSON, write the summary to a JSON file
             elif self.__persistent_driver == PersistentDrivers.JSON.value:
-
-                # Generate a timestamp for the log file name
                 timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
-
-                # Construct the log file path with the timestamp
                 log_path = Path(self.__storage) / f"{timestamp}_test_results.json"
 
-                # Ensure the directory exists
+                # Ensure the parent directory exists
                 log_path.parent.mkdir(parents=True, exist_ok=True)
 
-                # Write the summary dictionary to the JSON file
+                # Write the summary to the JSON file
                 with open(log_path, 'w', encoding='utf-8') as log:
                     json.dump(summary, log, indent=4)
-
         except OSError as e:
 
-            # Raise an OSError if there is an issue with file or directory operations
+            # Raise an error if directory creation or file writing fails
             raise OSError(f"Error creating directories or writing files: {str(e)}")
-
         except Exception as e:
 
-            # Raise a custom exception for any other issues during persistence
+            # Raise a persistence error for any other exceptions
             raise OrionisTestPersistenceError(f"Error persisting test results: {str(e)}")
 
     def __filterTestsByName(
@@ -1381,44 +1231,57 @@ class UnitTest(IUnitTest):
         pattern: str
     ) -> unittest.TestSuite:
         """
-        Filters tests in a given test suite based on a specified name pattern.
+        Filter tests in a test suite by a regular expression pattern applied to test names.
+
         Parameters
         ----------
         suite : unittest.TestSuite
-            The test suite containing the tests to filter.
+            The test suite containing the tests to be filtered.
         pattern : str
-            A regular expression pattern to match test names.
+            Regular expression pattern to match against test names (test IDs).
+
         Returns
         -------
         unittest.TestSuite
-            A new test suite containing only the tests that match the pattern.
+            A new TestSuite containing only the tests whose names match the given pattern.
+
         Raises
         ------
         OrionisTestValueError
             If the provided pattern is not a valid regular expression.
+
         Notes
         -----
+        This method compiles the provided regular expression and applies it to the IDs of all test cases
+        in the flattened suite. Only tests whose IDs match the pattern are included in the returned suite.
+        If the pattern is invalid, an OrionisTestValueError is raised with details about the regex error.
         """
 
-        # Initialize an empty TestSuite to hold the filtered tests
+        # Create a new TestSuite to hold the filtered tests
         filtered_suite = unittest.TestSuite()
 
-        # Validate the pattern
         try:
+
+            # Compile the provided regular expression pattern
             regex = re.compile(pattern)
+
         except re.error as e:
+
+            # Raise a value error if the regex is invalid
             raise OrionisTestValueError(
                 f"The provided test name pattern is invalid: '{pattern}'. "
                 f"Regular expression compilation error: {str(e)}. "
                 "Please check the pattern syntax and try again."
             )
 
-        # Iterate through all tests in the suite and filter by the regex pattern
+        # Iterate through all test cases in the flattened suite
         for test in self.__flattenTestSuite(suite):
+
+            # Add the test to the filtered suite if its ID matches the regex
             if regex.search(test.id()):
                 filtered_suite.addTest(test)
 
-        # Return the filtered suite containing only tests that match the pattern
+        # Return the suite containing only the filtered tests
         return filtered_suite
 
     def __filterTestsByTags(
@@ -1427,47 +1290,56 @@ class UnitTest(IUnitTest):
         tags: List[str]
     ) -> unittest.TestSuite:
         """
-        Filter tests in a unittest TestSuite by specified tags.
-
-        Iterates through all tests in the provided TestSuite and checks for a `__tags__`
-        attribute either on the test method or the test case class. If any of the specified
-        tags match the tags associated with the test, the test is included in the filtered suite.
+        Filters tests in a unittest TestSuite by matching specified tags.
 
         Parameters
         ----------
         suite : unittest.TestSuite
-            The original TestSuite containing all tests.
+            The original TestSuite containing all test cases to be filtered.
         tags : list of str
             List of tags to filter the tests by.
 
         Returns
         -------
         unittest.TestSuite
-            A new TestSuite containing only the tests that match the specified tags.
+            A new TestSuite containing only the tests that have at least one matching tag.
+
+        Notes
+        -----
+        This method inspects each test case in the provided suite and checks for the presence of tags
+        either on the test method (via a `__tags__` attribute) or on the test class instance itself.
+        If any of the specified tags are found in the test's tags, the test is included in the returned suite.
         """
 
-        # Initialize an empty TestSuite to hold the filtered tests
+        # Create a new TestSuite to hold the filtered tests
         filtered_suite = unittest.TestSuite()
+
+        # Convert the list of tags to a set for efficient intersection checks
         tag_set = set(tags)
 
+        # Iterate through all test cases in the flattened suite
         for test in self.__flattenTestSuite(suite):
 
-            # Get test method if this is a TestCase instance
+            # Attempt to retrieve the test method from the test case
             test_method = getattr(test, test._testMethodName, None)
 
-            # Check for tags attribute on the test method
+            # Check if the test method has a __tags__ attribute
             if hasattr(test_method, '__tags__'):
                 method_tags = set(getattr(test_method, '__tags__'))
+
+                # If there is any intersection between the method's tags and the filter tags, add the test
                 if tag_set.intersection(method_tags):
                     filtered_suite.addTest(test)
 
-            # Also check on the test case class
+            # If the method does not have tags, check if the test case itself has a __tags__ attribute
             elif hasattr(test, '__tags__'):
                 class_tags = set(getattr(test, '__tags__'))
+
+                # If there is any intersection between the class's tags and the filter tags, add the test
                 if tag_set.intersection(class_tags):
                     filtered_suite.addTest(test)
 
-        # Return the filtered suite containing only tests with matching tags
+        # Return the suite containing only the filtered tests
         return filtered_suite
 
     def getTestNames(
@@ -1478,8 +1350,8 @@ class UnitTest(IUnitTest):
 
         Returns
         -------
-        List[str]
-            List of test names (unique identifiers) from the test suite.
+        list of str
+            List of test names from the test suite.
         """
         return [test.id() for test in self.__flattenTestSuite(self.__suite)]
 
@@ -1487,12 +1359,12 @@ class UnitTest(IUnitTest):
         self
     ) -> int:
         """
-        Returns the total number of test cases in the test suite.
+        Get the total number of test cases in the test suite.
 
         Returns
         -------
         int
-            The total number of individual test cases in the suite.
+            Total number of individual test cases in the suite.
         """
         return len(list(self.__flattenTestSuite(self.__suite)))
 
@@ -1502,7 +1374,9 @@ class UnitTest(IUnitTest):
         """
         Clear all tests from the current test suite.
 
-        Resets the internal test suite to an empty `unittest.TestSuite`, removing any previously added tests.
+        Returns
+        -------
+        None
         """
         self.__suite = unittest.TestSuite()
 
@@ -1510,12 +1384,12 @@ class UnitTest(IUnitTest):
         self
     ) -> dict:
         """
-        Returns the results of the executed test suite.
+        Get the results of the executed test suite.
 
         Returns
         -------
-        UnitTest
-            The result of the executed test suite.
+        dict
+            Result of the executed test suite.
         """
         return self.__result
 
@@ -1523,12 +1397,12 @@ class UnitTest(IUnitTest):
         self
     ) -> int:
         """
-        Returns the output buffer used for capturing test results.
-        This method returns the internal output buffer that collects the results of the test execution.
+        Get the output buffer used for capturing test results.
+
         Returns
         -------
         int
-            The output buffer containing the results of the test execution.
+            Output buffer containing the results of the test execution.
         """
         return self.__output_buffer
 
@@ -1536,8 +1410,11 @@ class UnitTest(IUnitTest):
         self
     ) -> None:
         """
-        Prints the contents of the output buffer to the console.
-        This method retrieves the output buffer and prints its contents using the rich console.
+        Print the contents of the output buffer to the console.
+
+        Returns
+        -------
+        None
         """
         self.__printer.print(self.__output_buffer)
 
@@ -1545,12 +1422,12 @@ class UnitTest(IUnitTest):
         self
     ) -> int:
         """
-        Returns the error buffer used for capturing test errors.
-        This method returns the internal error buffer that collects any errors encountered during test execution.
+        Get the error buffer used for capturing test errors.
+
         Returns
         -------
         int
-            The error buffer containing the errors encountered during the test execution.
+            Error buffer containing errors encountered during test execution.
         """
         return self.__error_buffer
 
@@ -1558,7 +1435,10 @@ class UnitTest(IUnitTest):
         self
     ) -> None:
         """
-        Prints the contents of the error buffer to the console.
-        This method retrieves the error buffer and prints its contents using the rich console.
+        Print the contents of the error buffer to the console.
+
+        Returns
+        -------
+        None
         """
         self.__printer.print(self.__error_buffer)