orionis 0.432.0__py3-none-any.whl → 0.434.0__py3-none-any.whl

orionis/test/cases/synchronous.py

@@ -3,52 +3,28 @@ from orionis.test.output.dumper import TestDumper
 
 class SyncTestCase(unittest.TestCase, TestDumper):
     """
-    Base test case class for synchronous unit testing.
+    Base class for synchronous unit tests in the Orionis framework.
 
-    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.
+    Inherits from `unittest.TestCase` and `TestDumper`, providing
+    hooks for custom setup and teardown logic via `onSetup()` and
+    `onTeardown()` methods. Subclasses should override these hooks
+    to implement test-specific initialization and cleanup.
 
     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.
     """
 
     def setUp(self):
         """
-        Initialize the test environment before each test method.
+        Set up 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
+        Calls the superclass `setUp()` and then invokes the
+        `onSetup()` hook for additional initialization.
 
         Returns
         -------
         None
-
-        Notes
-        -----
-        This method should not be overridden directly. Use onSetup() instead
-        for custom setup logic.
         """
         super().setUp()
         self.onSetup()
@@ -57,70 +33,38 @@ class SyncTestCase(unittest.TestCase, TestDumper):
         """
         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
+        Invokes the `onTeardown()` hook for custom cleanup and
+        then calls the superclass `tearDown()`.
 
         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.
+        Hook 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
+        Intended to be overridden by subclasses to perform
+        custom initialization before each test.
 
         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.
+        Hook 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
+        Intended to be overridden by subclasses to perform
+        custom cleanup after each test.
 
         Returns
         -------
         None
-
-        Examples
-        --------
-        >>> def onTeardown(self):
-        ...     self.mock_service.cleanup()
-        ...     del self.test_data
         """
-        pass
+        pass

orionis/test/contracts/dumper.py

@@ -2,51 +2,47 @@ from abc import ABC, abstractmethod
 
 class ITestDumper(ABC):
     """
-    Interface for standard output debugging utilities.
+    Abstract base class for debugging output utilities.
 
-    This interface defines methods for dumping debugging information,
-    capturing the caller's file, method, and line number, and utilizing
-    a Debug class to output the information.
-
-    Implementations
-    --------------
-    Implementations should provide mechanisms to output or log the
-    provided arguments for debugging purposes.
+    This interface specifies methods for outputting debugging information,
+    capturing the caller's file, method, and line number, and utilizing a
+    Debug class to display or log the information.
     """
 
     @abstractmethod
     def dd(self, *args) -> None:
         """
-        Outputs debugging information using the Debug class.
+        Output debugging information using the Debug class.
 
-        This method captures the caller's file and line number, then
-        utilizes the Debug class to display or log the provided arguments
-        for debugging purposes.
+        Captures the caller's file and line number, then uses the Debug class
+        to display or log the provided arguments for debugging purposes.
 
         Parameters
         ----------
         *args : tuple
-            Variable length argument list containing the data to be dumped.
+            Variable length argument list containing the data to be output.
 
         Returns
         -------
         None
-            This method does not return any value. Its purpose is to output
-            or log the debugging information.
         """
         pass
 
     @abstractmethod
     def dump(self, *args) -> None:
         """
-        Dumps debugging information using the Debug class.
+        Output 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.
+        Captures the caller's file, method, and line number, and uses the
+        Debug class to output the provided arguments for debugging purposes.
 
         Parameters
         ----------
         *args : tuple
-            Variable length argument list to be dumped.
+            Variable length argument list containing the data to be output.
+
+        Returns
+        -------
+        None
         """
-        pass
+        pass

orionis/test/contracts/kernel.py

@@ -3,27 +3,20 @@ from orionis.test.contracts.unit_test import IUnitTest
 
 class ITestKernel(ABC):
     """
-    Abstract interface for test kernel implementations.
+    Interface for test kernel implementations in the Orionis testing framework.
 
-    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
+    The test kernel manages the application context, validates and handles test configuration,
+    orchestrates test discovery and execution, and provides a unified interface for test operations.
     """
 
     @abstractmethod
     def handle(self) -> IUnitTest:
         """
-        Configure and execute the unit tests based on the current configuration.
+        Configure and execute unit tests according to the current configuration.
 
         Returns
         -------
         IUnitTest
-            The configured and executed unit test instance.
+            An instance representing the configured and executed unit test.
         """
         pass

orionis/test/contracts/logs.py

@@ -3,7 +3,7 @@ from typing import Dict, List, Optional, Tuple
 
 class ITestLogs(ABC):
     """
-    Interface for test logs persistence using a relational database.
+    Abstract interface for persisting and retrieving test logs in a relational database.
     """
 
     @abstractmethod
@@ -13,22 +13,16 @@ class ITestLogs(ABC):
 
         Parameters
         ----------
-        report : Dict
-            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)
+        report : dict
+            Dictionary containing the test report data. Required keys:
+            'json' (str), '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 stored successfully.
+            True if the report was stored successfully, otherwise False.
 
         Raises
         ------
@@ -42,12 +36,12 @@ class ITestLogs(ABC):
     @abstractmethod
     def reset(self) -> bool:
         """
-        Drop the reports table, removing all test history.
+        Remove all test reports from the database.
 
         Returns
         -------
         bool
-            True if the table was dropped or did not exist.
+            True if the reports table was dropped or did not exist.
 
         Raises
         ------
@@ -67,15 +61,16 @@ class ITestLogs(ABC):
 
         Parameters
         ----------
-        first : Optional[int]
-            Number of earliest reports (ascending by id).
-        last : Optional[int]
-            Number of latest reports (descending by id).
+        first : int, optional
+            Number of earliest reports to retrieve, ordered by ascending ID.
+        last : int, optional
+            Number of latest reports to retrieve, ordered by descending ID.
 
         Returns
         -------
-        List[Tuple]
-            Each tuple: (id, json, total_tests, passed, failed, errors, skipped, total_time, success_rate, timestamp)
+        list of tuple
+            Each tuple contains:
+            (id, json, total_tests, passed, failed, errors, skipped, total_time, success_rate, timestamp).
 
         Raises
         ------

orionis/test/contracts/printer.py

@@ -9,7 +9,14 @@ class ITestPrinter(ABC):
         self,
         value: Any
     ) -> None:
-        """Prints a value to the console using the rich console."""
+        """
+        Print a value to the console using the rich console.
+
+        Parameters
+        ----------
+        value : Any
+            The value to be printed to the console.
+        """
         pass
 
     @abstractmethod
@@ -20,7 +27,18 @@ class ITestPrinter(ABC):
         execution_mode: str,
         max_workers: int
     ):
-        """Displays a formatted start message for the test execution session."""
+        """
+        Display a formatted start message for the test execution session.
+
+        Parameters
+        ----------
+        length_tests : int
+            The total number of tests to be executed.
+        execution_mode : str
+            The mode in which the tests will be executed.
+        max_workers : int
+            The maximum number of worker threads or processes.
+        """
         pass
 
     @abstractmethod
@@ -29,7 +47,14 @@ class ITestPrinter(ABC):
         *,
         summary: Dict[str, Any]
     ) -> None:
-        """Display a summary message for the test suite execution."""
+        """
+        Display a summary message for the test suite execution.
+
+        Parameters
+        ----------
+        summary : dict of str to Any
+            A dictionary containing summary information about the test execution.
+        """
         pass
 
     @abstractmethod
@@ -39,7 +64,16 @@ class ITestPrinter(ABC):
         flatten_test_suite: list,
         callable: callable
     ):
-        """Executes a test suite panel with optional live console output."""
+        """
+        Execute a test suite panel with optional live console output.
+
+        Parameters
+        ----------
+        flatten_test_suite : list
+            A flattened list representing the test suite to be executed.
+        callable : callable
+            A callable object to execute each test.
+        """
         pass
 
     @abstractmethod
@@ -47,7 +81,14 @@ class ITestPrinter(ABC):
         self,
         path: str
     ):
-        """Prints an invitation to view the test results, with an underlined path."""
+        """
+        Print an invitation to view the test results, with an underlined path.
+
+        Parameters
+        ----------
+        path : str
+            The file system or web path to the test results report.
+        """
         pass
 
     @abstractmethod
@@ -55,7 +96,14 @@ class ITestPrinter(ABC):
         self,
         summary: Dict[str, Any]
     ) -> None:
-        """Prints a summary table of test results using the Rich library."""
+        """
+        Print a summary table of test results using the Rich library.
+
+        Parameters
+        ----------
+        summary : dict of str to Any
+            A dictionary containing summary statistics of the test results.
+        """
         pass
 
     @abstractmethod
@@ -64,7 +112,14 @@ class ITestPrinter(ABC):
         *,
         summary: Dict[str, Any]
     ) -> None:
-        """Display the results of the test execution, including a summary table and details."""
+        """
+        Display the results of the test execution, including a summary table and details.
+
+        Parameters
+        ----------
+        summary : dict of str to Any
+            A dictionary containing the results and summary of the test execution.
+        """
         pass
 
     @abstractmethod
@@ -72,5 +127,12 @@ class ITestPrinter(ABC):
         self,
         test_result: TestResult
     ) -> None:
-        """Display the result of a single unit test in a formatted manner."""
+        """
+        Display the result of a single unit test in a formatted manner.
+
+        Parameters
+        ----------
+        test_result : TestResult
+            The result object of a single unit test.
+        """
         pass

orionis/test/contracts/render.py

@@ -7,24 +7,18 @@ class ITestingResultRender(ABC):
         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
+        Generates a report file by rendering test results into a template.
 
         Returns
         -------
         str
-            The full path to the generated report file.
+            The absolute 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.
+        - If persistence is enabled, retrieves the last 10 reports from the SQLite database.
+        - If persistence is disabled, uses only the current test result stored in memory.
+        - Reads a template file, replaces placeholders with test results and persistence mode,
+          and writes the rendered content to the report file.
         """
-        pass
+        pass

orionis/test/contracts/test_result.py

@@ -5,23 +5,24 @@ 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.
+    Interface for a custom test result collector that extends unittest's TextTestResult,
+    providing detailed execution metadata for each test case.
 
-    Classes implementing this interface are responsible for capturing detailed
-    information about each test case execution, including success, failure,
-    error, and skip states.
+    This interface defines properties and methods for capturing test outcomes,
+    execution times, error tracebacks, and related metadata for each test case.
     """
 
     @property
     @abstractmethod
     def test_results(self) -> List[TestResult]:
         """
-        A list containing the detailed results of each executed test case.
+        List of detailed results for 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.
+        Returns
+        -------
+        List[TestResult]
+            Each element contains metadata such as status, execution time, method name,
+            module, file, and optional error information.
         """
         pass
 
@@ -29,8 +30,12 @@ class IOrionisTestResult(ABC):
     @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()`.
+        Mapping of test cases to their execution durations in seconds.
+
+        Returns
+        -------
+        Dict[unittest.case.TestCase, float]
+            Keys are test case instances, values are elapsed times in seconds.
         """
         pass
 
@@ -38,63 +43,89 @@ class IOrionisTestResult(ABC):
     @abstractmethod
     def _current_test_start(self) -> Optional[float]:
         """
-        Timestamp (in seconds) marking the beginning of the currently running test.
-        Used internally to calculate duration.
+        Timestamp marking the start of the currently running test.
+
+        Returns
+        -------
+        Optional[float]
+            Start time in seconds, or None if no test is running.
         """
         pass
 
     @abstractmethod
     def startTest(self, test: unittest.case.TestCase) -> None:
         """
-        Called before the test is run.
+        Record the start time for a test case before execution.
 
-        Records the current start time for the test case in `_current_test_start`.
+        Parameters
+        ----------
+        test : unittest.case.TestCase
+            The test case about to be executed.
         """
         pass
 
     @abstractmethod
     def stopTest(self, test: unittest.case.TestCase) -> None:
         """
-        Called after the test has run.
+        Calculate and store the execution time for a test case after execution.
 
-        Calculates and stores the execution time for the test in `_test_timings`.
+        Parameters
+        ----------
+        test : unittest.case.TestCase
+            The test case that has finished execution.
         """
         pass
 
     @abstractmethod
     def addSuccess(self, test: unittest.case.TestCase) -> None:
         """
-        Called when a test case completes successfully.
+        Append a successful test result to the results list.
 
-        Appends a `TestResult` instance with status `PASSED` to `test_results`.
+        Parameters
+        ----------
+        test : unittest.case.TestCase
+            The test case that completed successfully.
         """
         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.
+        Append a failed test result, including traceback and error message.
 
-        Captures and appends a `TestResult` instance with status `FAILED`, along
-        with traceback and error message.
+        Parameters
+        ----------
+        test : unittest.case.TestCase
+            The test case that failed.
+        err : tuple
+            Tuple containing exception type, exception instance, and traceback object.
         """
         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.
+        Append an errored test result, including traceback and error message.
 
-        Captures and appends a `TestResult` instance with status `ERRORED`, along
-        with traceback and error message.
+        Parameters
+        ----------
+        test : unittest.case.TestCase
+            The test case that encountered an error.
+        err : tuple
+            Tuple containing exception type, exception instance, and traceback object.
         """
         pass
 
     @abstractmethod
     def addSkip(self, test: unittest.case.TestCase, reason: str) -> None:
         """
-        Called when a test case is skipped.
+        Append a skipped test result with the provided reason.
 
-        Appends a `TestResult` instance with status `SKIPPED` and reason to `test_results`.
+        Parameters
+        ----------
+        test : unittest.case.TestCase
+            The test case that was skipped.
+        reason : str
+            Reason for skipping the test.
         """
         pass