orionis 0.372.0__py3-none-any.whl → 0.374.0__py3-none-any.whl

orionis/test/entities/arguments.py

@@ -0,0 +1,38 @@
+from dataclasses import dataclass
+from typing import Literal, Optional
+
+@dataclass
+class TestArguments:
+    """
+    Parameters for Orionis test execution.
+
+    Parameters
+    ----------
+    verbosity : int, default=2
+        Level of test output verbosity.
+    mode : {'parallel', 'sequential'}, default='parallel'
+        Test execution mode. Whether to run tests in parallel or sequentially.
+    fail_fast : bool, default=False
+        If True, stop execution upon first test failure.
+    print_result : bool, default=True
+        If True, print test results to the console.
+    throw_exception : bool, default=False
+        If True, raise exceptions during test execution.
+    persistent : bool, default=False
+        If True, maintain state between test runs.
+    persistent_driver : str, optional
+        Driver to use for persistent test execution.
+    web_report : bool, default=False
+        If True, generate a web-based test report.
+    print_output_buffer : bool, default=False
+        If True, print the test output buffer.
+    """
+    verbosity: int = 2
+    mode: Literal['parallel', 'sequential'] = 'parallel'
+    fail_fast: bool = False
+    print_result: bool = True
+    throw_exception: bool = False
+    persistent: bool = False
+    persistent_driver: Optional[str] = None
+    web_report: bool = False
+    print_output_buffer: bool = False

orionis/test/kernel.py

@@ -0,0 +1,336 @@
+import gc
+import os
+import re
+from os import walk
+from orionis.foundation.config.testing.entities.testing import Testing as Configuration
+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.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.
+
+        Parameters
+        ----------
+        app : IApplication
+            The application instance that implements the IApplication interface.
+            This provides the context and services needed for test execution.
+
+        Raises
+        ------
+        ValueError
+            If the provided app is None or 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
+
+    def __checkConfiguration(
+        self,
+        config: Configuration = None,
+        **kwargs
+    ) -> Configuration:
+        """
+        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.
+
+        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.
+
+        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.
+        """
+        # Check if config is None and kwargs are provided
+        if config is None:
+            try:
+                # Attempt to create a Configuration instance with provided keyword arguments
+                config = Configuration(**kwargs)
+            except TypeError:
+                # 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')})")
+
+                # 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)}]")
+
+        # Assign the configuration to the instance variable
+        return config or Configuration()
+
+    def handle(
+        self,
+        config: Configuration = None,
+        **kwargs
+    ) -> UnitTest:
+        """
+        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
+
+        Returns
+        -------
+        UnitTest
+            The configured and executed test suite instance containing all results.
+
+        Raises
+        ------
+        OrionisTestConfigException
+            If the configuration validation fails.
+        """
+        # 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
+        )
+
+        # Extract configuration values for test discovery
+        base_path = config.base_path
+        folder_path = config.folder_path
+        pattern = config.pattern
+
+        def list_matching_folders(custom_path: str, pattern: str):
+            """
+            Discover folders containing files that match the specified pattern.
+
+            This helper function walks through the directory tree starting from
+            custom_path and identifies folders that contain files matching the
+            given pattern.
+
+            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 = []
+        if folder_path == '*':
+            # Search all folders under base_path
+            discovered_folders.extend(list_matching_folders(base_path, pattern))
+        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))
+        else:
+            # Search single specified folder
+            discovered_folders.extend(list_matching_folders(folder_path, pattern))
+
+        # Add discovered folders to the test suite for execution
+        for folder in discovered_folders:
+            tests.discoverTestsInFolder(
+                folder_path=folder,
+                base_path=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
+            )
+
+        # 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
+        os._exit(code)

orionis/test/output/dumper.py

@@ -45,10 +45,9 @@ class TestDumper(ITestDumper):
         try:
             if value is None:
                 return False
-            from orionis.test.cases.test_async import AsyncTestCase
-            from orionis.test.cases.test_case import TestCase
-            from orionis.test.cases.test_sync import SyncTestCase
-            return isinstance(value, (AsyncTestCase, TestCase, SyncTestCase))
+            from orionis.test.cases.asynchronous import AsyncTestCase
+            from orionis.test.cases.synchronous import SyncTestCase
+            return isinstance(value, (AsyncTestCase, SyncTestCase))
         except Exception:
             return False
 

orionis/test/output/printer.py

@@ -16,6 +16,28 @@ class TestPrinter(ITestPrinter):
     def __init__(
         self
     ) -> None:
+        """
+        Initialize the test output printer.
+
+        This initializes a Rich Console for output rendering, setting up panel
+        parameters and debug keywords for test result display.
+
+        Parameters
+        ----------
+        None
+
+        Returns
+        -------
+        None
+
+        Notes
+        -----
+        Sets up the following attributes:
+        - __rich_console: Rich Console instance for formatted terminal output
+        - __panel_title: Title string for the output panel
+        - __panel_width: Width of the output panel (75% of console width)
+        - __debbug_keywords: List of keywords for identifying debug calls
+        """
         self.__rich_console = Console()
         self.__panel_title: str = "🧪 Orionis Framework - Component Test Suite"
         self.__panel_width: int = int(self.__rich_console.width * 0.75)

orionis/test/{logs → record}/history.py

@@ -5,9 +5,9 @@ from pathlib import Path
 from typing import Dict, List, Optional, Tuple
 from orionis.services.environment.env import Env
 from orionis.test.exceptions import OrionisTestPersistenceError, OrionisTestValueError
-from orionis.test.contracts.history import ITestHistory
+from orionis.test.contracts.logs import ITestLogs
 
-class TestHistory(ITestHistory):
+class TestLogs(ITestLogs):
 
     def __init__(
         self,
@@ -71,7 +71,9 @@ class TestHistory(ITestHistory):
         # Create a connection to the database, initially set to None
         self._conn: Optional[sqlite3.Connection] = None
 
-    def __connect(self) -> None:
+    def __connect(
+        self
+    ) -> None:
         """
         Establishes a connection to the SQLite database if not already connected.
 
@@ -89,7 +91,9 @@ class TestHistory(ITestHistory):
             except (sqlite3.Error, Exception) as e:
                 raise OrionisTestPersistenceError(f"Database connection error: {e}")
 
-    def __createTableIfNotExists(self) -> bool:
+    def __createTableIfNotExists(
+        self
+    ) -> bool:
         """
         Ensures that the test history table exists in the database.
 
@@ -135,7 +139,10 @@ class TestHistory(ITestHistory):
                 self.__close()
                 self._conn = None
 
-    def __insertReport(self, report: Dict) -> bool:
+    def __insertReport(
+        self,
+        report: Dict
+    ) -> bool:
         """
         Inserts a test report into the history database table.
 
@@ -272,7 +279,9 @@ class TestHistory(ITestHistory):
                 self.__close()
                 self._conn = None
 
-    def __resetDatabase(self) -> bool:
+    def __resetDatabase(
+        self
+    ) -> bool:
         """
         Resets the database by dropping the existing table.
         This method connects to the database, drops the table specified by
@@ -304,7 +313,9 @@ class TestHistory(ITestHistory):
                 self.__close()
                 self._conn = None
 
-    def __close(self) -> None:
+    def __close(
+        self
+    ) -> None:
         """
         Closes the current database connection.
         This method checks if a database connection exists. If so, it closes the connection and sets the connection attribute to None.
@@ -318,7 +329,10 @@ class TestHistory(ITestHistory):
             self._conn.close()
             self._conn = None
 
-    def create(self, report: Dict) -> bool:
+    def create(
+        self,
+        report: Dict
+    ) -> bool:
         """
         Create a new test report in the history database.
 
@@ -335,7 +349,9 @@ class TestHistory(ITestHistory):
         self.__createTableIfNotExists()
         return self.__insertReport(report)
 
-    def reset(self) -> bool:
+    def reset(
+        self
+    ) -> bool:
         """
         Reset the history database by dropping the existing table.