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

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

orionis/test/contracts/unit_test.py

@@ -22,28 +22,28 @@ class IUnitTest(ABC):
         web_report: bool
     ) -> 'IUnitTest':
         """
-        Configure the unit test runner with the specified options.
+        Configure the unit test runner with the provided options.
 
         Parameters
         ----------
         verbosity : int or VerbosityMode
-            Level of verbosity for test output.
+            Verbosity level for test output.
         execution_mode : str or ExecutionMode
-            Mode in which tests are executed (e.g., sequential, parallel).
+            Execution mode for running tests.
         max_workers : int
             Maximum number of worker threads or processes.
         fail_fast : bool
-            If True, stop execution on first failure.
+            Whether to stop on the first test failure.
         print_result : bool
-            If True, print test results to the console.
+            Whether to print test results to the console.
         throw_exception : bool
-            If True, raise exceptions on test failures.
+            Whether to 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.
+            Whether to enable persistent storage for test results.
+        persistent_driver : str or PersistentDrivers
+            Persistent storage driver to use.
         web_report : bool
-            If True, generate a web-based test report.
+            Whether to generate a web-based test report.
 
         Returns
         -------
@@ -63,20 +63,20 @@ class IUnitTest(ABC):
         tags: Optional[List[str]] = None
     ) -> 'IUnitTest':
         """
-        Discover test cases in a specified folder.
+        Discover test cases within a specified folder.
 
         Parameters
         ----------
         base_path : str or Path
             Base directory for test discovery.
         folder_path : str
-            Relative or absolute path to the folder containing tests.
+            Path to the folder containing test files.
         pattern : str
-            File pattern to match test files (e.g., 'test_*.py').
+            File pattern to match test files.
         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.
+            Tags to filter discovered tests.
 
         Returns
         -------
@@ -93,7 +93,7 @@ class IUnitTest(ABC):
         test_name_pattern: Optional[str] = None
     ) -> 'IUnitTest':
         """
-        Discover test cases in a specified module.
+        Discover test cases within a specified module.
 
         Parameters
         ----------
@@ -117,14 +117,14 @@ class IUnitTest(ABC):
         Returns
         -------
         dict
-            Dictionary containing the results of the test execution.
+            Results of the test execution.
         """
         pass
 
     @abstractmethod
     def getTestNames(self) -> List[str]:
         """
-        Get the list of discovered test names.
+        Retrieve the list of discovered test names.
 
         Returns
         -------
@@ -160,7 +160,7 @@ class IUnitTest(ABC):
         Returns
         -------
         dict
-            Dictionary containing the results of the last test execution.
+            Results of the last test execution.
         """
         pass