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

orionis/test/entities/result.py

@@ -5,29 +5,57 @@ from orionis.test.enums import TestStatus
 @dataclass(frozen=True, kw_only=True)
 class TestResult:
     """
-    Data class representing the outcome of a test execution.
+    Represents the outcome of a test execution.
 
-    This class encapsulates all relevant information about a test's execution,
-    including its unique identifier, name, execution status, timing, and any
-    error details if the test did not pass. It also stores optional metadata
-    such as the class, method, module, file path, and docstring associated
-    with the test, if applicable.
+    Parameters
+    ----------
+    id : Any
+        Unique identifier for the test result.
+    name : str
+        Name of the test.
+    status : TestStatus
+        Status of the test execution (e.g., passed, failed).
+    execution_time : float
+        Time taken to execute the test, in seconds.
+    error_message : Optional[str], optional
+        Error message if the test failed, otherwise None.
+    traceback : Optional[str], optional
+        Traceback information if an error occurred, otherwise None.
+    class_name : Optional[str], optional
+        Name of the class containing the test, if applicable.
+    method : Optional[str], optional
+        Name of the method representing the test, if applicable.
+    module : Optional[str], optional
+        Name of the module containing the test, if applicable.
+    file_path : Optional[str], optional
+        Path to the file containing the test, if applicable.
+    doc_string : Optional[str], optional
+        Docstring of the test, if applicable.
 
-    Attributes:
-        id (Any): Unique identifier for the test result.
-        name (str): Name of the test.
-        status (TestStatus): Status of the test execution (e.g., passed, failed).
-        execution_time (float): Time taken to execute the test, in seconds.
-        error_message (Optional[str]): Error message if the test failed, otherwise None.
-        traceback (Optional[str]): Traceback information if an error occurred, otherwise None.
-        class_name (Optional[str]): Name of the class containing the test, if applicable.
-        method (Optional[str]): Name of the method representing the test, if applicable.
-        module (Optional[str]): Name of the module containing the test, if applicable.
-        file_path (Optional[str]): Path to the file containing the test, if applicable.
-        doc_string (Optional[str]): Docstring of the test, if applicable.
-
-    Returns:
-        TestResult: An immutable instance containing all details about a single test execution.
+    Attributes
+    ----------
+    id : Any
+        Unique identifier for the test result.
+    name : str
+        Name of the test.
+    status : TestStatus
+        Status of the test execution.
+    execution_time : float
+        Time taken to execute the test.
+    error_message : Optional[str]
+        Error message if the test failed.
+    traceback : Optional[str]
+        Traceback information if an error occurred.
+    class_name : Optional[str]
+        Name of the class containing the test.
+    method : Optional[str]
+        Name of the method representing the test.
+    module : Optional[str]
+        Name of the module containing the test.
+    file_path : Optional[str]
+        Path to the file containing the test.
+    doc_string : Optional[str]
+        Docstring of the test.
     """
 
     # Unique identifier for the test result

orionis/test/enums/status.py

@@ -2,26 +2,20 @@ from enum import Enum, auto
 
 class TestStatus(Enum):
     """
-    TestStatus(Enum)
-    An enumeration representing the possible statuses that a test can have during its execution.
+    Enumeration of possible statuses for a test during execution.
 
-    Attributes
-    ----------
-    PASSED : auto()
-        The test completed successfully without any errors or failures.
-    FAILED : auto()
-        The test ran to completion but did not produce the expected results.
-    ERRORED : auto()
-        An unexpected error occurred during the execution of the test, preventing it from completing.
-    SKIPPED : auto()
-        The test was intentionally not executed, typically due to configuration or conditional logic.
-
-    Returns
+    Members
     -------
-    TestStatus
-        An instance of the TestStatus enumeration indicating the current status of a test.
+    PASSED : enum
+        Indicates the test completed successfully without errors or failures.
+    FAILED : enum
+        Indicates the test completed but did not produce the expected results.
+    ERRORED : enum
+        Indicates an unexpected error occurred during test execution.
+    SKIPPED : enum
+        Indicates the test was intentionally not executed.
     """
     PASSED = auto()   # Test executed successfully
     FAILED = auto()   # Test executed but failed
     ERRORED = auto()  # Error occurred during test execution
-    SKIPPED = auto()  # Test was intentionally skipped
+    SKIPPED = auto()  # Test was intentionally skipped

orionis/test/exceptions/config.py

@@ -2,26 +2,22 @@ class OrionisTestConfigException(Exception):
 
     def __init__(self, msg: str):
         """
-        Initializes the OrionisTestConfigException with a descriptive error message.
+        Initialize the OrionisTestConfigException.
 
         Parameters
         ----------
         msg : str
-            Descriptive error message explaining the cause of the exception.
+            The error message describing the cause of the exception.
         """
-
-        # Call the base Exception class constructor with the message
         super().__init__(msg)
 
     def __str__(self) -> str:
         """
-        Returns a formatted string representation of the exception message.
+        Return the exception message as a string.
 
         Returns
         -------
         str
-            The error message provided during exception initialization.
+            The error message provided during initialization.
         """
-
-        # Return the first argument as the exception message
         return str(self.args[0])

orionis/test/exceptions/failure.py

@@ -4,11 +4,7 @@ class OrionisTestFailureException(Exception):
 
     def __init__(self, result: unittest.TestResult):
         """
-        Initializes the OrionisTestFailureException with details about failed and errored tests.
-
-        This constructor extracts information from the provided unittest.TestResult object,
-        including the IDs of tests that failed or encountered errors. It then formats a summary
-        message listing all such tests and passes this message to the base Exception class.
+        Initialize the exception with details of failed and errored tests.
 
         Parameters
         ----------
@@ -25,18 +21,7 @@ class OrionisTestFailureException(Exception):
             List of formatted error messages for each failed or errored test.
         text : str
             Formatted string summarizing all test failures and errors.
-
-        Returns
-        -------
-        None
-            This method does not return a value. It initializes the exception instance.
-
-        Raises
-        ------
-        OrionisTestFailureException
-            Raised when there are failed or errored tests, with a summary message.
         """
-
         # Collect IDs of failed tests
         failed_tests = [test.id() for test, _ in result.failures]
 
@@ -61,13 +46,12 @@ class OrionisTestFailureException(Exception):
 
     def __str__(self) -> str:
         """
-        Returns a formatted string describing the exception.
+        Return a formatted string describing the exception.
 
         Returns
         -------
         str
             The summary message containing the number and details of failed and errored tests.
         """
-
         # Return the first argument passed to the exception as a string
         return str(self.args[0])

orionis/test/exceptions/persistence.py

@@ -2,26 +2,22 @@ class OrionisTestPersistenceError(Exception):
 
     def __init__(self, msg: str):
         """
-        Initializes the OrionisTestPersistenceError with a descriptive error message.
+        Initialize the OrionisTestPersistenceError with an error message.
 
         Parameters
         ----------
         msg : str
-            A descriptive error message that explains the cause of the exception.
+            The error message describing the cause of the exception.
         """
-
-        # Call the base Exception class constructor with the message
         super().__init__(msg)
 
     def __str__(self) -> str:
         """
-        Returns a formatted string representation of the exception message.
+        Return the string representation of the exception message.
 
         Returns
         -------
         str
-            The error message provided when the exception was raised.
+            The error message associated with the exception.
         """
-
-        # Return the first argument passed to the exception as a string
         return str(self.args[0])

orionis/test/exceptions/runtime.py

@@ -2,26 +2,22 @@ class OrionisTestRuntimeError(Exception):
 
     def __init__(self, msg: str):
         """
-        Initializes the OrionisTestRuntimeError with a descriptive error message.
+        Initialize the OrionisTestRuntimeError with a specific error message.
 
         Parameters
         ----------
         msg : str
-            Descriptive error message explaining the cause of the exception.
+            The error message describing the cause of the exception.
         """
-
-        # Call the base class constructor with the error message
         super().__init__(msg)
 
     def __str__(self) -> str:
         """
-        Returns a formatted string representation of the exception.
+        Return the string representation of the exception.
 
         Returns
         -------
         str
-            The error message provided during exception initialization.
+            The error message provided during initialization.
         """
-
-        # Return the error message stored in the first argument
         return str(self.args[0])

orionis/test/exceptions/value.py

@@ -2,30 +2,22 @@ class OrionisTestValueError(Exception):
 
     def __init__(self, msg: str):
         """
-        Initializes the OrionisTestValueError with a descriptive error message.
+        Initialize the OrionisTestValueError exception.
 
         Parameters
         ----------
         msg : str
-            Descriptive error message explaining the cause of the exception.
+            The error message describing the cause of the exception.
         """
-
-        # Call the base class constructor with the error message
         super().__init__(msg)
 
     def __str__(self) -> str:
         """
-        Returns a formatted string representation of the exception.
-
-        This method retrieves the error message provided during initialization
-        and returns it as a string. It ensures that when the exception is
-        converted to a string, the descriptive message is displayed.
+        Return the string representation of the exception.
 
         Returns
         -------
         str
-            The descriptive error message associated with this exception.
+            The error message associated with this exception.
         """
-
-        # Return the error message stored in the first argument
-        return str(self.args[0])
+        return str(self.args[0])

orionis/test/kernel.py

@@ -21,29 +21,22 @@ class TestKernel(ITestKernel):
         Parameters
         ----------
         app : IApplication
-            The application instance implementing the IApplication contract.
+            Application instance implementing the IApplication contract.
 
         Raises
         ------
         OrionisTestConfigException
             If the provided app is not an instance of IApplication.
         """
-
-        # Validate that the app is an instance of IApplication
         if not isinstance(app, IApplication):
             raise OrionisTestConfigException(
                 f"Failed to initialize TestKernel: expected IApplication, got {type(app).__module__}.{type(app).__name__}."
             )
 
-        # Load testing configuration from the application
         self.__config = Testing(**app.config('testing'))
-
-        # Create and configure the unit test instance
         self.__unit_test: IUnitTest = app.make('core.orionis.testing')
         self.__unit_test._UnitTest__app = app
         self.__unit_test._UnitTest__storage = app.path('storage_testing')
-
-        # Initialize the console for output
         self.__console: IConsole = app.make('core.orionis.console')
 
     def __listMatchingFolders(
@@ -53,52 +46,47 @@ class TestKernel(ITestKernel):
         pattern: str
     ) -> List[str]:
         """
-        List folders within a custom path whose files match a given pattern.
+        List folders within a given path containing files matching a pattern.
 
         Parameters
         ----------
         base_path : Path
-            The base directory path for relative calculation.
+            The base directory path for calculating relative paths.
         custom_path : Path
-            The custom directory path to search for matching files.
+            The directory path to search for matching files.
         pattern : str
-            The filename pattern to match (supports '*' and '?').
+            The filename pattern to match, supporting '*' and '?' wildcards.
 
         Returns
         -------
         List[str]
             List of relative folder paths containing files matching the pattern.
         """
-
-        # Compile the pattern into a regex for matching file names
         regex = re.compile('^' + pattern.replace('*', '.*').replace('?', '.') + '$')
         matched_folders = set()
-
-        # Walk through the directory tree starting at custom_path
         for root, _, files in walk(str(custom_path)):
-
-            # Check if any file in the current folder matches the pattern
             if any(regex.fullmatch(file) for file in files):
-
-                # Calculate the relative path from base_path and add to results
                 rel_path = Path(root).relative_to(base_path).as_posix()
                 matched_folders.add(rel_path)
-
-        # Return the list of matching folder paths
         return list(matched_folders)
 
     def handle(self) -> IUnitTest:
         """
-        Configure and execute the unit tests based on the current configuration.
+        Configure, discover, and execute unit tests based on the current configuration.
 
         Returns
         -------
         IUnitTest
             The configured and executed unit test instance.
+
+        Raises
+        ------
+        OrionisTestFailureException
+            If test execution fails.
+        Exception
+            If an unexpected error occurs during test execution.
         """
         try:
-
-            # Configure the unit test with parameters from the configuration
             self.__unit_test.configure(
                 verbosity=self.__config.verbosity,
                 execution_mode=self.__config.execution_mode,
@@ -111,32 +99,21 @@ class TestKernel(ITestKernel):
                 web_report=self.__config.web_report
             )
 
-            # Prepare paths and pattern for test discovery
             base_path = (Path.cwd() / self.__config.base_path).resolve()
             folder_path = self.__config.folder_path
             pattern = self.__config.pattern
-
-            # Set to hold discovered folders
             discovered_folders = set()
 
-            # Discover folders containing test files according to the configuration
-
-            # Search all folders under base_path
             if folder_path == '*':
                 discovered_folders.update(self.__listMatchingFolders(base_path, base_path, pattern))
-
-            # Search each custom folder in the list
             elif isinstance(folder_path, list):
                 for custom in folder_path:
                     custom_path = (base_path / custom).resolve()
                     discovered_folders.update(self.__listMatchingFolders(base_path, custom_path, pattern))
-
-            # Search a single custom folder
             else:
                 custom_path = (base_path / folder_path).resolve()
                 discovered_folders.update(self.__listMatchingFolders(base_path, custom_path, pattern))
 
-            # Register discovered folders with the unit test for test discovery
             for folder in discovered_folders:
                 self.__unit_test.discoverTestsInFolder(
                     folder_path=folder,
@@ -146,15 +123,10 @@ class TestKernel(ITestKernel):
                     tags=self.__config.tags or None
                 )
 
-            # Run the unit tests and return the result
             return self.__unit_test.run()
 
         except OrionisTestFailureException as e:
-
-            # Handle test failures and exit with an error message
             self.__console.exitError(f"Test execution failed: {e}")
 
         except Exception as e:
-
-            # Handle unexpected errors and exit with a generic error message
-            self.__console.exitError(f"An unexpected error occurred: {e}")
+            self.__console.exitError(f"An unexpected error occurred: {e}")

orionis/test/output/dumper.py

@@ -6,34 +6,16 @@ from orionis.test.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.
-        - 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.
+    Utility class for debugging and outputting information during test execution.
+
+    Provides methods to determine if an object is a test case instance, output debugging
+    information using the Debug class, manage standard output and error streams, and
+    capture the caller's file and line number for context.
     """
 
     def __isTestCaseClass(self, value) -> bool:
         """
-        Determines whether the provided value is an instance of a recognized test case class.
-
-        This method checks if the given object is an instance of either AsyncTestCase or SyncTestCase,
-        which are the supported test case base classes in the Orionis testing framework.
+        Check if the provided value is an instance of a recognized test case class.
 
         Parameters
         ----------
@@ -43,8 +25,8 @@ class TestDumper(ITestDumper):
         Returns
         -------
         bool
-            Returns True if `value` is an instance of AsyncTestCase or SyncTestCase.
-            Returns False if `value` is None, not an instance of these classes, or if any import error occurs.
+            True if `value` is an instance of AsyncTestCase, SyncTestCase, unittest.TestCase,
+            or unittest.IsolatedAsyncioTestCase. False otherwise or if an import error occurs.
         """
 
         # If the value is None, it cannot be a test case instance.
@@ -76,23 +58,21 @@ class TestDumper(ITestDumper):
 
     def dd(self, *args) -> None:
         """
-        Outputs debugging information using the Debug class and halts further execution.
+        Output debugging information and halt further execution.
 
-        This method captures the caller's file and line number to provide context for the debug output.
-        It temporarily redirects standard output and error streams to ensure the debug information is
-        displayed correctly. If the first argument is a recognized test case instance, it is skipped
-        in the output to avoid redundant information. The method raises an exception if any error
-        occurs during the dumping process.
+        Captures the caller's file and line number for context. Temporarily redirects
+        standard output and error streams to ensure correct display. If the first argument
+        is a recognized test case instance, it is skipped in the output. Raises a custom
+        runtime error if dumping fails.
 
         Parameters
         ----------
         *args : tuple
-            Variable length argument list containing the objects to be dumped.
+            Objects to be dumped.
 
         Returns
         -------
         None
-            This method does not return any value. It outputs debug information and may halt execution.
         """
 
         # If no arguments are provided, exit the method early.
@@ -136,23 +116,21 @@ class TestDumper(ITestDumper):
 
     def dump(self, *args) -> None:
         """
-        Outputs debugging information using the Debug class.
+        Output debugging information.
 
-        This method captures the caller's file and line number to provide context for the debug output.
-        It temporarily redirects standard output and error streams to ensure the debug information is
-        displayed correctly. If the first argument is a recognized test case instance, it is skipped
-        in the output to avoid redundant information. The method raises an exception if any error
-        occurs during the dumping process.
+        Captures the caller's file and line number for context. Temporarily redirects
+        standard output and error streams to ensure correct display. If the first argument
+        is a recognized test case instance, it is skipped in the output. Raises a custom
+        runtime error if dumping fails.
 
         Parameters
         ----------
         *args : tuple
-            Variable length argument list containing the objects to be dumped.
+            Objects to be dumped.
 
         Returns
         -------
         None
-            This method does not return any value. It outputs debug information.
         """
 
         # If no arguments are provided, exit the method early.
@@ -192,4 +170,4 @@ class TestDumper(ITestDumper):
 
             # Restore the original stdout and stderr
             sys.stdout = original_stdout
-            sys.stderr = original_stderr
+            sys.stderr = original_stderr