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

orionis/test/contracts/test_result.py

@@ -0,0 +1,100 @@
+import unittest
+from abc import ABC, abstractmethod
+from typing import List, Dict, Optional, Tuple
+from orionis.test.entities.result import TestResult
+
+class IOrionisTestResult(ABC):
+    """
+    Interface for OrionisTestResult, a custom test result collector that extends
+    unittest's TextTestResult to include rich execution metadata such as
+    execution time, error tracebacks, and reflection-based information.
+
+    Classes implementing this interface are responsible for capturing detailed
+    information about each test case execution, including success, failure,
+    error, and skip states.
+    """
+
+    @property
+    @abstractmethod
+    def test_results(self) -> List[TestResult]:
+        """
+        A list containing the detailed results of each executed test case.
+
+        Each entry is an instance of `TestResult`, storing metadata such as
+        status, execution time, method name, module, file, and optional error info.
+        """
+        pass
+
+    @property
+    @abstractmethod
+    def _test_timings(self) -> Dict[unittest.case.TestCase, float]:
+        """
+        Internal mapping from each test case to its execution duration in seconds.
+        Used to compute elapsed time between `startTest()` and `stopTest()`.
+        """
+        pass
+
+    @property
+    @abstractmethod
+    def _current_test_start(self) -> Optional[float]:
+        """
+        Timestamp (in seconds) marking the beginning of the currently running test.
+        Used internally to calculate duration.
+        """
+        pass
+
+    @abstractmethod
+    def startTest(self, test: unittest.case.TestCase) -> None:
+        """
+        Called before the test is run.
+
+        Records the current start time for the test case in `_current_test_start`.
+        """
+        pass
+
+    @abstractmethod
+    def stopTest(self, test: unittest.case.TestCase) -> None:
+        """
+        Called after the test has run.
+
+        Calculates and stores the execution time for the test in `_test_timings`.
+        """
+        pass
+
+    @abstractmethod
+    def addSuccess(self, test: unittest.case.TestCase) -> None:
+        """
+        Called when a test case completes successfully.
+
+        Appends a `TestResult` instance with status `PASSED` to `test_results`.
+        """
+        pass
+
+    @abstractmethod
+    def addFailure(self, test: unittest.case.TestCase, err: Tuple[BaseException, BaseException, object]) -> None:
+        """
+        Called when a test case fails due to an assertion failure.
+
+        Captures and appends a `TestResult` instance with status `FAILED`, along
+        with traceback and error message.
+        """
+        pass
+
+    @abstractmethod
+    def addError(self, test: unittest.case.TestCase, err: Tuple[BaseException, BaseException, object]) -> None:
+        """
+        Called when a test case encounters an unexpected error or exception.
+
+        Captures and appends a `TestResult` instance with status `ERRORED`, along
+        with traceback and error message.
+        """
+        pass
+
+    @abstractmethod
+    def addSkip(self, test: unittest.case.TestCase, reason: str) -> None:
+        """
+        Called when a test case is skipped.
+
+        Appends a `TestResult` instance with status `SKIPPED` and reason to `test_results`.
+        """
+        pass

orionis/test/contracts/unit_test.py

@@ -1,71 +1,54 @@
 from abc import ABC, abstractmethod
+from pathlib import Path
 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
+from orionis.foundation.config.testing.enums import ExecutionMode
+from orionis.foundation.config.testing.enums.drivers import PersistentDrivers
+from orionis.foundation.config.testing.enums.verbosity import VerbosityMode
 
 class IUnitTest(ABC):
 
     @abstractmethod
     def configure(
-            self,
-            *,
-            verbosity: int = 2,
-            execution_mode: str | ExecutionMode = ExecutionMode.SEQUENTIAL,
-            max_workers: int = Workers().calculate(),
-            fail_fast: bool = False,
-            print_result: bool = True,
-            throw_exception: bool = False,
-            persistent: bool = False,
-            persistent_driver: str = 'sqlite',
-            web_report: bool = False
-        ):
-        """
-        Configures the UnitTest instance with the specified parameters.
-
-        Parameters
-        ----------
-        verbosity : int, optional
-            The verbosity level for test output. If None, the current setting is retained.
-        execution_mode : str or ExecutionMode, optional
-            The mode in which the tests will be executed ('SEQUENTIAL' or 'PARALLEL'). If None, the current setting is retained.
-        max_workers : int, optional
-            The maximum number of workers to use for parallel execution. If None, the current setting is retained.
-        fail_fast : bool, optional
-            Whether to stop execution upon the first failure. If None, the current setting is retained.
-        print_result : bool, optional
-            Whether to print the test results after execution. If None, the current setting is retained.
-        throw_exception : bool, optional
-            Whether to throw an exception if any test fails. Defaults to False.
-        persistent : bool, optional
-            Whether to persist the test results in a database. Defaults to False.
-        persistent_driver : str, optional
-            The driver to use for persistent storage. Defaults to 'sqlite'.
-
-        Returns
-        -------
-        UnitTest
-            The configured UnitTest instance.
-        """
-        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.
+        *,
+        verbosity: int | VerbosityMode,
+        execution_mode: str | ExecutionMode,
+        max_workers: int,
+        fail_fast: bool,
+        print_result: bool,
+        throw_exception: bool,
+        persistent: bool,
+        persistent_driver: str | PersistentDrivers,
+        web_report: bool
+    ) -> 'IUnitTest':
+        """
+        Configure the unit test runner with the specified options.
 
         Parameters
         ----------
-        app : IApplication
-            The application instance to be set for the UnitTest.
+        verbosity : int or VerbosityMode
+            Level of verbosity for test output.
+        execution_mode : str or ExecutionMode
+            Mode in which tests are executed (e.g., sequential, parallel).
+        max_workers : int
+            Maximum number of worker threads or processes.
+        fail_fast : bool
+            If True, stop execution on first failure.
+        print_result : bool
+            If True, print test results to the console.
+        throw_exception : bool
+            If True, raise exceptions on test failures.
+        persistent : bool
+            If True, enable persistent storage for test results.
+        persistent_driver : str | PersistentDrivers
+            Name of the persistent storage driver.
+        web_report : bool
+            If True, generate a web-based test report.
 
         Returns
         -------
-        UnitTest
+        IUnitTest
+            The configured unit test runner instance.
         """
         pass
 
@@ -73,39 +56,32 @@ class IUnitTest(ABC):
     def discoverTestsInFolder(
         self,
         *,
-        base_path: str = "tests",
+        base_path: str | Path,
         folder_path: str,
-        pattern: str = "test_*.py",
+        pattern: str,
         test_name_pattern: Optional[str] = None,
         tags: Optional[List[str]] = None
-    ):
+    ) -> 'IUnitTest':
         """
+        Discover test cases in a specified folder.
+
         Parameters
         ----------
+        base_path : str or Path
+            Base directory for test discovery.
         folder_path : str
-            The relative path to the folder containing the tests.
-        base_path : str, optional
-            The base directory where the test folder is located. Defaults to "tests".
-        pattern : str, optional
-            The filename pattern to match test files. Defaults to "test_*.py".
-        test_name_pattern : str or None, optional
-            A pattern to filter test names. Defaults to None.
-        tags : list of str or None, optional
-            A list of tags to filter tests. Defaults to None.
+            Relative or absolute path to the folder containing tests.
+        pattern : str
+            File pattern to match test files (e.g., 'test_*.py').
+        test_name_pattern : str, optional
+            Pattern to match test function or class names.
+        tags : list of str, optional
+            List of tags to filter discovered tests.
 
         Returns
         -------
-        UnitTest
-            The current instance of the UnitTest class with the discovered tests added.
-
-        Raises
-        ------
-        OrionisTestValueError
-            If the test folder does not exist, no tests are found, or an error occurs during test discovery.
-
-        Notes
-        -----
-        This method updates the internal test suite with the discovered tests and tracks the number of tests found.
+        IUnitTest
+            The unit test runner instance with discovered tests.
         """
         pass
 
@@ -115,152 +91,113 @@ class IUnitTest(ABC):
         *,
         module_name: str,
         test_name_pattern: Optional[str] = None
-    ):
+    ) -> 'IUnitTest':
         """
-        Discovers and loads tests from a specified module, optionally filtering by a test name pattern, and adds them to the test suite.
+        Discover test cases in a specified module.
 
         Parameters
         ----------
         module_name : str
-            Name of the module from which to discover tests.
+            Name of the module to search for tests.
         test_name_pattern : str, optional
-            Pattern to filter test names. Only tests matching this pattern will be included. Defaults to None.
+            Pattern to match test function or class names.
 
         Returns
         -------
-        UnitTest
-            The current instance of the UnitTest class, allowing method chaining.
-
-        Exceptions
-        ----------
-        OrionisTestValueError
-            If the specified module cannot be imported.
+        IUnitTest
+            The unit test runner instance with discovered tests.
         """
         pass
 
     @abstractmethod
-    def run(
-        self
-    ) -> Dict[str, Any]:
+    def run(self) -> Dict[str, Any]:
         """
-        Executes the test suite and processes the results.
-
-        Parameters
-        ----------
-        print_result : bool, optional
-            If provided, overrides the instance's `print_result` attribute to determine whether to print results.
-        throw_exception : bool, optional
-            If True, raises an exception if any test failures or errors are detected.
+        Execute all discovered tests.
 
         Returns
         -------
         dict
-            A summary of the test execution, including details such as execution time, results, and timestamp.
-
-        Raises
-        ------
-        OrionisTestFailureException
-            If `throw_exception` is True and there are test failures or errors.
+            Dictionary containing the results of the test execution.
         """
         pass
 
     @abstractmethod
-    def getTestNames(
-        self
-    ) -> List[str]:
+    def getTestNames(self) -> List[str]:
         """
-        Get a list of test names (unique identifiers) from the test suite.
+        Get the list of discovered test names.
 
         Returns
         -------
-        List[str]
-            List of test names (unique identifiers) from the test suite.
+        list of str
+            Names of all discovered tests.
         """
         pass
 
     @abstractmethod
-    def getTestCount(
-        self
-    ) -> int:
+    def getTestCount(self) -> int:
         """
-        Returns the total number of test cases in the test suite.
+        Get the total number of discovered tests.
 
         Returns
         -------
         int
-            The total number of individual test cases in the suite.
+            Number of discovered tests.
         """
         pass
 
     @abstractmethod
-    def clearTests(
-        self
-    ) -> None:
+    def clearTests(self) -> None:
         """
-        Clear all tests from the current test suite.
-
-        Resets the internal test suite to an empty `unittest.TestSuite`, removing any previously added tests.
+        Remove all discovered tests from the runner.
         """
         pass
 
     @abstractmethod
-    def getResult(
-        self
-    ) -> dict:
+    def getResult(self) -> dict:
         """
-        Returns the results of the executed test suite.
+        Retrieve the results of the last test run.
 
         Returns
         -------
-        UnitTest
-            The result of the executed test suite.
+        dict
+            Dictionary containing the results of the last test execution.
         """
         pass
 
     @abstractmethod
-    def getOutputBuffer(
-        self
-    ) -> int:
+    def getOutputBuffer(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 size or identifier of the output buffer.
+
         Returns
         -------
         int
-            The output buffer containing the results of the test execution.
+            Output buffer size or identifier.
         """
         pass
 
     @abstractmethod
-    def printOutputBuffer(
-        self
-    ) -> None:
+    def printOutputBuffer(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.
         """
         pass
 
     @abstractmethod
-    def getErrorBuffer(
-        self
-    ) -> int:
+    def getErrorBuffer(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 size or identifier of the error buffer.
+
         Returns
         -------
         int
-            The error buffer containing the errors encountered during the test execution.
+            Error buffer size or identifier.
         """
         pass
 
     @abstractmethod
-    def printErrorBuffer(
-        self
-    ) -> None:
+    def printErrorBuffer(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.
         """
         pass