orionis 0.283.0__py3-none-any.whl → 0.285.0__py3-none-any.whl

orionis/test/output/dumper.py

@@ -1,27 +1,46 @@
 import os
 import sys
+from orionis.test.exceptions.test_runtime_error import OrionisTestRuntimeError
 from orionis.test.output.contracts.dumper import ITestDumper
 
 class TestDumper(ITestDumper):
     """
     TestDumper provides utility methods for debugging and outputting information during test execution.
-    This class implements methods to determine if an object is a test case instance and to output debugging
-    information using the Debug class. It ensures that standard output and error streams are properly managed
-    during debugging dumps, and captures the caller's file and line number for context.
+
+    This class implements methods to:
+        - Determine if an object is a test case instance.
+        - Output debugging information using the Debug class.
+        - Manage standard output and error streams during debugging dumps.
+        - Capture the caller's file and line number for context.
+
+    Attributes
+    ----------
+    None
+
+    Methods
+    -------
+    __isTestCaseClass(value)
+        Determines if the given value is an instance of a test case class.
+    dd(*args)
+        Dumps debugging information using the Debug class.
+    dump(*args)
+        Dumps debugging information using the Debug class.
     """
 
-    def __isTestCaseClass(self, value):
+    def __isTestCaseClass(self, value) -> bool:
         """
-        Determines if the given value is an instance of a test case class.
-        This method checks whether the provided value is an instance of one of the
-        predefined test case classes: AsyncTestCase, TestCase, or SyncTestCase.
-        If the value is None or an ImportError occurs during the import of the
-        test case classes, the method returns False.
-        Args:
-            value: The object to be checked.
-        Returns:
-            bool: True if the value is an instance of AsyncTestCase, TestCase,
-            or SyncTestCase; False otherwise.
+        Check if the given value is an instance of a test case class.
+
+        Parameters
+        ----------
+        value : object
+            The object to check.
+
+        Returns
+        -------
+        bool
+            True if `value` is an instance of AsyncTestCase, TestCase, or SyncTestCase;
+            False otherwise.
         """
         try:
             if value is None:
@@ -33,13 +52,17 @@ class TestDumper(ITestDumper):
         except Exception:
             return False
 
-    def dd(self, *args):
+    def dd(self, *args) -> None:
         """
         Dumps debugging information using the Debug class.
-        This method captures the caller's file, method, and line number,
+
+        This method captures the caller's file and line number,
         and uses the Debug class to output debugging information.
-        Args:
-            *args: Variable length argument list to be dumped.
+
+        Parameters
+        ----------
+        *args : tuple
+            Variable length argument list to be dumped.
         """
         if not args:
             return
@@ -62,17 +85,23 @@ class TestDumper(ITestDumper):
                 dumper.dd(*args[1:])
             else:
                 dumper.dd(*args)
+        except Exception as e:
+            raise OrionisTestRuntimeError(f"An error occurred while dumping debug information: {e}")
         finally:
             sys.stdout = original_stdout
             sys.stderr = original_stderr
 
-    def dump(self, *args):
+    def dump(self, *args) -> None:
         """
         Dumps 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.
-        Args:
-            *args: Variable length argument list to be dumped.
+
+        Parameters
+        ----------
+        *args : tuple
+            Variable length argument list to be dumped.
         """
         if not args:
             return
@@ -95,6 +124,8 @@ class TestDumper(ITestDumper):
                 dumper.dump(*args[1:])
             else:
                 dumper.dump(*args)
+        except Exception as e:
+            raise OrionisTestRuntimeError(f"An error occurred while dumping debug information: {e}")
         finally:
             sys.stdout = original_stdout
             sys.stderr = original_stderr

orionis/test/suites/contracts/test_suite.py

@@ -1,23 +1,37 @@
 from abc import ABC, abstractmethod
-from orionis.foundation.config.testing.entities.testing import Testing as Configuration
 from orionis.test.suites.test_unit import UnitTest
 
 class ITestSuite(ABC):
-    """
-    Interface for configuring and running a UnitTest suite using a provided Configuration.
-    Methods:
-        run(config: Configuration = None) -> UnitTest
-    """
 
     @abstractmethod
-    def run(self, config: Configuration = None) -> UnitTest:
+    def run(self) -> UnitTest:
         """
         Runs the test suite based on the provided configuration.
-        Args:
-            config (Configuration, optional): An optional Configuration object for the test suite.
-        Returns:
-            UnitTest: The result of the executed test suite.
-        Raises:
-            OrionisTestConfigException: If the config parameter is not an instance of Configuration.
+
+        Initializes a UnitTest suite, configures it with parameters from the Configuration object,
+        discovers test folders matching the specified pattern, adds the discovered tests to the suite,
+        executes the test suite, and returns the results.
+
+        Returns
+        -------
+        UnitTest
+            The result of the executed test suite.
+
+        Raises
+        ------
+        OrionisTestConfigException
+            If the provided configuration is not an instance of Configuration.
         """
         pass
+
+    @abstractmethod
+    def getResult(self) -> UnitTest:
+        """
+        Returns the results of the executed test suite.
+
+        Returns
+        -------
+        UnitTest
+            The result of the executed test suite.
+        """
+        pass

orionis/test/suites/contracts/test_unit.py

@@ -3,32 +3,45 @@ from typing import Any, Dict, List, Optional
 from orionis.test.enums.test_mode import ExecutionMode
 
 class IUnitTest(ABC):
-    """
-    IUnitTest is an abstract base class that defines the contract for a unit testing interface within the Orionis framework.
-    This interface provides methods for configuring the test runner, discovering tests in folders or modules, executing tests, retrieving test information, and managing the test suite. Implementations of this interface are expected to provide mechanisms for flexible test discovery, execution, and result handling, supporting features such as verbosity control, parallel execution, test filtering, and result reporting.
-    """
 
     @abstractmethod
     def configure(
             self,
             verbosity: int = None,
-            execution_mode: ExecutionMode = None,
+            execution_mode: str | ExecutionMode = None,
             max_workers: int = None,
             fail_fast: bool = None,
-            print_result: bool = None
+            print_result: bool = None,
+            throw_exception: bool = False,
+            persistent: bool = False,
+            persistent_driver: str = 'sqlite'
         ):
         """
         Configures the UnitTest instance with the specified parameters.
 
-        Parameters:
-            verbosity (int, optional): The verbosity level for test output. Defaults to None.
-            execution_mode (ExecutionMode, optional): The mode in which the tests will be executed. Defaults to None.
-            max_workers (int, optional): The maximum number of workers to use for parallel execution. Defaults to None.
-            fail_fast (bool, optional): Whether to stop execution upon the first failure. Defaults to None.
-            print_result (bool, optional): Whether to print the test results after execution. Defaults to None.
+        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.
+        Returns
+        -------
+        UnitTest
+            The configured UnitTest instance.
         """
         pass
 
@@ -42,85 +55,112 @@ class IUnitTest(ABC):
         tags: Optional[List[str]] = None
     ):
         """
-        Discovers and loads unit tests from a specified folder.
-        Args:
-            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 (Optional[str], optional): A pattern to filter test names. Defaults to None.
-            tags (Optional[List[str]], optional): A list of tags to filter tests. Defaults to None.
-        Returns:
-            UnitTest: The current instance of the UnitTest class with the discovered tests added.
-        Raises:
-            ValueError: If the test folder does not exist, no tests are found, or an error occurs during test discovery.
+        Parameters
+        ----------
+        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.
+
+        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.
         """
         pass
 
     @abstractmethod
     def discoverTestsInModule(self, module_name: str, test_name_pattern: Optional[str] = None):
         """
-        Discovers and loads tests from a specified module, optionally filtering them
-        by a test name pattern, and adds them to the test suite.
-        Args:
-            module_name (str): The name of the module to discover tests from.
-            test_name_pattern (Optional[str]): A pattern to filter test names. Only
-                tests matching this pattern will be included. Defaults to None.
-        Returns:
-            UnitTest: The current instance of the UnitTest class, allowing method chaining.
-        Raises:
-            ValueError: If the specified module cannot be imported.
+        Discovers and loads tests from a specified module, optionally filtering by a test name pattern, and adds them to the test suite.
+
+        Parameters
+        ----------
+        module_name : str
+            Name of the module from which to discover tests.
+        test_name_pattern : str, optional
+            Pattern to filter test names. Only tests matching this pattern will be included. Defaults to None.
+
+        Returns
+        -------
+        UnitTest
+            The current instance of the UnitTest class, allowing method chaining.
+
+        Exceptions
+        ----------
+        OrionisTestValueError
+            If the specified module cannot be imported.
         """
         pass
 
     @abstractmethod
-    def run(self, print_result: bool = None, throw_exception: bool = False) -> Dict[str, Any]:
+    def run(self, print_result: bool = None, throw_exception: bool = None) -> Dict[str, Any]:
         """
         Executes the test suite and processes the results.
-        Args:
-            print_result (bool, optional): If provided, overrides the instance's
-                `print_result` attribute to determine whether to print the test results.
-            throw_exception (bool, optional): If True, raises an exception if any
-                test failures or errors are detected.
-        Returns:
-            Dict[str, Any]: A summary of the test execution, including details such as
-            execution time, test results, and a timestamp.
-        Raises:
-            OrionisTestFailureException: If `throw_exception` is True and there are
-            test failures or errors.
+
+        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.
+
+        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.
         """
         pass
 
     @abstractmethod
     def getTestNames(self) -> List[str]:
         """
-        Retrieves a list of test names from the test suite.
+        Get a list of test names (unique identifiers) from the test suite.
 
-        This method flattens the test suite and extracts the unique identifier
-        (`id`) of each test case.
-
-        Returns:
-            List[str]: A list of test names (unique identifiers) from the test suite.
+        Returns
+        -------
+        List[str]
+            List of test names (unique identifiers) from the test suite.
         """
         pass
 
     @abstractmethod
     def getTestCount(self) -> int:
         """
-        Calculate the total number of tests in the test suite.
-
-        This method flattens the test suite structure and counts the total
-        number of individual test cases.
+        Returns the total number of test cases in the test suite.
 
-        Returns:
-            int: The total number of test cases in the test suite.
+        Returns
+        -------
+        int
+            The total number of individual test cases in the suite.
         """
         pass
 
     @abstractmethod
     def clearTests(self) -> None:
         """
-        Clears the current test suite by reinitializing it to an empty `unittest.TestSuite`.
+        Clear all tests from the current test suite.
 
-        This method is used to reset the test suite, removing any previously added tests.
+        Resets the internal test suite to an empty `unittest.TestSuite`, removing any previously added tests.
         """
         pass

orionis/test/suites/test_suite.py

@@ -7,25 +7,36 @@ from orionis.test.suites.test_unit import UnitTest
 
 class TestSuite(ITestSuite):
     """
-    TestSuite is a class responsible for managing and executing a suite of unit tests based on a configurable set of parameters.
-        config (Configuration, optional): An optional Configuration object that specifies parameters for the test suite execution. If not provided, a new Configuration instance is created.
-        _config (Configuration): The configuration object used to control test suite behavior, such as verbosity, execution mode, worker count, and test discovery patterns.
-    Methods:
-        __init__(config: Configuration = None):
-            Initializes the TestSuite with the provided configuration or a default one.
-        run() -> UnitTest:
-            Executes the test suite according to the configuration. Discovers test folders matching the specified pattern, adds discovered tests to the suite, and runs them.
+    TestSuite manages and executes a suite of unit tests based on a configurable set of parameters.
+
+    Parameters
+    ----------
+    config : Configuration, optional
+        Configuration object specifying parameters for test suite execution. If not provided, a new Configuration instance is created.
+
+    Attributes
+    ----------
+    _config : Configuration
+        The configuration object controlling test suite behavior, such as verbosity, execution mode, worker count, and test discovery patterns.
+
+    Methods
+    -------
+    __init__(config=None)
+        Initializes the TestSuite with the provided configuration or a default one.
+    run()
+        Executes the test suite according to the configuration. Discovers test folders matching the specified pattern, adds discovered tests to the suite, and runs them.
+    getResult()
+        Returns the results of the executed test suite.
     """
 
     def __init__(self, config:Configuration = None):
         """
-        Initializes the object with the given configuration.
-
-        Args:
-            config (Configuration, optional): An optional Configuration object to initialize with. Defaults to None.
+        Initializes the TestSuite with the provided configuration.
 
-        Attributes:
-            _config (Configuration): The configuration used by the object. If no configuration is provided, a new Configuration instance is created.
+        Parameters
+        ----------
+        config : Configuration, optional
+            Configuration object specifying parameters for test suite execution. If not provided, a new Configuration instance is created.
         """
         self.__config = config or Configuration()
         self.__result = None
@@ -33,13 +44,20 @@ class TestSuite(ITestSuite):
     def run(self) -> UnitTest:
         """
         Runs the test suite based on the provided configuration.
-        This method initializes a UnitTest suite, configures it with parameters from the Configuration object,
-        discovers test folders matching the specified pattern, and adds the discovered tests to the suite.
-        Finally, it executes the test suite and returns the results.
-        Returns:
-            UnitTest: The result of the executed test suite.
-        Raises:
-            OrionisTestConfigException: If the provided configuration is not an instance of Configuration.
+
+        Initializes a UnitTest suite, configures it with parameters from the Configuration object,
+        discovers test folders matching the specified pattern, adds the discovered tests to the suite,
+        executes the test suite, and returns the results.
+
+        Returns
+        -------
+        UnitTest
+            The result of the executed test suite.
+
+        Raises
+        ------
+        OrionisTestConfigException
+            If the provided configuration is not an instance of Configuration.
         """
 
         # Check if the config is provided
@@ -61,6 +79,7 @@ class TestSuite(ITestSuite):
             print_result=config.print_result,
             throw_exception=config.throw_exception,
             persistent=config.persistent,
+            persistent_driver=config.persistent_driver,
         )
 
         # Extract configuration values
@@ -101,13 +120,15 @@ class TestSuite(ITestSuite):
 
         # Return the initialized test suite
         self.__result = tests.run()
-        return self.__result
+        return self
 
     def getResult(self) -> UnitTest:
         """
         Returns the results of the executed test suite.
 
-        Returns:
-            UnitTest: The result of the executed test suite.
+        Returns
+        -------
+        UnitTest
+            The result of the executed test suite.
         """
         return self.__result