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

orionis/test/contracts/logs.py

@@ -3,79 +3,56 @@ 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.
+    Interface for test logs persistence using a relational database.
     """
 
     @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.
+        Store a new test report in the database.
 
         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.
+            Must include the following keys:
+            - json (str): JSON-serialized report.
+            - total_tests (int)
+            - passed (int)
+            - failed (int)
+            - errors (int)
+            - skipped (int)
+            - total_time (float)
+            - success_rate (float)
+            - timestamp (str)
 
         Returns
         -------
         bool
-            True if the report was successfully created and stored, False otherwise.
+            True if the report was stored successfully.
 
         Raises
         ------
         OrionisTestValueError
-            If the report structure is invalid or missing required fields.
+            If required fields are missing or invalid.
         OrionisTestPersistenceError
-            If there is an error during the storage operation.
+            If a database error occurs.
         """
         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.
+        Drop the reports table, removing all test history.
 
         Returns
         -------
         bool
-            True if the database was successfully reset, False otherwise.
+            True if the table was dropped or did not exist.
 
         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.
+            If a database error occurs.
         """
         pass
 
@@ -86,40 +63,25 @@ class ITestLogs(ABC):
         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.
+        Retrieve test reports from the database.
 
         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.
+        first : Optional[int]
+            Number of earliest reports (ascending by id).
+        last : Optional[int]
+            Number of latest reports (descending by id).
 
         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).
+            Each tuple: (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.
+            If both 'first' and 'last' are specified, or if either is not a positive integer.
         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.
+            If a database error occurs.
         """
-        pass
+        pass

orionis/test/contracts/printer.py

@@ -1,5 +1,6 @@
 from abc import ABC, abstractmethod
 from typing import Any, Dict
+from orionis.test.entities.result import TestResult
 
 class ITestPrinter(ABC):
 
@@ -8,106 +9,37 @@ class ITestPrinter(ABC):
         self,
         value: Any
     ) -> None:
-        """
-        Prints a value to the console using the rich console.
-        Parameters
-        ----------
-        value : Any
-            The value to be printed. It can be a string, object, or any other type.
-        Notes
-        -----
-        - If the value is a string, it is printed directly.
-        - If the value is an object, its string representation is printed.
-        - If the value is a list, each item is printed on a new line.
-        """
+        """Prints a value to the console using the rich console."""
         pass
 
     @abstractmethod
     def startMessage(
         self,
         *,
-        print_result: bool,
         length_tests: int,
         execution_mode: str,
         max_workers: int
     ):
-        """
-        Displays a formatted start message for the test execution session.
-
-        Parameters
-        ----------
-        print_result : bool
-            Whether to print the start message.
-        length_tests : int
-            The total number of tests to be executed.
-        execution_mode : str
-            The mode of execution, either "parallel" or "sequential".
-        max_workers : int
-            The number of worker threads/processes for parallel execution.
-
-        Side Effects
-        ------------
-        Prints a styled panel with test session information to the console if `print_result` is True.
-        """
+        """Displays a formatted start message for the test execution session."""
         pass
 
     @abstractmethod
     def finishMessage(
         self,
         *,
-        print_result: bool,
         summary: Dict[str, Any]
     ) -> None:
-        """
-        Display a summary message for the test suite execution.
-
-        Parameters
-        ----------
-        summary : dict
-            Dictionary containing the test suite summary, including keys such as
-            'failed', 'errors', and 'total_time'.
-
-        Notes
-        -----
-        - If `self.print_result` is False, the method returns without displaying anything.
-        - Shows a status icon (✅ for success, ❌ for failure) based on the presence of
-          failures or errors in the test suite.
-        - Formats and prints the message within a styled panel using the `rich` library.
-        """
+        """Display a summary message for the test suite execution."""
         pass
 
     @abstractmethod
     def executePanel(
         self,
         *,
-        print_result: bool,
         flatten_test_suite: list,
         callable: callable
     ):
-        """
-        Executes a test suite panel with optional live console output.
-
-        Parameters
-        ----------
-        print_result : bool
-            If True, displays a running message panel while executing the test suite.
-        flatten_test_suite : list
-            The flattened list of test cases or test suite items to be executed.
-        callable : callable
-            The function or method to execute the test suite.
-
-        Returns
-        -------
-        Any
-            The result returned by the provided callable after execution.
-
-        Notes
-        -----
-        This method manages the display of a running message panel using the Rich library,
-        depending on whether debugging is enabled in the test suite and whether results should be printed.
-        If debugging or dump calls are detected in the test code, a live console is used to display
-        real-time updates. Otherwise, a static panel is shown before executing the test suite.
-        """
+        """Executes a test suite panel with optional live console output."""
         pass
 
     @abstractmethod
@@ -115,14 +47,7 @@ class ITestPrinter(ABC):
         self,
         path: str
     ):
-        """
-        Prints an elegant invitation to view the test results, with an underlined path.
-
-        Parameters
-        ----------
-        path : str or Path
-            The path to the test results report.
-        """
+        """Prints an invitation to view the test results, with an underlined path."""
         pass
 
     @abstractmethod
@@ -130,59 +55,22 @@ class ITestPrinter(ABC):
         self,
         summary: Dict[str, Any]
     ) -> None:
-        """
-        Prints a summary table of test results using the Rich library.
-
-        Parameters
-        ----------
-        summary : dict
-            Dictionary with the test summary data. Must contain the following keys:
-            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 had errors.
-            skipped : int
-                Number of tests that were skipped.
-            total_time : float
-                Total duration of the test execution in seconds.
-            success_rate : float
-                Percentage of tests that passed.
-
-        Returns
-        -------
-        None
-        """
+        """Prints a summary table of test results using the Rich library."""
         pass
 
     @abstractmethod
     def displayResults(
         self,
         *,
-        print_result: bool,
         summary: Dict[str, Any]
     ) -> None:
-        """
-        Display the results of the test execution, including a summary table and detailed
-        information about failed or errored tests grouped by their test classes.
-
-        Parameters
-        ----------
-        summary : dict
-            Dictionary containing the summary of the test execution, including test details,
-            statuses, and execution times.
+        """Display the results of the test execution, including a summary table and details."""
+        pass
 
-        Notes
-        -----
-        - Prints a summary table of the test results.
-        - Groups failed and errored tests by their test class and displays them in a structured
-          format using panels.
-        - For each failed or errored test, displays the traceback in a syntax-highlighted panel
-          with additional metadata such as the test method name and execution time.
-        - Uses different icons and border colors to distinguish between failed and errored tests.
-        - Calls a finishing message method after displaying all results.
-        """
-        pass
+    @abstractmethod
+    def unittestResult(
+        self,
+        test_result: TestResult
+    ) -> None:
+        """Display the result of a single unit test in a formatted manner."""
+        pass

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