orionis 0.371.0__py3-none-any.whl → 0.373.0__py3-none-any.whl

orionis/test/cases/asynchronous.py

@@ -0,0 +1,145 @@
+import unittest
+from orionis.test.output.dumper import TestDumper
+
+class AsyncTestCase(unittest.IsolatedAsyncioTestCase, TestDumper):
+    """
+    Base test case class for asynchronous unit testing.
+
+    This class provides a foundation for writing asynchronous unit tests within
+    the Orionis framework. It extends unittest.IsolatedAsyncioTestCase and includes
+    TestDumper functionality for enhanced test output and debugging capabilities.
+
+    The class provides hooks for custom async setup and teardown logic through the
+    onAsyncSetup() and onAsyncTeardown() methods, which can be overridden by subclasses
+    to implement test-specific asynchronous initialization and cleanup procedures.
+
+    Each test method runs in its own isolated asyncio event loop, ensuring proper
+    isolation and preventing side effects between tests.
+
+    Attributes
+    ----------
+    None
+
+    Methods
+    -------
+    asyncSetUp()
+        Initialize test environment before each async test method execution.
+    asyncTearDown()
+        Clean up test environment after each async test method execution.
+    onAsyncSetup()
+        Hook method for subclass-specific async setup logic.
+    onAsyncTeardown()
+        Hook method for subclass-specific async teardown logic.
+
+    Examples
+    --------
+    >>> class MyAsyncTest(AsyncTestCase):
+    ...     async def onAsyncSetup(self):
+    ...         self.client = AsyncHttpClient()
+    ...         await self.client.connect()
+    ...
+    ...     async def testAsyncOperation(self):
+    ...         result = await self.client.get('/api/data')
+    ...         self.assertEqual(result.status, 200)
+    """
+
+    async def asyncSetUp(self):
+        """
+        Initialize the test environment before each async test method.
+
+        This method is automatically called by the unittest framework before
+        each async test method execution. It performs the standard unittest
+        async setup and then calls the onAsyncSetup() hook for custom
+        asynchronous initialization.
+
+        Parameters
+        ----------
+        None
+
+        Returns
+        -------
+        None
+
+        Notes
+        -----
+        This method should not be overridden directly. Use onAsyncSetup() instead
+        for custom async setup logic. The method runs in the isolated event loop
+        created for each test.
+        """
+        await super().asyncSetUp()
+        await self.onAsyncSetup()
+
+    async def asyncTearDown(self):
+        """
+        Clean up the test environment after each async test method.
+
+        This method is automatically called by the unittest framework after
+        each async test method execution. It calls the onAsyncTeardown() hook
+        for custom cleanup and then performs the standard unittest async teardown.
+
+        Parameters
+        ----------
+        None
+
+        Returns
+        -------
+        None
+
+        Notes
+        -----
+        This method should not be overridden directly. Use onAsyncTeardown() instead
+        for custom async teardown logic. The method runs in the same isolated event
+        loop as the test.
+        """
+        await self.onAsyncTeardown()
+        await super().asyncTearDown()
+
+    async def onAsyncSetup(self):
+        """
+        Hook method for subclass-specific async setup logic.
+
+        This method is called during the asyncSetUp() phase and is intended to be
+        overridden by subclasses that need to perform custom asynchronous
+        initialization before each test method execution.
+
+        Parameters
+        ----------
+        None
+
+        Returns
+        -------
+        None
+
+        Examples
+        --------
+        >>> async def onAsyncSetup(self):
+        ...     self.db_connection = await create_async_connection()
+        ...     self.mock_service = AsyncMockService()
+        ...     await self.mock_service.initialize()
+        """
+        pass
+
+    async def onAsyncTeardown(self):
+        """
+        Hook method for subclass-specific async teardown logic.
+
+        This method is called during the asyncTearDown() phase and is intended to be
+        overridden by subclasses that need to perform custom asynchronous cleanup
+        after each test method execution.
+
+        Parameters
+        ----------
+        None
+
+        Returns
+        -------
+        None
+
+        Examples
+        --------
+        >>> async def onAsyncTeardown(self):
+        ...     await self.db_connection.close()
+        ...     await self.mock_service.cleanup()
+        ...     del self.test_data
+        """
+        pass

orionis/test/cases/synchronous.py

@@ -0,0 +1,135 @@
+import unittest
+from orionis.test.output.dumper import TestDumper
+
+class SyncTestCase(unittest.TestCase, TestDumper):
+    """
+    Base test case class for synchronous unit testing.
+
+    This class provides a foundation for writing synchronous unit tests within
+    the Orionis framework. It extends unittest.TestCase and includes TestDumper
+    functionality for enhanced test output and debugging capabilities.
+
+    The class provides hooks for custom setup and teardown logic through the
+    onSetup() and onTeardown() methods, which can be overridden by subclasses
+    to implement test-specific initialization and cleanup procedures.
+
+    Attributes
+    ----------
+    None
+
+    Methods
+    -------
+    setUp()
+        Initialize test environment before each test method execution.
+    tearDown()
+        Clean up test environment after each test method execution.
+    onSetup()
+        Hook method for subclass-specific setup logic.
+    onTeardown()
+        Hook method for subclass-specific teardown logic.
+
+    Examples
+    --------
+    >>> class MyTest(SyncTestCase):
+    ...     def onSetup(self):
+    ...         self.data = [1, 2, 3]
+    ...
+    ...     def testExample(self):
+    ...         self.assertEqual(len(self.data), 3)
+    """
+
+    def setUp(self):
+        """
+        Initialize the test environment before each test method.
+
+        This method is automatically called by the unittest framework before
+        each test method execution. It performs the standard unittest setup
+        and then calls the onSetup() hook for custom initialization.
+
+        Parameters
+        ----------
+        None
+
+        Returns
+        -------
+        None
+
+        Notes
+        -----
+        This method should not be overridden directly. Use onSetup() instead
+        for custom setup logic.
+        """
+        super().setUp()
+        self.onSetup()
+
+    def tearDown(self):
+        """
+        Clean up the test environment after each test method.
+
+        This method is automatically called by the unittest framework after
+        each test method execution. It calls the onTeardown() hook for custom
+        cleanup and then performs the standard unittest teardown.
+
+        Parameters
+        ----------
+        None
+
+        Returns
+        -------
+        None
+
+        Notes
+        -----
+        This method should not be overridden directly. Use onTeardown() instead
+        for custom teardown logic.
+        """
+        self.onTeardown()
+        super().tearDown()
+
+    def onSetup(self):
+        """
+        Hook method for subclass-specific setup logic.
+
+        This method is called during the setUp() phase and is intended to be
+        overridden by subclasses that need to perform custom initialization
+        before each test method execution.
+
+        Parameters
+        ----------
+        None
+
+        Returns
+        -------
+        None
+
+        Examples
+        --------
+        >>> def onSetup(self):
+        ...     self.mock_service = MockService()
+        ...     self.test_data = {"key": "value"}
+        """
+        pass
+
+    def onTeardown(self):
+        """
+        Hook method for subclass-specific teardown logic.
+
+        This method is called during the tearDown() phase and is intended to be
+        overridden by subclasses that need to perform custom cleanup after
+        each test method execution.
+
+        Parameters
+        ----------
+        None
+
+        Returns
+        -------
+        None
+
+        Examples
+        --------
+        >>> def onTeardown(self):
+        ...     self.mock_service.cleanup()
+        ...     del self.test_data
+        """
+        pass

orionis/test/contracts/kernel.py

@@ -0,0 +1,99 @@
+from abc import ABC, abstractmethod
+from typing import Any
+from orionis.foundation.config.testing.entities.testing import Testing as Configuration
+from orionis.test.core.unit_test import UnitTest
+
+class ITestKernel(ABC):
+    """
+    Abstract interface for test kernel implementations.
+
+    This contract defines the required methods that any test kernel implementation
+    must provide for the Orionis testing framework. It ensures consistent behavior
+    across different test kernel implementations.
+
+    The test kernel is responsible for:
+    - Managing application context for testing
+    - Validating and handling test configuration
+    - Orchestrating test discovery and execution
+    - Providing a unified interface for test operations
+    """
+
+    @abstractmethod
+    def handle(
+        self,
+        config: Configuration = None,
+        **kwargs: Any
+    ) -> UnitTest:
+        """
+        Execute the complete test discovery and execution pipeline.
+
+        This is the main entry point for running tests. Implementations must:
+        1. Validate the provided configuration
+        2. Discover test files based on configuration
+        3. Configure and execute the test suite
+        4. Return the test results
+
+        Parameters
+        ----------
+        config : Configuration, optional
+            A pre-configured Testing configuration instance. If None,
+            implementations should create one from kwargs.
+        **kwargs : Any
+            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.
+        """
+        pass
+
+    @abstractmethod
+    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.
+        """
+        pass

orionis/test/contracts/logs.py

@@ -0,0 +1,125 @@
+from abc import ABC, abstractmethod
+from typing import Dict, List, Optional, Tuple
+
+class ITestLogs(ABC):
+    """
+    Abstract base class for test logging and report persistence.
+
+    This interface defines the contract for managing test reports in a persistent
+    storage system. Implementations should provide functionality to create, retrieve,
+    and reset test report data while maintaining proper data validation and error
+    handling.
+
+    The interface supports chronological retrieval of reports and provides methods
+    for database management operations.
+
+    Methods
+    -------
+    create(report)
+        Create and store a new test report in the persistence layer.
+    reset()
+        Reset the storage by clearing all existing test reports.
+    get(first, last)
+        Retrieve test reports with optional chronological filtering.
+    """
+
+    @abstractmethod
+    def create(self, report: Dict) -> bool:
+        """
+        Create a new test report in the history database.
+
+        This method persists a test report containing execution results and
+        metadata to the underlying storage system. The report should include
+        all necessary fields for proper tracking and analysis.
+
+        Parameters
+        ----------
+        report : Dict
+            A dictionary containing the test report data. Must include fields
+            such as total_tests, passed, failed, errors, skipped, total_time,
+            success_rate, and timestamp.
+
+        Returns
+        -------
+        bool
+            True if the report was successfully created and stored, False otherwise.
+
+        Raises
+        ------
+        OrionisTestValueError
+            If the report structure is invalid or missing required fields.
+        OrionisTestPersistenceError
+            If there is an error during the storage operation.
+        """
+        pass
+
+    @abstractmethod
+    def reset(self) -> bool:
+        """
+        Reset the history database by dropping the existing table.
+
+        This method clears all stored test reports and resets the storage
+        system to its initial state. Use with caution as this operation
+        is irreversible and will result in permanent data loss.
+
+        Returns
+        -------
+        bool
+            True if the database was successfully reset, False otherwise.
+
+        Raises
+        ------
+        OrionisTestPersistenceError
+            If there is an error during the reset operation.
+
+        Notes
+        -----
+        This operation is destructive and cannot be undone. Ensure that
+        any important historical data is backed up before calling this method.
+        """
+        pass
+
+    @abstractmethod
+    def get(
+        self,
+        first: Optional[int] = None,
+        last: Optional[int] = None
+    ) -> List[Tuple]:
+        """
+        Retrieve test reports from the history database.
+
+        This method allows for chronological retrieval of test reports with
+        optional filtering. You can retrieve either the earliest or most recent
+        reports, but not both in a single call.
+
+        Parameters
+        ----------
+        first : Optional[int], default=None
+            The number of earliest reports to retrieve, ordered ascending by ID.
+            Must be a positive integer if specified.
+        last : Optional[int], default=None
+            The number of latest reports to retrieve, ordered descending by ID.
+            Must be a positive integer if specified.
+
+        Returns
+        -------
+        List[Tuple]
+            A list of tuples representing the retrieved reports. Each tuple
+            contains the report data in the order: (id, json, total_tests,
+            passed, failed, errors, skipped, total_time, success_rate, timestamp).
+
+        Raises
+        ------
+        OrionisTestValueError
+            If both 'first' and 'last' are specified, or if either parameter
+            is not a positive integer when provided.
+        OrionisTestPersistenceError
+            If there is an error retrieving reports from the storage system.
+
+        Notes
+        -----
+        Only one of 'first' or 'last' parameters can be specified in a single
+        call. The returned results are ordered chronologically based on the
+        selected parameter.
+        """
+        pass

orionis/test/contracts/parser.py

@@ -0,0 +1,37 @@
+from abc import ABC, abstractmethod
+from orionis.test.entities.arguments import TestArguments
+
+class ITestArgumentParser(ABC):
+    """
+    A parser class for handling test command-line arguments.
+
+    This class encapsulates the logic for creating and configuring the argument parser
+    for the Orionis test runner, providing a clean interface for parsing test arguments.
+    """
+
+    @abstractmethod
+    def parse(
+        self,
+        args=None
+    ) -> TestArguments:
+        """
+        Parse command line arguments and return TestArguments object.
+
+        Parameters
+        ----------
+        args : list, optional
+            List of arguments to parse. If None, uses sys.argv.
+
+        Returns
+        -------
+        TestArguments
+            Parsed test arguments object.
+        """
+        pass
+
+    @abstractmethod
+    def help(
+        self
+    ) -> None:
+        """Print help message for the test runner."""
+        pass

orionis/test/contracts/render.py

@@ -0,0 +1,30 @@
+from abc import ABC, abstractmethod
+
+class ITestingResultRender(ABC):
+
+    @abstractmethod
+    def render(
+        self
+    ) -> str:
+        """
+        Otherwise, uses the current test result stored in memory. The method replaces placeholders in a
+        template file with the test results and the persistence mode, then writes the rendered content
+        to a report file.
+
+        Parameters
+        ----------
+        None
+
+        Returns
+        -------
+        str
+            The full path to the generated report file.
+
+        Notes
+        -----
+        - If persistence is enabled, the last 10 reports are fetched from the SQLite database.
+        - If persistence is not enabled, only the current test result in memory is used.
+        - The method reads a template file, replaces placeholders with the test results and persistence mode,
+          and writes the final content to the report file.
+        """
+        pass

orionis/test/contracts/unit_test.py

@@ -1,5 +1,6 @@
 from abc import ABC, abstractmethod
 from typing import Any, Dict, List, Optional
+from orionis.foundation.contracts.application import IApplication
 from orionis.services.system.workers import Workers
 from orionis.test.enums.execution_mode import ExecutionMode
 
@@ -48,6 +49,26 @@ class IUnitTest(ABC):
         """
         pass
 
+    @abstractmethod
+    def setApplication(
+        self,
+        app: 'IApplication'
+    ):
+        """
+        Set the application instance for the UnitTest.
+        This method allows the UnitTest to access the application instance, which is necessary for resolving dependencies and executing tests.
+
+        Parameters
+        ----------
+        app : IApplication
+            The application instance to be set for the UnitTest.
+
+        Returns
+        -------
+        UnitTest
+        """
+        pass
+
     @abstractmethod
     def discoverTestsInFolder(
         self,