orionis 0.404.0__py3-none-any.whl → 0.406.0__py3-none-any.whl

orionis/test/kernel.py

@@ -1,347 +1,145 @@
-import gc
-import os
+from pathlib import Path
 import re
+from typing import List
 from os import walk
-import sys
-from orionis.foundation.config.testing.entities.testing import Testing as Configuration
+from orionis.foundation.config.testing.entities.testing import Testing
 from orionis.foundation.contracts.application import IApplication
 from orionis.test.contracts.kernel import ITestKernel
-from orionis.test.arguments.parser import TestArgumentParser
-from orionis.test.core.unit_test import UnitTest
-from orionis.test.entities.arguments import TestArguments
-from orionis.test.enums.execution_mode import ExecutionMode
+from orionis.test.contracts.unit_test import IUnitTest
 from orionis.test.exceptions import OrionisTestConfigException
 
 class TestKernel(ITestKernel):
-    """
-    Core test kernel for the Orionis testing framework.
-
-    This class provides the main interface for discovering, configuring, and executing
-    test suites within the Orionis framework. It handles test configuration validation,
-    test discovery across multiple directories, and orchestrates the execution of
-    discovered tests.
-
-    Parameters
-    ----------
-    app : IApplication
-        The Orionis application instance that provides the testing context.
-
-    Attributes
-    ----------
-    __app : IApplication
-        Private reference to the application instance.
-    __config : Configuration
-        Private reference to the testing configuration.
-    """
 
     def __init__(
         self,
         app: IApplication
     ) -> None:
         """
-        Initialize the Orionis test kernel.
+        Initialize the TestKernel with the provided application instance.
 
         Parameters
         ----------
         app : IApplication
-            The application instance that implements the IApplication interface.
-            This provides the context and services needed for test execution.
+            The application instance implementing the IApplication contract.
 
         Raises
         ------
-        ValueError
-            If the provided app is None or not an instance of IApplication.
+        OrionisTestConfigException
+            If the provided app is not an instance of IApplication.
         """
-        # Validate application instance
-        if app is None or not isinstance(app, IApplication):
-            raise ValueError("The provided application is not a valid instance of IApplication.")
 
-        # Set the application instance
-        self.__app = app
+        # Validate that the app is an instance of IApplication
+        if not isinstance(app, IApplication):
+            raise OrionisTestConfigException(
+                f"Failed to initialize TestKernel: expected IApplication, got {type(app).__module__}.{type(app).__name__}."
+            )
+
+        # Load testing configuration from the application
+        self.__config = Testing(**app.config('testing'))
 
-    def __checkConfiguration(
+        # Create and configure the unit test instance
+        self.__unit_test: IUnitTest = app.make('core.orionis.testing')
+        self.__unit_test._UnitTest__app = app
+        self.__unit_test._UnitTest__storage = app.path('storage_testing')
+
+    def __listMatchingFolders(
         self,
-        config: Configuration = None,
-        **kwargs
-    ) -> Configuration:
+        base_path: Path,
+        custom_path: Path,
+        pattern: str
+    ) -> List[str]:
         """
-        Validate and initialize the testing configuration.
-
-        This method validates the provided configuration or creates a new one from
-        keyword arguments. It ensures that the configuration is properly set up
-        before test execution begins.
+        List folders within a custom path whose files match a given pattern.
 
         Parameters
         ----------
-        config : Configuration, optional
-            A pre-configured Testing configuration instance. If None, attempts to
-            create one from kwargs.
-        **kwargs : dict
-            Keyword arguments to create a Configuration instance if config is None.
-            Must match the Configuration class constructor parameters.
+        base_path : Path
+            The base directory path for relative calculation.
+        custom_path : Path
+            The custom directory path to search for matching files.
+        pattern : str
+            The filename pattern to match (supports '*' and '?').
 
         Returns
         -------
-        bool
-            True if configuration validation succeeds.
-
-        Raises
-        ------
-        OrionisTestConfigException
-            If the configuration is invalid or required fields are missing.
-            The exception message includes details about required fields and their types.
+        List[str]
+            List of relative folder paths containing files matching the pattern.
         """
-        # Check if config is None and kwargs are provided
-        if config is None:
 
-            # Try to create a Configuration instance with provided kwargs or default values
-            try:
-                # If no kwargs are provided, create a default Configuration instance
-                if not kwargs:
-                    config = Configuration(**self.__app.config('testing'))
+        # Compile the pattern into a regex for matching file names
+        regex = re.compile('^' + pattern.replace('*', '.*').replace('?', '.') + '$')
+        matched_folders = set()
 
-                # If kwargs are provided, create a Configuration instance with them
-                else:
-                    config = Configuration(**kwargs)
+        # Walk through the directory tree starting at custom_path
+        for root, _, files in walk(str(custom_path)):
 
-            except TypeError:
+            # Check if any file in the current folder matches the pattern
+            if any(regex.fullmatch(file) for file in files):
 
-                # If a TypeError occurs, it indicates that the provided arguments do not match the Configuration class
-                required_fields = []
-                for field in Configuration().getFields():
-                    required_fields.append(f"{field.get('name')} = (Type: {field.get('type')}, Default: {field.get('default')})")
+                # Calculate the relative path from base_path and add to results
+                rel_path = Path(root).relative_to(base_path).as_posix()
+                matched_folders.add(rel_path)
 
-                # Raise an exception with a detailed message about the required fields
-                raise OrionisTestConfigException(f"The provided configuration is not valid. Please ensure it is an instance of the Configuration class or provide valid keyword arguments. \n{str('\n').join(required_fields)}]")
+        # Return the list of matching folder paths
+        return list(matched_folders)
 
-        # Assign the configuration to the instance variable
-        return config or Configuration()
-
-    def handle(
-        self,
-        config: Configuration = None,
-        **kwargs
-    ) -> UnitTest:
+    def handle(self) -> IUnitTest:
         """
-        Execute the complete test discovery and execution pipeline.
-
-        This is the main entry point for running tests. It validates the configuration,
-        discovers test files based on specified patterns and paths, configures the
-        test suite, and executes all discovered tests.
-
-        Parameters
-        ----------
-        config : Configuration, optional
-            A pre-configured Testing configuration instance. If None, attempts to
-            create one from kwargs.
-        **kwargs : dict
-            Keyword arguments to create a Configuration instance if config is None.
-            Common parameters include:
-            - base_path : str, base directory for test discovery
-            - folder_path : str or list, specific folders to search
-            - pattern : str, file pattern for test discovery
-            - verbosity : int, output verbosity level
-            - execution_mode : str, test execution mode
-            - max_workers : int, maximum number of worker threads
-            - fail_fast : bool, stop on first failure
+        Configure and execute the unit tests based on the current configuration.
 
         Returns
         -------
-        UnitTest
-            The configured and executed test suite instance containing all results.
-
-        Raises
-        ------
-        OrionisTestConfigException
-            If the configuration validation fails.
+        IUnitTest
+            The configured and executed unit test instance.
         """
-        # Validate and set configuration
-        config = self.__checkConfiguration(config, **kwargs)
-
-        # Initialize the test suite
-        tests = UnitTest()
-
-        # Assign the application instance to the test suite
-        tests.setApplication(self.__app)
 
-        # Configure the test suite with validated configuration values
-        tests.configure(
-            verbosity=config.verbosity,
-            execution_mode=config.execution_mode,
-            max_workers=config.max_workers,
-            fail_fast=config.fail_fast,
-            print_result=config.print_result,
-            throw_exception=config.throw_exception,
-            persistent=config.persistent,
-            persistent_driver=config.persistent_driver,
-            web_report=config.web_report
+        # Configure the unit test with parameters from the configuration
+        self.__unit_test.configure(
+            verbosity=self.__config.verbosity,
+            execution_mode=self.__config.execution_mode,
+            max_workers=self.__config.max_workers,
+            fail_fast=self.__config.fail_fast,
+            print_result=self.__config.print_result,
+            throw_exception=self.__config.throw_exception,
+            persistent=self.__config.persistent,
+            persistent_driver=self.__config.persistent_driver,
+            web_report=self.__config.web_report
         )
 
-        # Extract configuration values for test discovery
-        base_path = config.base_path
-        folder_path = config.folder_path
-        pattern = config.pattern
+        # Prepare paths and pattern for test discovery
+        base_path = (Path.cwd() / self.__config.base_path).resolve()
+        folder_path = self.__config.folder_path
+        pattern = self.__config.pattern
 
-        def list_matching_folders(custom_path: str, pattern: str):
-            """
-            Discover folders containing files that match the specified pattern.
+        # Set to hold discovered folders
+        discovered_folders = set()
 
-            This helper function walks through the directory tree starting from
-            custom_path and identifies folders that contain files matching the
-            given pattern.
+        # Discover folders containing test files according to the configuration
 
-            Parameters
-            ----------
-            custom_path : str
-                The root path to start the search from.
-            pattern : str
-                The file pattern to match (supports wildcards * and ?).
-
-            Returns
-            -------
-            list of str
-                List of relative folder paths containing matching files.
-            """
-            matched_folders = []
-            for root, _, files in walk(custom_path):
-                for file in files:
-                    if re.fullmatch(pattern.replace('*', '.*').replace('?', '.'), file):
-                        relative_path = root.replace(base_path, '').replace('\\', '/').lstrip('/')
-                        if relative_path not in matched_folders:
-                            matched_folders.append(relative_path)
-            return matched_folders
-
-        # Discover test folders based on configuration
-        discovered_folders = []
+        # Search all folders under base_path
         if folder_path == '*':
-            # Search all folders under base_path
-            discovered_folders.extend(list_matching_folders(base_path, pattern))
+            discovered_folders.update(self.__listMatchingFolders(base_path, base_path, pattern))
+
+        # Search each custom folder in the list
         elif isinstance(folder_path, list):
-            # Search specific folders provided in the list
-            for custom_path in folder_path:
-                discovered_folders.extend(list_matching_folders(f"{base_path}/{custom_path}", pattern))
+            for custom in folder_path:
+                custom_path = (base_path / custom).resolve()
+                discovered_folders.update(self.__listMatchingFolders(base_path, custom_path, pattern))
+
+        # Search a single custom folder
         else:
-            # Search single specified folder
-            discovered_folders.extend(list_matching_folders(folder_path, pattern))
+            custom_path = (base_path / folder_path).resolve()
+            discovered_folders.update(self.__listMatchingFolders(base_path, custom_path, pattern))
 
-        # Add discovered folders to the test suite for execution
+        # Register discovered folders with the unit test for test discovery
         for folder in discovered_folders:
-            tests.discoverTestsInFolder(
+            self.__unit_test.discoverTestsInFolder(
                 folder_path=folder,
-                base_path=base_path,
+                base_path=self.__config.base_path,
                 pattern=pattern,
-                test_name_pattern=config.test_name_pattern if config.test_name_pattern else None,
-                tags=config.tags if config.tags else None
+                test_name_pattern=self.__config.test_name_pattern or None,
+                tags=self.__config.tags or None
             )
 
-        # Execute the test suite and return the results
-        tests.run()
-
-        # Return the test suite instance containing all results
-        return tests
-
-    def handleCLI(
-        self,
-        sys_argv: list[str],
-    ) -> UnitTest:
-
-        """
-        Process command line arguments for test execution.
-        This method configures and runs tests based on command line arguments. It extracts
-        configuration from the provided TestArguments object, executes the tests, and
-        handles output generation.
-        Parameters
-        ----------
-        args : TestArguments
-            Command line arguments parsed into a TestArguments object.
-        base_path : str, optional
-            Base directory to search for test files, by default 'tests'.
-        folder_path : str, optional
-            Pattern for folder selection within base_path, by default '*'.
-        pattern : str, optional
-            Filename pattern for test files, by default 'test_*.py'.
-        Returns
-        -------
-        UnitTest
-            The test suite instance containing all test results.
-        Notes
-        -----
-        The method supports various test execution options including parallel/sequential
-        execution mode, fail fast behavior, and result output configuration.
-        """
-
-        # Validate the provided arguments
-        if not isinstance(sys_argv, list):
-            raise OrionisTestConfigException("The provided sys_argv must be a list of command line arguments.")
-
-        # Assign the provided arguments to a TestArguments instance
-        parser = TestArgumentParser()
-        args:TestArguments = parser.parse(sys_argv)
-
-        # Extract and validate the configuration from command line arguments
-        test = self.handle(
-            verbosity = int(args.verbosity),
-            execution_mode = ExecutionMode.PARALLEL if args.mode == 'parallel' else ExecutionMode.SEQUENTIAL,
-            fail_fast = bool(args.fail_fast),
-            print_result = bool(args.print_result),
-            throw_exception = bool(args.throw_exception),
-            persistent = bool(args.persistent),
-            persistent_driver = str(args.persistent_driver) if args.persistent_driver else None,
-            web_report = bool(args.web_report)
-        )
-
-        # If requested, print the output buffer
-        if args.print_output_buffer:
-            test.printOutputBuffer()
-
-        # Return the test suite instance containing all results
-        return test
-
-    def exit(
-        self,
-        code: int = 0
-    ) -> None:
-        """
-        Terminate the test execution process and free associated resources.
-
-        This method performs a clean shutdown of the test kernel by explicitly
-        triggering garbage collection to release memory resources and then
-        terminating the process with the provided exit code. It ensures that any
-        remaining file handles, threads, or other resources are properly released.
-
-        Parameters
-        ----------
-        code : int
-            The exit code to return to the operating system. Should be 0 for
-            successful execution or a non-zero value to indicate an error.
-
-        Returns
-        -------
-        None
-            This method does not return as it terminates the process.
-
-        Raises
-        ------
-        ValueError
-            If the provided code is not a valid integer or outside the allowed range.
-
-        Notes
-        -----
-        Using os._exit() bypasses normal Python cleanup mechanisms and
-        immediately terminates the process. This can be necessary when
-        normal sys.exit() would be caught by exception handlers.
-        """
-        # Validate the exit code
-        if not isinstance(code, int):
-            raise ValueError("Exit code must be an integer")
-
-        # Check if the code is within the allowed range (typically 0-255)
-        if code < 0 or code > 255:
-            raise ValueError("Exit code must be between 0 and 255")
-
-        # Force garbage collection to free memory
-        gc.collect()
-
-        # Terminate the process immediately without running cleanup handlers
-        sys.exit(code)
-        os._exit(code)
+        # Run the unit tests and return the result
+        return self.__unit_test.run()

orionis/test/output/dumper.py

@@ -1,6 +1,7 @@
 import os
 import sys
-from orionis.test.exceptions.runtime import OrionisTestRuntimeError
+from orionis.console.dumper.dump import Debug
+from orionis.test.exceptions import OrionisTestRuntimeError
 from orionis.test.contracts.dumper import ITestDumper
 
 class TestDumper(ITestDumper):
@@ -29,102 +30,165 @@ class TestDumper(ITestDumper):
 
     def __isTestCaseClass(self, value) -> bool:
         """
-        Check if the given value is an instance of a test case class.
+        Determines whether the provided value is an instance of a recognized test case class.
+
+        This method checks if the given object is an instance of either AsyncTestCase or SyncTestCase,
+        which are the supported test case base classes in the Orionis testing framework.
 
         Parameters
         ----------
         value : object
-            The object to check.
+            The object to check for test case class membership.
 
         Returns
         -------
         bool
-            True if `value` is an instance of AsyncTestCase, TestCase, or SyncTestCase;
-            False otherwise.
+            Returns True if `value` is an instance of AsyncTestCase or SyncTestCase.
+            Returns False if `value` is None, not an instance of these classes, or if any import error occurs.
         """
+
+        # If the value is None, it cannot be a test case instance.
+        if value is None:
+            return False
+
         try:
-            if value is None:
-                return False
+
+            # Attempt to import the test case base classes.
             from orionis.test.cases.asynchronous import AsyncTestCase
             from orionis.test.cases.synchronous import SyncTestCase
-            return isinstance(value, (AsyncTestCase, SyncTestCase))
+            import unittest
+
+            # Check if the value is an instance of either Orionis or native unittest test case class.
+            return isinstance(
+                value,
+                (
+                    AsyncTestCase,
+                    SyncTestCase,
+                    unittest.TestCase,
+                ),
+            )
+
         except Exception:
+
+            # If imports fail or any other exception occurs, return False.
             return False
 
     def dd(self, *args) -> None:
         """
-        Dumps debugging information using the Debug class.
+        Outputs debugging information using the Debug class and halts further execution.
 
-        This method captures the caller's file and line number,
-        and uses the Debug class to output debugging information.
+        This method captures the caller's file and line number to provide context for the debug output.
+        It temporarily redirects standard output and error streams to ensure the debug information is
+        displayed correctly. If the first argument is a recognized test case instance, it is skipped
+        in the output to avoid redundant information. The method raises an exception if any error
+        occurs during the dumping process.
 
         Parameters
         ----------
         *args : tuple
-            Variable length argument list to be dumped.
+            Variable length argument list containing the objects to be dumped.
+
+        Returns
+        -------
+        None
+            This method does not return any value. It outputs debug information and may halt execution.
         """
+
+        # If no arguments are provided, exit the method early.
         if not args:
             return
 
+        # Save the original stdout and stderr to restore them later
         original_stdout = sys.stdout
         original_stderr = sys.stderr
 
         try:
-            from orionis._console.dumper.dump_die import Debug
 
+            # Redirect stdout and stderr to the system defaults for proper debug output
             sys.stdout = sys.__stdout__
             sys.stderr = sys.__stderr__
 
+            # Retrieve the caller's frame to get file and line number context
             caller_frame = sys._getframe(1)
             _file = os.path.abspath(caller_frame.f_code.co_filename)
             _line = caller_frame.f_lineno
 
+            # Initialize the Debug dumper with context information
             dumper = Debug(f"{_file}:{_line}")
+
+            # If the first argument is a test case instance, skip it in the output
             if self.__isTestCaseClass(args[0]):
                 dumper.dd(*args[1:])
             else:
                 dumper.dd(*args)
+
         except Exception as e:
+
+            # Raise a custom runtime error if dumping fails
             raise OrionisTestRuntimeError(f"An error occurred while dumping debug information: {e}")
+
         finally:
+
+            # Restore the original stdout and stderr
             sys.stdout = original_stdout
             sys.stderr = original_stderr
 
     def dump(self, *args) -> None:
         """
-        Dumps debugging information using the Debug class.
+        Outputs debugging information using the Debug class.
 
-        This method captures the caller's file, method, and line number,
-        and uses the Debug class to output debugging information.
+        This method captures the caller's file and line number to provide context for the debug output.
+        It temporarily redirects standard output and error streams to ensure the debug information is
+        displayed correctly. If the first argument is a recognized test case instance, it is skipped
+        in the output to avoid redundant information. The method raises an exception if any error
+        occurs during the dumping process.
 
         Parameters
         ----------
         *args : tuple
-            Variable length argument list to be dumped.
+            Variable length argument list containing the objects to be dumped.
+
+        Returns
+        -------
+        None
+            This method does not return any value. It outputs debug information.
         """
+
+        # If no arguments are provided, exit the method early.
         if not args:
             return
 
+        # Save the original stdout and stderr to restore them later
         original_stdout = sys.stdout
         original_stderr = sys.stderr
 
         try:
-            from orionis._console.dumper.dump_die import Debug
 
+            # Redirect stdout and stderr to the system defaults for proper debug output
             sys.stdout = sys.__stdout__
             sys.stderr = sys.__stderr__
 
+            # Retrieve the caller's frame to get file and line number context
             caller_frame = sys._getframe(1)
             _file = os.path.abspath(caller_frame.f_code.co_filename)
             _line = caller_frame.f_lineno
 
+            # Initialize the Debug dumper with context information
             dumper = Debug(f"{_file}:{_line}")
+
+            # If the first argument is a test case instance, skip it in the output
             if self.__isTestCaseClass(args[0]):
                 dumper.dump(*args[1:])
             else:
                 dumper.dump(*args)
+
         except Exception as e:
+
+            # Raise a custom runtime error if dumping fails
             raise OrionisTestRuntimeError(f"An error occurred while dumping debug information: {e}")
+
         finally:
+
+            # Restore the original stdout and stderr
             sys.stdout = original_stdout
             sys.stderr = original_stderr