orionis 0.245.0__py3-none-any.whl → 0.247.0__py3-none-any.whl

orionis/luminate/test/core/contracts/test_unit.py

@@ -1,82 +1,126 @@
-from typing import Any, Dict, Optional
+from abc import ABC, abstractmethod
+from typing import Any, Dict, List, Optional
+from orionis.luminate.test.enums.test_mode import ExecutionMode
 
-class IUnitTest:
+class IUnitTest(ABC):
     """
-    Advanced unit testing utility for discovering, executing, and reporting test results
-    with support for folder-based discovery, regex filtering, and customizable output.
-
-    Attributes
-    ----------
-    loader : unittest.TestLoader
-        Internal loader for test discovery.
-    suite : unittest.TestSuite
-        The aggregated test suite to be executed.
-    test_results : List[TestResult]
-        List of captured results per test, including status and errors.
-    start_time : float
-        Timestamp when the test execution started.
+    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,
+            max_workers: int = None,
+            fail_fast: bool = None,
+            print_result: bool = None
+        ):
+        """
+        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.
+
+        Returns:
+            UnitTest: The configured UnitTest instance.
+        """
+        pass
+
+    @abstractmethod
     def discoverTestsInFolder(
         self,
         folder_path: str,
         base_path: str = "tests",
         pattern: str = "test_*.py",
-        test_name_pattern: Optional[str] = None
+        test_name_pattern: Optional[str] = None,
+        tags: Optional[List[str]] = None
     ):
         """
-        Discover and add test cases from a given folder to the test suite.
+        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.
+        """
+        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.
+        """
+        pass
 
-        Parameters
-        ----------
-        folder_path : str
-            Relative path to the folder containing test files.
-        base_path : str, default="tests"
-            Base path used to resolve full path to test modules.
-        pattern : str, default="test_*.py"
-            Glob pattern to match test filenames.
-        test_name_pattern : Optional[str], optional
-            Regex pattern to filter discovered test method names.
+    @abstractmethod
+    def run(self, print_result: bool = None, throw_exception: bool = False) -> 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.
+        """
+        pass
 
-        Returns
-        -------
-        UnitTest
-            Self instance for chaining.
+    @abstractmethod
+    def getTestNames(self) -> List[str]:
+        """
+        Retrieves a list of test names from the test suite.
 
-        Raises
-        ------
-        ValueError
-            If folder is invalid or no tests are found.
+        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.
         """
         pass
 
-    def run(self, print_result:bool = True, throw_exception:bool = False) -> Dict[str, Any]:
+    @abstractmethod
+    def getTestCount(self) -> int:
         """
-        Run all added tests and return a summary of the results.
+        Calculate the total number of tests in the test suite.
 
-        Parameters
-        ----------
-        print_result : bool, default=True
-            Whether to print a formatted report to the console.
-        throw_exception : bool, default=False
-            Raise an exception if there are failures or errors.
+        This method flattens the test suite structure and counts the total
+        number of individual test cases.
 
-        Returns
-        -------
-        Dict[str, Any]
-            Summary including:
-            - total_tests : int
-            - passed : int
-            - failed : int
-            - errors : int
-            - skipped : int
-            - total_time : str (e.g., '1.234 seconds')
-            - success_rate : str (e.g., '87.5%')
-            - test_details : List[Dict[str, Any]]
+        Returns:
+            int: The total number of test cases in the test suite.
+        """
+        pass
+
+    @abstractmethod
+    def clearTests(self) -> None:
+        """
+        Clears the current test suite by reinitializing it to an empty `unittest.TestSuite`.
 
-        Raises
-        ------
-        OrionisTestFailureException
-            If any test fails or errors occur and `throw_exception=True`.
+        This method is used to reset the test suite, removing any previously added tests.
         """
         pass

orionis/luminate/test/core/test_suite.py

@@ -1,53 +1,62 @@
 import re
 from os import walk
+from orionis.luminate.config.entities.testing import Testing
 from orionis.luminate.test.core.contracts.test_suite import ITestSuite
-from orionis.luminate.test.core.test_unit import UnitTest as UnitTestClass
+from orionis.luminate.test.core.test_unit import UnitTest
+from orionis.luminate.test.exceptions.test_config_exception import OrionisTestConfigException
 
 class TestSuite(ITestSuite):
     """
-    A class containing test utility methods.
+    TestSuite provides static configuration and initialization of a unit test suite based on a given Testing configuration.
+    Methods:
+        config(config: Testing) -> UnitTest
+            Configures and initializes a test suite using the provided Testing configuration.
+            - Validates the type of the configuration object.
+            - Sets up the UnitTest suite with parameters such as verbosity, execution mode, worker count, and error handling.
+            - Discovers test folders based on base path, folder path(s), and filename pattern, supporting wildcards.
+            - Adds discovered test folders to the suite, optionally filtering by test name pattern and tags.
+        OrionisTestConfigException: If the provided config is not an instance of the Testing class.
     """
 
     @staticmethod
-    def load(
-        base_path: str = 'tests',
-        folder_path: list | str = '*',
-        pattern: str = 'test_*.py'
-    ) -> UnitTestClass:
+    def config(config:Testing) -> UnitTest:
+        """
+        Configures and initializes a UnitTest suite based on the provided Testing configuration.
+        Args:
+            config (Testing): An instance of the Testing class containing configuration options for the test suite.
+        Returns:
+            UnitTest: An initialized UnitTest suite configured according to the provided settings.
+        Raises:
+            OrionisTestConfigException: If the config parameter is not an instance of the Testing class.
+        The function performs the following steps:
+            - Validates the type of the config parameter.
+            - Initializes a UnitTest suite and applies configuration values from the Testing instance.
+            - Discovers folders containing test files based on the specified base path, folder path(s), and filename pattern.
+            - Adds discovered test folders to the UnitTest suite, applying optional test name patterns and tags.
+            - Returns the configured UnitTest suite ready for execution.
         """
-        Discover and initialize a test suite from the specified folder(s).
 
-        This method scans the provided folder(s) for test files matching the given pattern
-        and initializes a test suite with the discovered files.
+        # Check if the config is an instance of Testing
+        if not isinstance(config, Testing):
+            raise OrionisTestConfigException("The config parameter must be an instance of the Testing class.")
 
-        Parameters
-        ----------
-        base_path : str, optional
-            The base path for the tests. Defaults to 'tests'.
-        folder_path : str or list of str, optional
-            Path(s) to the folder(s) containing test files. Use '*' to scan all folders
-            under the base path. Defaults to '*'.
-        pattern : str, optional
-            File pattern to match test files. Defaults to 'test_*.py'.
+        # Initialize the test suite
+        tests = UnitTest()
 
-        Returns
-        -------
-        UnitTestClass
-            An initialized test suite containing the discovered test files.
+        # Assign config values to the test suite
+        tests.configure(
+            verbosity=config.verbosity,
+            execution_mode=config.execution_mode,
+            max_workers=config.max_workers,
+            fail_fast=config.fail_fast,
+            print_result=config.print_result,
+            throw_exception=config.throw_exception
+        )
 
-        Raises
-        ------
-        TypeError
-            If `base_path` is not a string, `folder_path` is not a string or list, or
-            `pattern` is not a string.
-        """
-        # Validate parameters
-        if not isinstance(base_path, str):
-            raise TypeError("base_path must be a string")
-        if not isinstance(folder_path, (str, list)):
-            raise TypeError("folder_path must be a string or a list")
-        if not isinstance(pattern, str):
-            raise TypeError("pattern must be a string")
+        # Extract configuration values
+        base_path = config.base_path
+        folder_path = config.folder_path
+        pattern = config.pattern
 
         # Helper function to list folders matching the pattern
         def list_matching_folders(custom_path: str, pattern: str):
@@ -66,19 +75,18 @@ class TestSuite(ITestSuite):
             discovered_folders.extend(list_matching_folders(base_path, pattern))
         elif isinstance(folder_path, list):
             for custom_path in folder_path:
-                discovered_folders.extend(list_matching_folders(custom_path, pattern))
+                discovered_folders.extend(list_matching_folders(f"{base_path}/{custom_path}", pattern))
         else:
             discovered_folders.extend(list_matching_folders(folder_path, pattern))
 
-        # Initialize the test suite
-        tests = UnitTestClass()
-
         # Add discovered folders to the test suite
         for folder in discovered_folders:
             tests.discoverTestsInFolder(
-                base_path=base_path,
                 folder_path=folder,
-                pattern=pattern
+                base_path=base_path,
+                pattern=pattern,
+                test_name_pattern=config.test_name_pattern if config.test_name_pattern else None,
+                tags=config.tags if config.tags else None
             )
 
         # Return the initialized test suite