orionis 0.404.0__py3-none-any.whl → 0.406.0__py3-none-any.whl

orionis/test/records/logs.py

@@ -1,9 +1,7 @@
 import json
-import re
 import sqlite3
 from pathlib import Path
 from typing import Dict, List, Optional, Tuple
-from orionis.services.environment.env import Env
 from orionis.test.exceptions import OrionisTestPersistenceError, OrionisTestValueError
 from orionis.test.contracts.logs import ITestLogs
 
@@ -11,64 +9,42 @@ class TestLogs(ITestLogs):
 
     def __init__(
         self,
-        storage_path: Optional[str] = None,
-        db_name: Optional[str] = 'tests.sqlite',
-        table_name: Optional[str] = 'reports',
+        storage_path: str
     ) -> None:
         """
-        Initialize the history storage for test logs.
+        Initialize a new instance of the TestLogs class, configuring the SQLite database path and connection.
+
+        This constructor sets up the database file and table names, ensures the storage directory exists,
+        and prepares the absolute path for the SQLite database file. The database connection is initialized
+        as None and will be established when needed.
 
         Parameters
         ----------
-        storage_path : Optional[str], default=None
-            Directory path where the database file will be stored. If not provided,
-            the path is determined from the TEST_DB_PATH environment variable or
-            defaults to 'orionis/test/logs/storage' in the current working directory.
-        db_name : Optional[str], default='tests.sqlite'
-            Name of the SQLite database file. Must be alphanumeric or underscore and
-            end with '.sqlite'.
-        table_name : Optional[str], default='reports'
-            Name of the table to use in the database. Must be alphanumeric or underscore.
+        storage_path : str
+            The directory path where the SQLite database file ('tests.sqlite') will be stored. If the directory
+            does not exist, it will be created automatically.
 
-        Raises
-        ------
-        OrionisTestValueError
-            If db_name or table_name do not meet the required format.
+        Returns
+        -------
+        None
+            This method does not return a value.
         """
 
-        # Validate db_name: only alphanumeric and underscores, must end with .sqlite
-        if not isinstance(db_name, str) or not re.fullmatch(r'[a-zA-Z0-9_]+\.sqlite', db_name):
-            raise OrionisTestValueError("Database name must be alphanumeric/underscore and end with '.sqlite'.")
-        self.__db_name = db_name
-
-        # Validate table_name: only alphanumeric and underscores
-        if not isinstance(table_name, str) or not re.fullmatch(r'[a-zA-Z0-9_]+', table_name):
-            raise OrionisTestValueError("Table name must be alphanumeric/underscore only.")
-        self.__table_name = table_name
-
-        # Determine database path
-        db_path = None
-        if storage_path:
-            db_path = Path(storage_path).expanduser().resolve()
-            if db_path.is_dir():
-                db_path = db_path / self.__db_name
-        else:
-            env_path = Env.get("TEST_DB_PATH", None)
-            if env_path:
-                db_path = Path(env_path).expanduser().resolve()
-                if db_path.is_dir():
-                    db_path = db_path / self.__db_name
-            else:
-                db_path = Path.cwd() / 'storage/framework/testing' / self.__db_name
-
-        # Ensure parent directory exists
+        # Set the database file and table names
+        self.__db_name = 'tests.sqlite'
+        self.__table_name = 'reports'
+
+        # Create the full path to the database file
+        db_path = Path(storage_path)
+        db_path = db_path / self.__db_name
+
+        # Ensure the parent directory exists
         db_path.parent.mkdir(parents=True, exist_ok=True)
 
-        # Store path in environment
-        Env.set("TEST_DB_PATH", str(db_path), 'path')
-        self.__db_path = db_path
+        # Store the resolved absolute path to the database
+        self.__db_path = db_path.resolve()
 
-        # Create a connection to the database, initially set to None
+        # Initialize the database connection as None
         self._conn: Optional[sqlite3.Connection] = None
 
     def __connect(
@@ -77,28 +53,56 @@ class TestLogs(ITestLogs):
         """
         Establishes a connection to the SQLite database if not already connected.
 
-        Attempts to create a new SQLite connection using the provided database path.
-        If the connection fails, raises an OrionisTestPersistenceError with the error details.
+        This method checks if a database connection is already established. If not, it attempts to create a new
+        SQLite connection using the absolute path specified during initialization. If the connection attempt fails,
+        it raises an OrionisTestPersistenceError with the error details.
 
         Raises
         ------
         OrionisTestPersistenceError
             If a database connection error occurs.
+
+        Returns
+        -------
+        None
+            This method does not return a value. It sets the self._conn attribute to an active SQLite connection
+            if successful, or raises an exception if the connection fails.
         """
+
+        # Only connect if there is no existing connection
         if self._conn is None:
+
             try:
-                self._conn = sqlite3.connect(str(self.__db_path))
+
+                # Attempt to establish a new SQLite connection
+                self._conn = sqlite3.connect(
+                    database=str(self.__db_path),
+                    timeout=5.0,
+                    isolation_level=None,
+                    check_same_thread=False,
+                    autocommit=True
+                )
+
+                # Hability to use WAL mode for better concurrency
+                self._conn.execute("PRAGMA journal_mode=WAL;")
+                self._conn.execute("PRAGMA synchronous=NORMAL;")
+
             except (sqlite3.Error, Exception) as e:
+
+                # Raise a custom exception if connection fails
                 raise OrionisTestPersistenceError(f"Database connection error: {e}")
 
     def __createTableIfNotExists(
         self
     ) -> bool:
         """
-        Ensures that the test history table exists in the database.
+        Ensures the existence of the test history table in the SQLite database.
 
-        Connects to the database and creates the table with the required schema if it does not already exist.
-        Handles any SQLite errors by rolling back the transaction and raising a custom exception.
+        This method establishes a connection to the database and attempts to create the table
+        specified by `self.__table_name` with the required schema if it does not already exist.
+        The table includes columns for the report JSON, test statistics, and a timestamp.
+        If a database error occurs during table creation, the transaction is rolled back and
+        an OrionisTestPersistenceError is raised.
 
         Raises
         ------
@@ -108,12 +112,19 @@ class TestLogs(ITestLogs):
         Returns
         -------
         bool
-            True if the table was created successfully or already exists, False otherwise.
+            Returns True if the table was created successfully or already exists.
+            Returns False only if an unexpected error occurs (which will typically raise an exception).
         """
 
+        # Establish a connection to the database
         self.__connect()
+
         try:
+
+            # Create a cursor to execute SQL commands
             cursor = self._conn.cursor()
+
+            # Create the table with the required schema if it does not exist
             cursor.execute(f'''
                 CREATE TABLE IF NOT EXISTS {self.__table_name} (
                     id INTEGER PRIMARY KEY AUTOINCREMENT,
@@ -128,13 +139,25 @@ class TestLogs(ITestLogs):
                     timestamp TEXT
                 )
             ''')
+
+            # Commit the transaction to save changes
             self._conn.commit()
+
+            # Return True indicating the table exists or was created successfully
             return True
+
         except sqlite3.Error as e:
+
+            # Roll back the transaction if an error occurs
             if self._conn:
                 self._conn.rollback()
+
+            # Raise a custom exception with the error details
             raise OrionisTestPersistenceError(f"Failed to create table: {e}")
+
         finally:
+
+            # Close the database connection
             if self._conn:
                 self.__close()
                 self._conn = None
@@ -146,10 +169,14 @@ class TestLogs(ITestLogs):
         """
         Inserts a test report into the history database table.
 
+        This method validates the provided report dictionary to ensure all required fields are present,
+        serializes the report as JSON, and inserts it into the database table. If any required field is missing,
+        or if a database error occurs during insertion, an appropriate exception is raised.
+
         Parameters
         ----------
         report : Dict
-            A dictionary containing the report data. Must include the following keys:
+            A dictionary containing the report data. The dictionary must include the following keys:
             - total_tests
             - passed
             - failed
@@ -169,16 +196,17 @@ class TestLogs(ITestLogs):
         Returns
         -------
         bool
-            True if the report was successfully inserted, False otherwise.
+            Returns True if the report was successfully inserted into the database.
+            Returns False only if an unexpected error occurs (which will typically raise an exception).
         """
 
-        # Required fields in the report
+        # List of required fields for the report
         fields = [
             "json", "total_tests", "passed", "failed", "errors",
             "skipped", "total_time", "success_rate", "timestamp"
         ]
 
-        # Validate report structure
+        # Check for missing required fields (excluding "json" which is handled separately)
         missing = []
         for key in fields:
             if key not in report and key != "json":
@@ -186,11 +214,10 @@ class TestLogs(ITestLogs):
         if missing:
             raise OrionisTestValueError(f"Missing report fields: {missing}")
 
-        # Insert the report into the database
+        # Establish a connection to the database
         self.__connect()
         try:
-
-            # Query to insert the report into the table
+            # Prepare the SQL query to insert the report data
             query = f'''
                 INSERT INTO {self.__table_name} (
                     json, total_tests, passed, failed, errors,
@@ -198,8 +225,10 @@ class TestLogs(ITestLogs):
                 ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
             '''
 
-            # Execute the insert query with the report data
+            # Execute the insert query with the report data, serializing the entire report as JSON
             cursor = self._conn.cursor()
+
+            # Ensure the 'json' field is serialized to JSON format
             cursor.execute(query, (
                 json.dumps(report),
                 report["total_tests"],
@@ -211,13 +240,23 @@ class TestLogs(ITestLogs):
                 report["success_rate"],
                 report["timestamp"]
             ))
+
+            # Commit the transaction to save the new report
             self._conn.commit()
+
+            # Return True indicating the report was successfully inserted
             return True
+
         except sqlite3.Error as e:
+
+            # Roll back the transaction if an error occurs during insertion
             if self._conn:
                 self._conn.rollback()
             raise OrionisTestPersistenceError(f"Failed to insert report: {e}")
+
         finally:
+
+            # Ensure the database connection is closed after the operation
             if self._conn:
                 self.__close()
                 self._conn = None
@@ -230,6 +269,11 @@ class TestLogs(ITestLogs):
         """
         Retrieves a specified number of report records from the database, ordered by their ID.
 
+        This method allows fetching either the earliest or latest test reports from the database,
+        depending on the parameters provided. If `first` is specified, it retrieves the earliest
+        reports in ascending order by ID. If `last` is specified, it retrieves the latest reports
+        in descending order by ID. Only one of `first` or `last` can be provided at a time.
+
         Parameters
         ----------
         first : Optional[int], default=None
@@ -240,7 +284,9 @@ class TestLogs(ITestLogs):
         Returns
         -------
         List[Tuple]
-            A list of tuples representing the report records.
+            A list of tuples, where each tuple represents a report record retrieved from the database.
+            Each tuple contains all columns from the reports table, including the serialized JSON report
+            and associated statistics.
 
         Raises
         ------
@@ -250,31 +296,52 @@ class TestLogs(ITestLogs):
             If there is an error retrieving reports from the database.
         """
 
-        # Validate parameters
+        # Ensure that only one of 'first' or 'last' is specified
         if first is not None and last is not None:
             raise OrionisTestValueError(
                 "Cannot specify both 'first' and 'last' parameters. Use one or the other."
             )
+
+        # Validate 'first' parameter if provided
         if first is not None:
             if not isinstance(first, int) or first <= 0:
                 raise OrionisTestValueError("'first' must be an integer greater than 0.")
+
+        # Validate 'last' parameter if provided
         if last is not None:
             if not isinstance(last, int) or last <= 0:
                 raise OrionisTestValueError("'last' must be an integer greater than 0.")
 
+        # Determine the order and quantity of records to retrieve
         order = 'DESC' if last is not None else 'ASC'
         quantity = first if first is not None else last
 
+        # Establish a connection to the database
         self.__connect()
+
         try:
+
+            # Create a cursor to execute SQL commands
             cursor = self._conn.cursor()
+
+            # Prepare the SQL query to select the desired reports
             query = f"SELECT * FROM {self.__table_name} ORDER BY id {order} LIMIT ?"
             cursor.execute(query, (quantity,))
+
+            # Fetch all matching records
             results = cursor.fetchall()
+
+            # Return the list of report records
             return results
+
         except sqlite3.Error as e:
+
+            # Raise a custom exception if retrieval fails
             raise OrionisTestPersistenceError(f"Failed to retrieve reports from '{self.__db_name}': {e}")
+
         finally:
+
+            # Ensure the database connection is closed after the operation
             if self._conn:
                 self.__close()
                 self._conn = None
@@ -283,32 +350,47 @@ class TestLogs(ITestLogs):
         self
     ) -> bool:
         """
-        Resets the database by dropping the existing table.
-        This method connects to the database, drops the table specified by
-        `self.__table_name` if it exists, commits the changes, and then closes
-        the connection. If an error occurs during the process, an
-        OrionisTestPersistenceError is raised.
+        Drops the reports table from the SQLite database, effectively resetting the test history.
+
+        This method establishes a connection to the database and attempts to drop the table specified
+        by `self.__table_name` if it exists. After dropping the table, it commits the changes and closes
+        the connection. If an error occurs during the operation, an OrionisTestPersistenceError is raised.
 
         Raises
         ------
         OrionisTestPersistenceError
-            If the database reset operation fails due to an SQLite error.
+            If an SQLite error occurs while attempting to drop the table.
 
         Returns
         -------
         bool
-            True if the database was successfully reset, False otherwise.
+            Returns True if the table was successfully dropped or did not exist.
+            Returns False only if an unexpected error occurs (which will typically raise an exception).
         """
 
+        # Establish a connection to the database
         self.__connect()
+
         try:
+
+            # Create a cursor and execute the DROP TABLE statement
             cursor = self._conn.cursor()
             cursor.execute(f'DROP TABLE IF EXISTS {self.__table_name}')
+
+            # Commit the transaction to apply the changes
             self._conn.commit()
+
+            # Return True to indicate the reset was successful
             return True
+
         except sqlite3.Error as e:
+
+            # Raise a custom exception if the reset fails
             raise OrionisTestPersistenceError(f"Failed to reset database: {e}")
+
         finally:
+
+            # Ensure the database connection is closed after the operation
             if self._conn:
                 self.__close()
                 self._conn = None
@@ -317,14 +399,19 @@ class TestLogs(ITestLogs):
         self
     ) -> None:
         """
-        Closes the current database connection.
-        This method checks if a database connection exists. If so, it closes the connection and sets the connection attribute to None.
+        Closes the active SQLite database connection if it exists.
+
+        This method checks whether a database connection is currently open. If so, it closes the connection
+        to release any associated resources and sets the connection attribute to None to indicate that
+        there is no active connection.
 
         Returns
         -------
         None
+            This method does not return a value. It ensures that the database connection is properly closed.
         """
 
+        # If a database connection exists, close it and set the connection attribute to None
         if self._conn:
             self._conn.close()
             self._conn = None
@@ -334,32 +421,50 @@ class TestLogs(ITestLogs):
         report: Dict
     ) -> bool:
         """
-        Create a new test report in the history database.
+        Inserts a new test report into the history database after ensuring the reports table exists.
+
+        This method first checks for the existence of the reports table in the SQLite database,
+        creating it if necessary. It then attempts to insert the provided report dictionary into
+        the table. The report must contain all required fields as defined by the schema.
 
         Parameters
         ----------
         report : Dict
-            A dictionary containing the test report data.
+            A dictionary containing the test report data. The dictionary must include all required
+            fields such as total_tests, passed, failed, errors, skipped, total_time, success_rate, and timestamp.
 
         Returns
         -------
         bool
-            True if the report was successfully created, False otherwise.
+            Returns True if the report was successfully inserted into the database.
+            Raises an exception if the operation fails due to missing fields or database errors.
         """
+
+        # Ensure the reports table exists before inserting the report
         self.__createTableIfNotExists()
+
+        # Insert the report into the database and return the result
         return self.__insertReport(report)
 
     def reset(
         self
     ) -> bool:
         """
-        Reset the history database by dropping the existing table.
+        Drops the reports table from the SQLite database, effectively clearing all test history records.
+
+        This method establishes a connection to the database and attempts to drop the table specified
+        by `self.__table_name` if it exists. This operation removes all stored test reports, resetting
+        the database to an empty state. If the table does not exist, the method completes without error.
+        If an error occurs during the operation, an OrionisTestPersistenceError is raised.
 
         Returns
         -------
         bool
-            True if the database was successfully reset, False otherwise.
+            Returns True if the reports table was successfully dropped or did not exist.
+            Raises an exception if the operation fails due to a database error.
         """
+
+        # Attempt to drop the reports table and reset the database
         return self.__resetDatabase()
 
     def get(
@@ -368,7 +473,12 @@ class TestLogs(ITestLogs):
         last: Optional[int] = None
     ) -> List[Tuple]:
         """
-        Retrieve test reports from the history database.
+        Retrieves test reports from the history database based on the specified parameters.
+
+        This method allows fetching either the earliest or latest test reports from the database.
+        If `first` is provided, it retrieves the earliest reports in ascending order by ID.
+        If `last` is provided, it retrieves the latest reports in descending order by ID.
+        Only one of `first` or `last` can be specified at a time; providing both will result in an error.
 
         Parameters
         ----------
@@ -380,6 +490,17 @@ class TestLogs(ITestLogs):
         Returns
         -------
         List[Tuple]
-            A list of tuples representing the retrieved reports.
+            A list of tuples, where each tuple represents a report record retrieved from the database.
+            Each tuple contains all columns from the reports table, including the serialized JSON report
+            and associated statistics.
+
+        Raises
+        ------
+        OrionisTestValueError
+            If both 'first' and 'last' are specified, or if either is not a positive integer.
+        OrionisTestPersistenceError
+            If there is an error retrieving reports from the database.
         """
+
+        # Delegate the retrieval logic to the internal __getReports method
         return self.__getReports(first, last)

orionis/test/validators/__init__.py

@@ -0,0 +1,33 @@
+from .base_path import ValidBasePath
+from .execution_mode import ValidExecutionMode
+from .fail_fast import ValidFailFast
+from .folder_path import ValidFolderPath
+from .module_name import ValidModuleName
+from .name_pattern import ValidNamePattern
+from .pattern import ValidPattern
+from .persistent_driver import ValidPersistentDriver
+from .persistent import ValidPersistent
+from .print_result import ValidPrintResult
+from .tags import ValidTags
+from .throw_exception import ValidThrowException
+from .verbosity import ValidVerbosity
+from .web_report import ValidWebReport
+from .workers import ValidWorkers
+
+__all__ = [
+    'ValidBasePath',
+    'ValidExecutionMode',
+    'ValidFailFast',
+    'ValidFolderPath',
+    'ValidModuleName',
+    'ValidNamePattern',
+    'ValidPattern',
+    'ValidPersistentDriver',
+    'ValidPersistent',
+    'ValidPrintResult',
+    'ValidTags',
+    'ValidThrowException',
+    'ValidVerbosity',
+    'ValidWebReport',
+    'ValidWorkers'
+]

orionis/test/validators/base_path.py

@@ -0,0 +1,45 @@
+from pathlib import Path
+from orionis.test.exceptions import OrionisTestValueError
+
+class __ValidBasePath:
+
+    def __call__(self, base_path) -> Path:
+        """
+        Callable class to validate and normalize a base path.
+        This validator ensures that the provided `base_path` is either a non-empty string or a `Path` object.
+        If valid, it returns a normalized `Path` object. Otherwise, it raises an `OrionisTestValueError`.
+
+        Parameters
+        ----------
+        base_path : str or Path
+            The base path to validate. Must be a non-empty string or a `Path` object.
+
+        Returns
+        -------
+        Path
+            A normalized `Path` object corresponding to the provided base path.
+            If `base_path` is not a non-empty string or a valid `Path` object.
+        """
+
+        if isinstance(base_path, str):
+            base_path = base_path.strip()
+            if not base_path:
+                raise OrionisTestValueError(
+                    "Invalid base_path: Expected a non-empty string or Path."
+                )
+            return Path(base_path)
+
+        elif isinstance(base_path, Path):
+            if not str(base_path).strip():
+                raise OrionisTestValueError(
+                    "Invalid base_path: Path cannot be empty."
+                )
+            return base_path
+
+        else:
+            raise OrionisTestValueError(
+                f"Invalid base_path: Expected a non-empty string or Path, got '{str(base_path)}' ({type(base_path).__name__})."
+            )
+
+# Exported singleton instance
+ValidBasePath = __ValidBasePath()

orionis/test/validators/execution_mode.py

@@ -0,0 +1,45 @@
+from orionis.foundation.config.testing.enums.mode import ExecutionMode
+from orionis.test.exceptions import OrionisTestValueError
+
+class __ValidExecutionMode:
+
+    def __call__(self, execution_mode: str | ExecutionMode) -> str:
+        """
+        Validates that the provided execution_mode is either a valid string representation
+        of an ExecutionMode enum member or an instance of the ExecutionMode enum.
+
+        Parameters
+        ----------
+        execution_mode : str or ExecutionMode
+            The execution mode to validate. Can be a string (case-insensitive) matching
+            an ExecutionMode enum member, or an ExecutionMode enum instance.
+
+        Returns
+        -------
+        str
+            The string value of the validated ExecutionMode.
+
+        Raises
+        ------
+        OrionisTestValueError
+            If execution_mode is not a string or ExecutionMode enum, or if the string
+            does not correspond to a valid ExecutionMode member.
+        """
+
+        if not isinstance(execution_mode, (str, ExecutionMode)):
+            raise OrionisTestValueError(
+                f"Invalid execution_mode: Expected a string or ExecutionMode enum, got '{execution_mode}' ({type(execution_mode).__name__})."
+            )
+
+        if isinstance(execution_mode, ExecutionMode):
+            return execution_mode.value
+
+        elif isinstance(execution_mode, str):
+            if execution_mode.upper() not in ExecutionMode.__members__:
+                raise OrionisTestValueError(
+                    f"Invalid execution_mode: '{execution_mode}' is not a valid ExecutionMode."
+                )
+            return ExecutionMode[execution_mode.upper()].value
+
+# Exported singleton instance
+ValidExecutionMode = __ValidExecutionMode()